Automatic Deployment

Install Operaide with one command. The installer fetches itself from an existing Operaide deployment and installs the version running there. It asks for the install location, registry login, optional reverse proxy and TLS, audit token, and login method, then starts the first instance.

curl -fsSL https://your-operaide.example.com/install/install.sh | bash

For full control over the compose file and environment, use Manual Deployment instead. System requirements and network rules are in the parent guide.

Prerequisites

• Ubuntu or Debian server with root access (run the command as root).
• Outbound HTTPS to the Operaide deployment you install from. The install bundle is served from there.
• Outbound HTTPS to the container registry you choose (Azure ACR or GHCR).
• An audit token (oprd_...) from objective partner.
• With the bundled Caddy reverse proxy: ports 80 and 443 reachable from the internet, plus DNS records pointing your hostnames at the server.
• Without Caddy: your own reverse proxy in front of the instance.

How It Works

The script self-pairs with the deployment it came from. The Operaide server rewrites the bundle source URL into the script at download time, so operaide self-update later pulls updates from the same deployment. A staging install from a staging deployment gets staging updates; a production install gets production updates.

The script first asks where to install (default /opt/operaide). After download, it verifies every bundled file against a manifest of sha256 hashes before installing under that directory in install/.

At runtime, one Caddy container reverse-proxies to one container stack per instance. Only Docker and a few helpers are installed natively; Caddy and every instance run under Docker.

                Internet / intranet
                       |
                  :80 / :443
                       v
+-------------------------------------------------------------+
|  Host (Ubuntu / Debian, root)                               |
|  native via apt:  docker   ufw   curl   jq   python3        |
+-------------------------------------------------------------+
        |
        |  everything below runs in the Docker daemon
        v
+-------------------------------------------------------------+
|  Caddy container        network_mode: host                  |
|  binds :80 / :443       imports instances/*/Caddyfile       |
|  terminates TLS         routes by hostname                  |
+-------------------------------------------------------------+
        |                          |
   reverse_proxy              reverse_proxy
   localhost:9090             localhost:9091
        v                          v
+----------------------+   +----------------------+
| instance A           |   | instance B           |   ... (n)
| app container :7077  |   | app container :7077  |
| embedded MongoDB     |   | embedded MongoDB     |
| host bind            |   | host bind            |
| 127.0.0.1:9090       |   | 127.0.0.1:9091       |
+----------------------+   +----------------------+

On-disk layout (host, default location):
  /opt/operaide/
    install/    verified bundle, source of the operaide CLI
    .config     BUNDLE_BASE_URL, REGISTRY, USE_CADDY, TLS, mail, ports
    caddy/      compose.yml, Caddyfile, certs/  (only when Caddy is on)
    instances/<project>/   .env, compose.yml, Caddyfile, tls.crt/tls.key

The operaide command is on PATH at /usr/local/sbin/operaide (a symlink into install/), so it runs from anywhere as root.

Each operaide add creates one instance stack: an app container with embedded MongoDB, a host port (auto-incremented from 9090), and a Caddy snippet that routes its hostname to that port. The single Caddy container imports every snippet.

With Caddy off, the Caddy box drops out. Your own reverse proxy targets the instance host port, and bind_addr decides whether that port is 127.0.0.1 (proxy on the same host) or 0.0.0.0 / a LAN IP (proxy elsewhere).

Server Setup Prompts

Before fetching the bundle, the installer asks for the install location (default /opt/operaide). After the bundle is verified, the setup phase asks:

1. Registry: Azure Container Registry (default) or GHCR. You enter a username and token; the script runs docker login.
2. Caddy reverse proxy: yes installs Caddy. No leaves TLS and routing to your own proxy.
3. TLS certificate (Caddy only): keep automatic Let's Encrypt (default), or provide your own wildcard certificate and key (PEM) that covers all instances. Use your own when the server cannot reach Let's Encrypt or your policy requires an internal CA.
4. Mail: SMTP URL and sender address.
5. Domain (Caddy only): a base domain and an optional prefix, for example demo for *.demo.example.com.
6. Firewall: opens ports 22, 80, and 443, then enables ufw on confirmation.

The setup phase then runs the first instance creation.

Setup gathers all answers first, shows a summary (secrets masked), and asks you to confirm before it changes anything; the registry login is validated first. A wrong answer or an abort leaves nothing half-configured. If setup stops partway, run it again (the same curl command, or operaide setup once the command is installed) - it reuses saved answers and asks only for what is missing.

Instance Prompts

Each instance (the first one during setup, and every later operaide add) asks:

1. Project name: lowercase, alphanumeric, hyphens.
2. Image tag: the Operaide version to run, for example operaide-v3.0.5.
3. Hostname: derived from project and domain when Caddy is on, or entered directly when Caddy is off.
4. TLS certificate (Caddy only): optional. Provide a certificate and key for this instance to override the global certificate or Let's Encrypt; otherwise the instance falls back to whichever was set at setup.
5. Audit token: required. See parent guide: Installation Identity.
6. Login method, three independent switches:
   • Built-in email and password login on or off.
   • OpenID Connect SSO on or off. With SSO on, you enter the discovery URL, client ID, client secret, and provider type. See SSO Setup.
   • External HTTP Basic auth backend on or off. Offered only when built-in email login stays on, because it reuses the same login form. See External Password Login.
   • Public self-registration on or off. Offered only when built-in email login stays on and HTTP Basic is off, since HTTP Basic provisions accounts on first login. Default off, invite/admin-only; with it off and no SSO, nobody can sign in as the first user.

The instance starts and a health check confirms it responds. With Caddy on, the script prints the DNS record you need to create.

Managing Instances

After setup, operaide is on PATH. Run it from anywhere as root:

Command	Action
operaide add	Add a new instance
operaide remove <project>	Stop and remove an instance
operaide update <project> <tag>	Switch an instance to a different image tag
operaide list	List instances and status
operaide start|stop|restart|logs <project>	Runtime control
operaide version	Show the installed bundle version and template status
operaide self-update	Fetch a newer bundle from the source deployment
operaide setup	Re-run base setup; resumes an incomplete install
operaide help	Full command list

Updating

operaide self-update

This fetches the manifest from the source deployment, compares versions, and only downloads when they differ. The new bundle is verified file by file before it replaces the live one. To move an instance to a newer Operaide image, use operaide update <project> <tag>.

Backups

operaide add asks whether to enable a daily backup cron for the instance. Backups land on the host under the instance's backup/ directory. Encryption and off-site transport are your responsibility.

See Backup and Restore for the full backup system, transport options, and restore procedure.

Common Mistakes

• Running the script from a local copy. The bundle source URL is injected by the server at download time. A script that still contains the __INJECTED__ placeholder was not served by an Operaide deployment and aborts. Always run it via curl from your deployment.
• Enabling HTTP Basic with email login disabled. The HTTP Basic backend reuses the email and password form. The installer does not offer it when built-in email login is off.
• Skipping the DNS record with Caddy on. Caddy provisions a certificate only after the hostname resolves to the server. Create the A record before expecting HTTPS.