Install Opfield

The public installer prepares the host, installs Docker when necessary, starts the complete Opfield stack, and hands configuration over to the browser. A normal first installation does not require you to create a Compose file or install Docker manually.

Choose an installation method

Method	Best for	What you review and run
Public installer — recommended	The shortest supported path and normal production updates	You can inspect or dry-run the installer; it installs Docker if needed, verifies signed release metadata, and creates the complete stack
Manual installation	Security reviews that do not permit piping a downloaded script into a shell	You install Docker, choose the release version, inspect the Compose foundation, generate secrets, and start every service yourself; digest verification is optional

Both methods deploy the same Opfield foundation. Choose manual installation without the installer script if your policy requires every downloaded artifact and command to be reviewed separately.

What you need before starting

Choose a dedicated Linux host or VM that meets the capacity requirements. The automatic Docker setup supports Debian, Ubuntu, Fedora, CentOS, and RHEL families. You also need:

• an account with root access or working sudo;
• outbound internet access to the Opfield update service, the license service (license.thesqlabs.com), container registries, and Docker package repositories; Opfield registers with the license service after its first start, and an installation that holds or held a paid plan authorizes every update there;
• curl and OpenSSL;
• a plan for the final Opfield URL and DNS record;
• inbound access to the web listener and Relay path described in Ports and network paths.

You do not need Docker Engine or Docker Compose preinstalled. If a working Docker installation is present, the installer reuses it. Otherwise, it configures Docker’s official package repository, installs Docker Engine and the Compose v2 plugin, and starts the Docker service. On hosts with conflicting distro or Podman compatibility packages, the Docker installation step may replace those packages, so use a dedicated Opfield host rather than a machine carrying unrelated workloads.

Install Opfield

Connect to the selected host and run:

curl -sSL https://thesqlabs.com/gateway/install.sh | bash

On a fresh interactive installation, choose how Opfield should listen on port 3000:

• Internal HTTPS is the default. Opfield uses a certificate issued by its own System CA.
• HTTP is appropriate when a trusted reverse proxy terminates TLS and the internal hop is deliberately plaintext.

For a non-interactive installation, HTTPS is selected automatically. You can make the choice explicit:

# Internal HTTPS, also the default
curl -sSL https://thesqlabs.com/gateway/install.sh | bash -s -- --https

# HTTP behind a trusted TLS-terminating proxy
curl -sSL https://thesqlabs.com/gateway/install.sh | bash -s -- --http

If you want to inspect the selected signed release and planned actions without changing the host, run a dry run:

curl -sSL https://thesqlabs.com/gateway/install.sh | bash -s -- --dry-run

What the installer changes

The default installation directory is /opt/gateway. The installer verifies the selected release, writes the environment and Compose foundation, pulls immutable application and Relay images, creates persistent storage, and starts Opfield, PostgreSQL, Redis, the local Relay member, and the private internal registry required by supported build workflows. PostgreSQL, Redis, and the registry are pinned by digest and pulled from the Opfield image mirror on ghcr.io first, with Docker Hub as a fallback.

Treat this host as part of Opfield’s trusted computing base. The application intentionally receives Docker-host control for signed updates, recovery, housekeeping, and optional managed services. Isolate Opfield in its own VM or dedicated trusted host; do not colocate unrelated workloads or credentials on it.

Finish in the browser

When the stack becomes healthy, the terminal prints:

• the URL to open;
• the Opfield System CA fingerprint;
• a one-time setup code valid for 24 hours;
• a reset command that issues a replacement code if setup expires.

The plaintext setup code is shown once and is not stored in .env or the database. Enter it only in the Opfield setup page; do not paste it into chat, tickets, logs, or screenshots. The browser wizard configures the canonical URL, node-network endpoints, authentication, the first administrator, structured logging, and optional AI Workspace. Setup does not need a paid license; structured logging stays off until the license includes it (Business and Enterprise).

Continue with Initial setup after the installer finishes.

Verify the installation

The install is complete when the browser setup page opens and the stack reports healthy services. For an operator-level check:

cd /opt/gateway
sudo docker compose ps

Every required service should be running. You can also verify the local health endpoint according to the selected transport:

curl -kfsS https://127.0.0.1:3000/health
# or, for an HTTP installation:
curl -fsS http://127.0.0.1:3000/health

Do not add production nodes until the wizard is complete, the canonical URL is correct, and a normal sign-in succeeds.

If installation fails

Read /tmp/gateway-install.log and the final installer message before retrying. A retry is safe after fixing a network, package, disk, or registry problem; the installer detects an existing installer-managed deployment and preserves persisted Opfield configuration during updates. A fresh installation that stopped before it showed the setup code is resumed by the next run instead of being treated as an existing deployment.

If services were created but Opfield did not become healthy, inspect bounded Compose status and logs from /opt/gateway rather than deleting volumes or regenerating credentials. Preserve .env, PostgreSQL, Relay identity/state, gateway_data, and the master encryption key. Removing these artifacts turns a recoverable install problem into data or identity loss.