Skip to content

Deploy OpenCircle

Run OpenCircle on one trusted LAN

Deploy through SSH and connect a desktop client over bounded, unencrypted LAN HTTP.

This is a bounded path for an OpenCircle Desktop client and a Linux Docker host on the same trusted network. The operator manages the host over SSH; the client reaches the Server over plain HTTP. OpenCircle does not currently offer a supported HTTPS mode for this topology.

Trusted does not mean encrypted. HTTP exposes sign-in traffic, session tokens, and Server data to anyone who can observe that network. Never use this route on guest Wi-Fi or a shared building network — use a hosted HTTPS deployment instead.

What this topology supports

Use a remote Compose profile even when the Linux host sits next to you; that profile advertises the SSH host name in the generated URLs, while a local profile advertises localhost and cannot be shared by editing its ports afterward.

  • one stable LAN host name every participating computer resolves the same way;
  • remote Compose lifecycle management over a pre-authorized SSH key;
  • protected, config-mode first-owner creation through the SSH loopback; and
  • an OpenCircle Desktop client pointed at the exact HTTP Server URL from the deployment receipt.

It does not support browser claim, mobile clients, a browser workbench on the LAN origin, or Internet exposure.

Prepare the host and create a profile

Prepare the LAN and host

  • Give the host a stable address and a LAN DNS name such as circle-lan.example that every device resolves the same way. Do not configure router port forwarding.
  • Install Docker Engine and the Compose plugin, and give a dedicated operator account permission to use Docker and write the deployment directory.
  • Pre-authorize a dedicated SSH key for that account, and confirm its host-key fingerprint through a trusted channel before saving it.

Create a LAN profile

Terminal

opencircle profile add lan-server \
  --transport=remote --lifecycle=compose \
  --instance-id=lan \
  --ssh-host="$OPENCIRCLE_LAN_HOST" \
  --ssh-user=operator \
  --ssh-identity-file="$OPENCIRCLE_SSH_IDENTITY_FILE" \
  --remote-path=/srv/opencircle \
  --https=off --yes

Do not add a public domain, https=letsencrypt, or a hand-written base URL to this profile. OpenCircle derives the HTTP Server and identity-service endpoints from the SSH host and the allocated Compose ports.

Contain the published ports

  • Permit SSH only from administrator devices, and begin with every application port denied at the upstream firewall.
  • After deployment reports owner-bound, permit only the exact Server and identity-service ports from the receipt, and only from the trusted LAN range.
  • Never expose database ports or the identity-service admin port, and never create public DNS records for this host.

Claim the first owner and connect a client

The browser claim endpoint rejects non-loopback HTTP, so create the owner through the protected config file instead:

Terminal

opencircle deploy \
  --profile lan-server \
  --owner-mode config \
  --owner-config "$HOME/.config/opencircle/deploy.toml" \
  --owner-result "$HOME/.config/opencircle/lan-owner-result.json" \
  --finish guide --json --no-open-browser

Require owner-bound, save the recovery codes and permanent credentials, then apply the LAN-only firewall rules before connecting Desktop from a second computer on the same network. Copy the exact http:// Server URL from the receipt, confirm the plaintext warning names the host you prepared, and sign in with the existing owner account — there is no claim page on this path.

For Web, mobile, public access, or transport confidentiality, choose an HTTPS deployment from Choose a deployment instead.