Start the Docker demo

This guide starts Workspace from the published Docker Compose bundle. You do not need a local copy of the source repository. The demo is ready when /health/ready returns HTTP 200.

Use Server installation for a production deployment.

Prerequisites

You need Docker with docker compose, at least 4 GB of free memory, access to the Workspace release and container registry, and an empty working directory. The first image download and schema setup can take more than ten minutes.

Download the bundle

Open the Workspace server release overview and select the required version. Download this asset for the Docker demo:

nucleus-server-7.30.0-docker-compose.tar.gz

The release offers several files. Use this mapping for the Docker demo:

Download SHA256SUMS into the same directory, then verify and unpack the archive:

sha256sum -c SHA256SUMS --ignore-missing
tar -xzf nucleus-server-7.30.0-docker-compose.tar.gz
cd nucleus-server-docker-compose

Continue only when the checksum command reports OK for the Docker archive. The bundled compose.yaml pins the matching release image.

Start Workspace

chmod +x start.sh
./start.sh start --detach
./start.sh status

The wrapper creates protected local configuration and database-secret files, starts PostgreSQL and Workspace, and preserves existing configuration and volumes. Follow progress in a separate terminal:

./start.sh logs

Establish TLS trust

On first start, Workspace creates data/nucleus.crt and data/nucleus-tls.key. The certificate is the public trust anchor for the local demo. Keep the server-side TLS key on the server with mode 0600; never copy it into a browser, CLI client, or MCP configuration.

Check the server-side certificate contract first:

./start.sh doctor

The Doctor checks readability, the validity period, SAN coverage, and whether the certificate matches the server-side TLS key. It then calls the health endpoints with data/nucleus.crt. Missing browser trust is a separate client setup step, not a server outage.

Browser and operating system

Import data/nucleus.crt into the browser or operating-system trust store before opening the sign-in page. In Chrome, open chrome://certificate-manager/localcerts/usercerts, import the certificate as a local user certificate, and restart Chrome if necessary. Your organization may manage the trust store centrally on managed devices.

Host CLI and nucli

Browser trust does not automatically apply to command-line programs. Use the absolute certificate path for those clients:

export WORKSPACE_URL=https://localhost.alvine.dev:8443
export SSL_CERT_FILE="$(pwd)/data/nucleus.crt"
curl --cacert "$SSL_CERT_FILE" -sS -i "$WORKSPACE_URL/health/ready"
nucli --host "$WORKSPACE_URL" discovery
nucli --host "$WORKSPACE_URL" login --email <system-admin-email>

Discovery must report the running Workspace version before you start login.

MCP process

An MCP client launches nucli mcp serve as a separate process. Pass the absolute certificate path in that process environment as well:

{
  "mcpServers": {
    "nucleus": {
      "command": "nucli",
      "args": ["--tenant", "<tenant-alias>", "mcp", "serve"],
      "env": {
        "SSL_CERT_FILE": "/absolute/path/nucleus-server-docker-compose/data/nucleus.crt"
      }
    }
  }
}

The process communicates over stdio and does not open an HTTP port. When started manually, no output means it is waiting for MCP messages. Setup is complete when the MCP client can list the available tools.

Check readiness

Set WORKSPACE_URL to the public URL shown by the bundle, then run:

curl --cacert ./data/nucleus.crt -sS -i "$WORKSPACE_URL/health/live"
curl --cacert ./data/nucleus.crt -sS -i "$WORKSPACE_URL/health/ready"

live = 200 with ready = 503 means that the runtime is active while setup is still in progress. Open $WORKSPACE_URL/login only after Readiness returns 200.

Take over first-access credentials safely

On the first start, start.sh prints only the path data/bootstrap-credentials.json. The file has mode 0600 and contains exactly the fields email, password, and apiKey. Open it only in a protected local shell and transfer the values directly to the approved secret manager. Do not copy any value into an agent session, chat, or log.

Verify a fresh sign-in with email and password. Remove the file only after that sign-in succeeds. A restart does not regenerate it. If the file is lost before the protected handoff, use only the documented recovery procedure in numin with the matching numin version. Do not reconstruct the credentials from files or directly from the database. Tenant creation remains a separate step.

If Workspace displays the EULA during first system access, an authorized representative must review and accept it in the browser. nucli, MCP, and other headless clients cannot perform this step. See Understand the EULA and commercial host status for details.

Test a local storefront domain with DNS TXT

The bundle contains an optional CoreDNS and Caddy overlay for shop.localhost.alvine.dev. The base wrapper does not enable it. Start only after ./start.sh doctor succeeds.

Follow Set up a local storefront domain for the complete local CA, DNS TXT verification, domain binding, and HTTPS check. That guide also explains why a tenant domain does not belong in the setup field System Domains (CSV). In that label, CSV means comma-separated administration hostnames, not a file upload.

Diagnose or stop the demo

./start.sh doctor
./start.sh logs
docker compose down

docker compose down keeps the data and configuration. Remove volumes only when you intentionally want to reset the complete demo.

Success criteria

The demo is ready when PostgreSQL and Workspace are running, /health/ready returns HTTP 200, and the System Admin sign-in page opens. Tenant creation is a separate step after server Readiness.

Next steps

• Follow From the Docker demo to the first live site for the complete path to the first published site.
• Create the first tenant with Create a tenant.
• Set up a local public host with Set up a local storefront domain.
• Build and publish the first site with Review and publish a CMS site.
• Read Server installation for the complete deployment contract.
• Plan release changes with Run product updates without manual repair.