# ShellOrchestra Docker install, repair, and upgrade ## Official Docker install Use the preflight bootstrap for a supported managed installation and upgrades: ```bash curl -fsSL https://shellorchestra.com/install/docker-install.sh | sh ``` The preflight checks the current user's working rootless Docker/Podman and Docker Desktop/Podman machine before requesting privileges. Do not put `sudo` around the bootstrap command: a rootful profile requests it only after signed artifact verification. When exactly one managed profile is viable, the bootstrap selects that exact profile deterministically; this is not a runtime fallback. When several profiles are viable, it stops before mutation and requires `SHELLORCHESTRA_INSTALL_PROFILE` with one exact printed name. The one-line command is intentionally pipe-safe. If no values are supplied, it uses the documented mainstream choices: `backend_direct`, signed updates and operational/security notices enabled, and privacy-preserving Community telemetry enabled. Each default is printed before mutation. Set `SHELLORCHESTRA_EXTERNAL_TRANSPORT=authorized_browser_relay`, `SHELLORCHESTRA_UPDATES_AND_NOTICES_ENABLED=no`, or `SHELLORCHESTRA_TELEMETRY_ENABLED=no` explicitly when a different choice is required. Rerunning the same bootstrap is the supported idempotent managed repair/upgrade entrypoint. It verifies the signed ShellOrchestra release metadata and artifact before applying changes. WSL profiles are explicitly nonpersistent: data and installation state can be lost when the WSL environment is removed or reset, so do not use a WSL profile for state that must persist. For a rootful profile, the managed layout is created under `/opt/shellorchestra` when that profile is available. The official artifact contains a prebuilt Docker image; the bootstrap loads it with `docker load` and does not build images on your host. The official layout installs: ```text /opt/shellorchestra/current -> /opt/shellorchestra/releases/ /opt/shellorchestra/config/ /opt/shellorchestra/staging/ /opt/shellorchestra/backups/ /etc/systemd/system/shellorchestra-updater.service ``` After install, open `http://127.0.0.1:7171` from the host or publish it through your private network / reverse proxy. For passkey mode, configure a stable HTTPS origin before first setup. For local-only/LAN setup, use the LAN-only setup flow. ## Legacy/manual rootful upgrade Keep this explicit command only for an existing legacy/manual rootful installation or when a runbook specifically directs it. It is not the normal install, repair, or upgrade path: ```bash curl -fsSL https://shellorchestra.com/install/docker-upgrade.sh | sudo sh ``` That script delegates to the local ShellOrchestra updater service. The updater independently verifies the signed manifest and artifact before applying the update. If the updater socket is not present, the command fails closed instead of guessing an unmanaged deployment layout. Prefer rerunning `docker-install.sh` for managed repair or upgrade. Official upgrades also load a prebuilt image from the verified release artifact; they do not run `docker compose build` on the host. The shell command itself does not parse unsigned release metadata to decide what to install. It asks the local updater to resolve the latest signed release from the verified manifest, then shows updater progress. Every signed release also has a static release notes page under `https://shellorchestra.com/releases//`; the in-product update banner links to that page before the operator starts the upgrade. That page includes the release key id and links to `keyring.json` for manual verification. The offline root public key is also published at `https://shellorchestra.com/releases/root-key.pem` for transparency, but clients trust their embedded root key rather than replacing trust from the website. When `docker-install.sh` finds an older unmanaged marker, it does not start, stop, or overwrite that layout automatically. If the expected legacy updater socket, protected credential, and installation state are all present, an interactive terminal offers **Start the existing legacy ShellOrchestra release** and **Update to the latest signed release and start ShellOrchestra**. The update choice invokes this existing `docker-upgrade.sh` helper; it does not invent a second update mechanism. In a non-interactive session the operator must set either `SHELLORCHESTRA_LEGACY_ACTION=start_existing` or `SHELLORCHESTRA_LEGACY_ACTION=upgrade_and_start` explicitly. If those updater prerequisites are absent, bootstrap explains that the layout remains manually managed and exits without changes. It never runs an unknown Compose file merely because it found a directory named `shellorchestra`. An **incomplete managed installation** is different: it has ShellOrchestra configuration or release directories but no current release and no installation state. This can happen when a prior signed install was interrupted before its final startup. Bootstrap reports the exact path and offers **Repair the incomplete installation with the current signed release and start ShellOrchestra**. The normal managed install path then validates and preserves the existing configuration and data directories. It never selects repair by default; in a non-interactive session set `SHELLORCHESTRA_INCOMPLETE_ACTION=repair` explicitly. ## Manual / unmanaged Docker install Use this path only when you want to manage Compose files yourself. ShellOrchestra will still check for new signed releases, but one-click upgrade is intentionally disabled because the local updater does not own the host layout. Manual operators should: 1. Verify the signed release manifest and artifact metadata: ```bash curl -fsSL https://shellorchestra.com/install/verify-release.sh | sh ``` The verifier downloads the ShellOrchestra release key and signed channel manifest over HTTPS. It is read-only: it does not install, unpack, start, or stop ShellOrchestra. 2. Download the `docker` artifact URL printed by the verifier. 3. Verify the downloaded artifact file before unpacking it: ```bash SHELLORCHESTRA_VERIFY_ARTIFACT_FILE=./shellorchestra-docker-.tar.zst \ curl -fsSL https://shellorchestra.com/install/verify-release.sh | sh ``` 4. Unpack the verified artifact into an operator-owned directory. 5. Review and edit `config.toml` explicitly. 6. Start with Docker Compose from that directory. Do not pipe an unmanaged release artifact into shell, and do not reuse the official updater apply script unless your host layout is `/opt/shellorchestra` with the official updater service. ## Manual / unmanaged Docker upgrade For unmanaged Compose deployments: 1. Stop ShellOrchestra with your existing Compose command. 2. Back up your config and persistent data directories. 3. Download and verify the new release manifest and Docker artifact. 4. Unpack the new artifact into a new directory. 5. Copy your reviewed config and data mounts into the new directory. 6. Start the new Compose directory. 7. Verify `/api/healthz` through your ingress. 8. Keep the previous directory until the upgrade is confirmed. ShellOrchestra does not silently migrate unknown Compose layouts. If you want supported one-click upgrades, reinstall or migrate to the official layout.