First-time install

This procedure walks through extracting the release bundle, loading the Docker image, configuring .env, and starting the stack. End state: the application is running on http://localhost:3000.

The full install is roughly seven commands. Plan on ten minutes once you have the package and your SECRET_KEY_BASE in hand.

Procedure

1. Open a terminal in the package directory

PowerShell, Windows Terminal, Command Prompt, or Terminal.app all work. Navigate to wherever the deployment archive landed.

2. Extract the package

tar -xzvf <package-name>.tar.gz

Replace <package-name> with the actual filename. Both .tgz and .tar.gz extensions are supported.

3. Change into the extracted directory

cd <extracted-directory>

The archive expands into a directory matching the release name. All remaining commands run from inside it.

4. Load the Docker image

docker load -i docker-images/<image-archive>.tgz

The image archive lives inside docker-images/ in the extracted folder. This imports it into Docker Desktop's local store so Compose can find it without reaching out to a registry.

5. Create the runtime .env

cp .env.example .env

(On Windows Command Prompt: copy .env.example .env.)

6. Edit .env

notepad .env       # Windows
open -e .env       # macOS

Two values must be filled in. Everything else can stay at its default for an evaluation install:

POSTGRES_PASSWORD=<your-postgres-password>
SECRET_KEY_BASE=<key-provided-with-package>

Pick a strong PostgreSQL password and write it down — it isn't recoverable. Paste the SECRET_KEY_BASE value the software distributor provided exactly as given.

The full template:

# Application port
APP_PORT=3000

# Database password
POSTGRES_PASSWORD=<your-postgres-password>

# Rails secret key base
SECRET_KEY_BASE=<key-provided-with-package>

# SSL — leave false for a local install. Set true when fronted by a TLS-terminating reverse proxy.
RAILS_FORCE_SSL=false
RAILS_ASSUME_SSL=false

# Local Docker — disable in production deployments behind a proxy.
RAILS_DISABLE_ORIGINS=true
RAILS_DISABLE_CSRF_PROTECTION=true

# Cameo API reachable from inside Docker via the Windows/macOS host
CAMEO_API_BASE_URL=http://host.docker.internal:1150

Save and close. Do not leave <your-postgres-password> or <key-provided-with-package> placeholders in the file.

7. Save a portable copy of .env

cp .env ../.env

(Command Prompt: copy .env ..\.env.)

This puts a copy one directory above the extracted folder so the next release can reuse it without re-editing. See redeploy.md for how that works.

8. Start the stack

docker compose up -d

Detached mode — Compose starts the containers and returns control to your terminal. The containers keep running until you explicitly stop them.

Validation

Confirm the services are up:

docker compose ps

You should see all services in a running or healthy state.

Open the app in your browser at http://localhost:3000. (If you set a non-default APP_PORT, swap your value in.)

Stopping the stack

docker compose down

Stops and removes the containers but preserves the database volume — your data survives the next start.

Security notes

  • Treat .env as a secret. Don't commit it, share it casually, or paste it into chat.
  • Pick a unique PostgreSQL password per install. Don't reuse credentials across customers or evaluation hosts.
  • CAMEO_API_BASE_URL=http://host.docker.internal:1150 assumes the Cameo API is reachable on the host at port 1150. If your network differs, update the URL.
  • APP_PORT=3000 is the default. Change it if 3000 is already taken on the host.