Deploy with Docker Compose

The packaged Compose path creates one isolated OpenCircle stack: the OpenCircle Server, the Logto identity service, two PostgreSQL services, persistent volumes, and one first owner. Run it on your own machine or on a Docker host reached over SSH.

Choose your setup path

Pick one route for a new Server. Once its owner exists, use Server admin to change keys rather than running the other setup path.

• Manual: create a profile, deploy with browser claim, add keys in Server admin afterward. No config file needed.
• Automated: create a profile, then use a protected config file to create the owner and optionally supply keys.

Either way you need the OpenCircle CLI, Docker Engine with the Compose plugin, and a password manager. A remote deployment also needs a dedicated operator SSH key, an SSH-reachable Docker host, DNS, and firewall preparation.

Create a profile

Local Docker

opencircle profile add my-server \
  --transport=local --lifecycle=compose \
  --instance-id=my-server --yes

Remote SSH / Docker

opencircle profile add my-server \
  --transport=remote --lifecycle=compose \
  --instance-id=my-server \
  --ssh-host=203.0.113.10 \
  --ssh-user=operator \
  --ssh-identity-file="$HOME/.ssh/opencircle_operator" \
  --remote-path=/opt/opencircle \
  --domain=circle.example.org \
  --base-url=https://circle.example.org \
  --https=letsencrypt \
  --acme-email=operator@example.org \
  --yes

Do not invent a port; the named instance allocates its own collision-safe bundle. For a public host, complete Deploy to a Linux server before creating this profile; for a private network with no HTTPS, use Run OpenCircle on one trusted LAN instead of adapting this command to a plaintext address.

Deploy and claim

opencircle deploy \
  --profile my-server \
  --owner-mode claim \
  --finish guide

This verifies the signed stable Server manifest and selects its exact image before creating any state. --owner-mode claim opens browser setup even when a config file already exists — the file is simply not used on this path. Deployment counts as complete only once the target reports owner-bound; follow Create the first owner to finish claiming it.

Afterward, sign in as an Owner or Admin and add keys in Server admin → API Keys — see Add your API keys.

Automated setup with a protected file

Download and fill the local setup file with the permanent owner password, approval PIN, and any provider keys you want set at creation time. Save it with restrictive permissions outside any backup path, then choose a new result filename the CLI can write recovery codes to.

opencircle deploy \
  --profile my-server \
  --owner-mode config \
  --owner-config "$HOME/.config/opencircle/deploy.toml" \
  --owner-result "$HOME/.config/opencircle/my-server-owner-result.json" \
  --finish guide

Require owner-bound and the recovery result path in the output, and save the one-time codes from that private file. For unattended runs add --json --no-open-browser. If interrupted, follow the exact resume command the CLI prints, keeping the same config and result paths — do not switch owner modes or delete an existing result to retry.

Day two

opencircle logs --profile my-server --follow
opencircle upgrade --profile my-server
opencircle destroy --profile my-server

upgrade is the safe day-two transaction with backup, acceptance, and rollback. A soft destroy preserves volumes; opencircle destroy --hard --yes is destructive and removes both volumes and first-owner custody. Read Protect connections and secrets and Advanced operations before moving important work onto this Server.