CT-Ops

Install CT-Ops

Production-ready CT-Ops installation guidance for a single-host Docker deployment.

This guide takes a new CT-Ops deployment from an empty host to a working web UI, healthy ingest service, and an enrolled agent. Use the release-bundle install for normal server deployments. Build from source only when you are developing CT-Ops itself or need to modify the images.

Deployment shape

The standard install runs CT-Ops as a single Docker Compose stack.

Agents need two routes back to the CT-Ops server: HTTPS to the web UI URL for agent binary downloads and updates, and TCP 9443 to ingest for registration, mTLS, heartbeats, checks, inventory, and tasks.

Prerequisites

No local Go, Node.js, or pnpm installation is required for the release-bundle path.

Install from the release bundle

Run the installer from the server that will host CT-Ops.

curl -fsSL https://forgejo.carrtech.dev/carrtech/ct-ops/raw/branch/main/install.sh | bash
cd ct-ops

To pin a specific release instead of taking the latest:

CT_OPS_VERSION=v0.3.0 curl -fsSL https://forgejo.carrtech.dev/carrtech/ct-ops/raw/branch/main/install.sh | bash
cd ct-ops

The installer downloads a small release bundle from Forgejo, verifies the published SHA-256 checksum, and unpacks docker-compose.yml, start.sh, .env.example, licence public-key material, and support-data collection tools.

First run

Run start.sh once to create .env from .env.example.

./start.sh

The first run intentionally exits after creating .env. Edit the file before starting the stack.

$EDITOR .env

At minimum, set the public URL values to your real deployment name.

BETTER_AUTH_URL=https://ct-ops.example.com
BETTER_AUTH_TRUSTED_ORIGINS=https://ct-ops.example.com
AGENT_DOWNLOAD_BASE_URL=https://ct-ops.example.com
REQUIRE_EMAIL_VERIFICATION=true

If nginx cannot bind to 80 or 443, set alternate host ports before the second run and include the external HTTPS port in every public URL.

NGINX_HTTP_PORT=8080
NGINX_HTTPS_PORT=8443
BETTER_AUTH_URL=https://ct-ops.example.com:8443
BETTER_AUTH_TRUSTED_ORIGINS=https://ct-ops.example.com:8443
AGENT_DOWNLOAD_BASE_URL=https://ct-ops.example.com:8443

If CT-Ops is behind a VM, LXC, Incus, NAT gateway, or cloud load balancer, forward the external HTTPS port and 9443 to the CT-Ops host. Agents must be able to reach both from their own network.

Second run

Start the stack.

./start.sh

On this run, start.sh:

• generates BETTER_AUTH_SECRET when it is blank
• generates POSTGRES_PASSWORD when it is blank
• generates the browser TLS certificate at deploy/tls/server.{crt,key} when missing
• generates the ingest gRPC certificate at deploy/dev-tls/server.{crt,key} when missing
• stamps digest-pinned image references into the compose environment when supplied by the release bundle
• pulls images
• runs migrations
• starts the web, ingest, nginx, database, and Solr services

Check service health.

docker compose ps

All long-running services should become healthy. If a service is unhealthy, inspect it before creating users or agents.

docker compose logs --tail=200 web
docker compose logs --tail=200 ingest
docker compose logs --tail=200 nginx
docker compose logs --tail=200 db
docker compose logs --tail=200 solr

.env reference

Anything marked security-critical affects authentication, trust boundaries, privileged endpoints, or credentials. Treat those values like passwords and keep .env out of tickets, chat, and screenshots.

Public URL and auth

Agent download and terminal connectivity

AGENT_DOWNLOAD_BASE_URL covers HTTPS downloads only. The agent gRPC address is supplied when creating or installing the agent and normally uses the same host with port 9443, for example ct-ops.example.com:9443.

Reverse proxy and ports

Database

Search

When CT-Ops writes data that contributes to global search, the web service also listens for PostgreSQL change notifications and queues a debounced Solr refresh for the affected instance. The periodic rebuild remains as a safety fallback for shared catalogue changes or missed notifications. Recurring Operations Calendar events are indexed by their next future occurrence, so recurring planning meetings remain searchable after the original series start date has passed.

Licensing

The current CarrTech licence verifier public key is baked into the web image and mounted from ./licence-keys/current.pem in customer bundles. Saved licences keep using the verifier key captured when they were activated.

Integrations

Load testing

Image overrides

Password Manager integration

Create the first admin account

Open your configured URL, for example https://ct-ops.example.com. If you are still using the self-signed certificate generated by the installer, your browser will warn until you replace deploy/tls/server.{crt,key} with a certificate from your own CA.

1. Click Register.
2. Create the first user.
3. Complete the standalone instance setup flow.
4. The first account becomes super_admin.

First agent

Use the dedicated CT-Ops Agents guide for production agent creation and rollout. It covers enrolment tokens, agent configuration, tags, global agent defaults, Debian and Red Hat based Linux installation, Windows installation, verification, updates, and uninstall behavior.

Build from source

Use this path when developing CT-Ops or validating changes before release.

git clone https://forgejo.carrtech.dev/carrtech/ct-ops.git ct-ops
cd ct-ops
make dev-tls
cp apps/web/.env.example apps/web/.env.local
docker compose -f docker-compose.single.yml up -d
docker compose -f docker-compose.single.yml exec web sh -c "cd /app && node_modules/.bin/drizzle-kit migrate"
make agent

For local agent execution and config details, use the CT-Ops Agents guide.

Operations

From a release-bundle install directory, run ./generate_support_data when opening a support request. It creates ct-ops-support-data-<timestamp>.tar.gz with redacted settings, Docker status, recent logs, host information, file metadata, and TLS certificate fingerprints. Review the archive before attaching it to a support request.

Stop or remove the stack:

# Stop the stack and keep volumes
docker compose down

# Stop the stack and remove volumes
docker compose down -v

Use down -v only when you intend to remove CT-Ops data from this host.

Troubleshooting