Installation

Prerequisites

Docker and Docker Compose
A domain name with DNS configured
Ports 80 and 443 available

You need three DNS records pointing to your server:

Record	Purpose
`your-domain.com`	Control plane web UI
`registry.your-domain.com`	Container image registry
`logs.your-domain.com`	Log aggregation (Victoria Logs)

Quick Start

Run the automated install script on a fresh server:

curl -fsSL https://raw.githubusercontent.com/techulus/cloud/main/deployment/install.sh | bash

The script detects your OS, installs Docker, walks you through DNS and environment configuration, and starts all services.

Manual Setup

Clone the repository and configure your environment:

cd deployment
cp .env.example .env
openssl rand -hex 32

Edit .env with your values. Set CONTROL_PLANE_UPDATER_TOKEN to the generated token. For an external PostgreSQL database, keep:

COMPOSE_FILE=compose.production.yml

Set TECHULUS_CLOUD_VERSION to the release tag you are installing:

TECHULUS_CLOUD_VERSION=vX.Y.Z

Use tip only for rolling installs. Rolling installs do not show release update prompts. Then start the stack:

docker compose -f compose.production.yml up -d --pull always --remove-orphans

To use the bundled PostgreSQL instead of an external database:

sed -i.bak 's/^COMPOSE_FILE=.*/COMPOSE_FILE=compose.postgres.yml/' .env
docker compose -f compose.postgres.yml up -d --pull always --remove-orphans

Production hosts should also cap Docker container logs. The installer creates /etc/docker/daemon.json with json-file rotation on fresh hosts. If Docker is already configured, keep your existing daemon settings and add equivalent log rotation manually.

Manual upgrades

Use the one-click upgrade flow in Settings when possible. If the updater cannot run, update the deployment from the host manually. Back up your .env file and database before upgrading. Then fetch the Compose files for the release, update TECHULUS_CLOUD_VERSION, pull images, and restart the stack:

cd /opt/techulus-cloud
TARGET_VERSION=vX.Y.Z
COMPOSE_FILE=$(grep -E '^COMPOSE_FILE=' .env | cut -d= -f2- || true)
if [ -z "$COMPOSE_FILE" ]; then
  COMPOSE_FILE=compose.production.yml
fi

cp .env ".env.backup.$(date +%Y%m%d%H%M%S)"
curl -fsSL "https://raw.githubusercontent.com/techulus/cloud/${TARGET_VERSION}/deployment/compose.production.yml" -o compose.production.yml
curl -fsSL "https://raw.githubusercontent.com/techulus/cloud/${TARGET_VERSION}/deployment/compose.postgres.yml" -o compose.postgres.yml

if grep -q '^TECHULUS_CLOUD_VERSION=' .env; then
  sed -i.bak "s/^TECHULUS_CLOUD_VERSION=.*/TECHULUS_CLOUD_VERSION=${TARGET_VERSION}/" .env
else
  echo "TECHULUS_CLOUD_VERSION=${TARGET_VERSION}" >> .env
fi

docker compose -f "$COMPOSE_FILE" pull
docker compose -f "$COMPOSE_FILE" up -d --remove-orphans

Rollback after migrations may require restoring the database backup before you restart older images. The Compose files include container health checks for visibility. Plain Docker Compose reports unhealthy containers but does not restart them automatically, so use the common commands below when investigating a self-hosted service.

Environment Variables

Required

Variable	Description
`ROOT_DOMAIN`	Your domain (e.g., `cloud.example.com`)
`ACME_EMAIL`	Email for Let’s Encrypt certificates
`DATABASE_URL`	PostgreSQL connection string (e.g., `postgres://user:pass@postgres:5432/techulus`)
`BETTER_AUTH_SECRET`	Secret key for authentication
`ENCRYPTION_KEY`	32 bytes as a 64-character hex string. Required unless you configure AWS KMS BYOK.

AWS KMS BYOK

AWS KMS BYOK is available for AWS-hosted dedicated control planes. The control plane can run in your AWS account or in the Techulus AWS account. Attach an EC2 instance profile or ECS task role to the web service. Do not store static AWS credentials in .env. Set these variables instead of ENCRYPTION_KEY for a new installation:

ENCRYPTION_KMS_KEY_ARN=arn:aws:kms:us-east-1:123456789012:key/your-key-id
AWS_REGION=us-east-1

The role needs kms:GenerateDataKey, kms:Encrypt, kms:Decrypt, and kms:DescribeKey for the configured key. Restrict the cryptographic operations to the role, the exact key, and this encryption context:

{
  "StringEquals": {
    "kms:EncryptionContext:techulus:purpose": "service-secret-dek"
  }
}

Control plane in the Techulus AWS account

You can keep the KMS key and compute agents in your AWS account while running the dedicated control plane in the Techulus AWS account. Grant the Techulus control-plane role direct cross-account access to the KMS key. The application uses that role through the standard AWS credential chain. It does not call AWS STS AssumeRole. Merge statements like these into the KMS key policy in your AWS account. Replace the account IDs and role name. DescribeKey is separate because that operation does not accept an encryption context:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowTechulusControlPlaneDescribe",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/techulus-control-plane-customer-name"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*"
    },
    {
      "Sid": "AllowTechulusControlPlaneCrypto",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/techulus-control-plane-customer-name"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Encrypt",
        "kms:Decrypt"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:EncryptionContext:techulus:purpose": "service-secret-dek"
        }
      }
    }
  ]
}

The Techulus control-plane role also needs this identity policy. Set Resource to the full ARN of your KMS key:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DescribeCustomerEncryptionKey",
      "Effect": "Allow",
      "Action": "kms:DescribeKey",
      "Resource": "arn:aws:kms:us-east-1:444455556666:key/your-key-id"
    },
    {
      "Sid": "UseCustomerEncryptionKey",
      "Effect": "Allow",
      "Action": [
        "kms:GenerateDataKey",
        "kms:Encrypt",
        "kms:Decrypt"
      ],
      "Resource": "arn:aws:kms:us-east-1:444455556666:key/your-key-id",
      "Condition": {
        "StringEquals": {
          "kms:EncryptionContext:techulus:purpose": "service-secret-dek"
        }
      }
    }
  ]
}

Configure ENCRYPTION_KMS_KEY_ARN with the customer-account key ARN and set AWS_REGION to that key’s region. Your compute agents do not need AWS credentials or KMS permissions. They continue receiving the data encryption key during registration. You can revoke future cold-start unwraps by removing the Techulus role from the key policy or disabling the key. This does not erase a key already cached by a running control-plane process or persisted by an existing agent. The first secret operation generates a 32-byte data encryption key. The control plane stores only its KMS-wrapped form in PostgreSQL. Each web process unwraps and caches the key when first needed. The secret ciphertext format and agent behavior remain unchanged. To migrate an existing installation:

Back up PostgreSQL and .env.
Add ENCRYPTION_KMS_KEY_ARN and AWS_REGION. Keep the existing ENCRYPTION_KEY temporarily.
Restart the web service and verify that you can reveal an existing secret and register an agent.
Remove ENCRYPTION_KEY and restart all web replicas.

When a wrapped key already exists, any remaining ENCRYPTION_KEY must contain the same key bytes. The control plane fails closed if they differ. Do not add a newly generated ENCRYPTION_KEY to an existing KMS installation. Do not change ENCRYPTION_KMS_KEY_ARN after initialization. Automatic rotation of the same KMS key is transparent. Moving to another KMS key requires a reviewed rewrap procedure. If KMS is unavailable, cold-started web processes return a service-unavailable response for secret operations and agent registration. Other control-plane features remain available. Warm processes and existing agents can continue using keys already held in memory or local agent configuration. Back up both PostgreSQL and continued access to the KMS key. Deleting the KMS key can make a database restore unrecoverable. Disabling the key blocks future unwraps, but it does not erase keys already cached by running processes or registered agents.

Control plane deployment

Variable	Description
`COMPOSE_FILE`	Compose file used by self-updates. Use `compose.production.yml` for external PostgreSQL or `compose.postgres.yml` for bundled PostgreSQL.
`TECHULUS_CLOUD_VERSION`	Installed release tag. Use `tip` only for rolling installs without release prompts.
`CONTROL_PLANE_UPDATER_TOKEN`	Random token used by the web app to call the internal updater service. Generate with `openssl rand -hex 32`.

Victoria Logs

Variable	Description
`VL_USERNAME`	Logs service username
`VL_PASSWORD`	Logs service password
`VL_RETENTION`	Log retention period (default: `7d`)

Victoria Metrics

Variable	Description
`VM_USERNAME`	Metrics service username
`VM_PASSWORD`	Metrics service password
`VM_RETENTION`	Metrics retention period (default: `30d`)

Registry

Variable	Description
`REGISTRY_USERNAME`	Registry username for agents
`REGISTRY_PASSWORD`	Registry password for agents
`REGISTRY_HTTP_SECRET`	Internal registry secret

Inngest

Variable	Description
`INNGEST_SIGNING_KEY`	Request verification key (prefix with `signkey-prod-`)
`INNGEST_EVENT_KEY`	Event API key

Control Plane Replicas

Variable	Description
`WEB_REPLICAS`	Number of control plane web containers to run (default: `1`)

When WEB_REPLICAS is greater than 1, Traefik discovers the replicated web containers through Docker and load balances requests for <ROOT_DOMAIN> across them. Schema sync runs once from the dedicated migrate service before the replicated web containers start, so scaling WEB_REPLICAS does not run migrations from every replica.

GitHub Integration (Optional)

Variable	Description
`GITHUB_APP_ID`	GitHub App ID
`GITHUB_APP_PRIVATE_KEY`	GitHub App private key (base64-encoded)
`GITHUB_WEBHOOK_SECRET`	Webhook secret

Generating Secrets

# Encryption key (64 hex characters)
openssl rand -hex 32

# Auth secret
openssl rand -hex 32

# Inngest signing key
echo "signkey-prod-$(openssl rand -hex 32)"

# Inngest event key
openssl rand -hex 16

Services

Once running, the following services are available:

Service	Endpoint
Web	`https://<ROOT_DOMAIN>`
Registry	`https://registry.<ROOT_DOMAIN>`
Logs	`https://logs.<ROOT_DOMAIN>`
PostgreSQL	Internal only
Inngest	Internal only

Traefik handles TLS termination and automatic certificate renewal via Let’s Encrypt.

Database Migrations

The schema is synced automatically by the one-shot migrate service via drizzle-kit push. Non-destructive changes (adding tables, columns, indexes) are applied automatically. Destructive changes like dropping columns require manual intervention. If schema sync fails, web startup is blocked; inspect the failure with docker compose logs migrate.

Common Commands

# Check service status
docker compose -f compose.production.yml ps

# View logs
docker compose -f compose.production.yml logs -f

# Stop all services
docker compose -f compose.production.yml down --remove-orphans

# Update to the configured image references
docker compose -f compose.production.yml up -d --pull always --remove-orphans

Use versioned or digest-pinned image references for production updates when possible. Mutable tags such as latest and tip are convenient, but they can move between pulls.

Core

Control Plane

Agents

Services

Deployments

Networking

Infrastructure

API

Prerequisites

Quick Start

Manual Setup

Manual upgrades

Environment Variables

Required

AWS KMS BYOK

Control plane in the Techulus AWS account

Control plane deployment

Victoria Logs

Victoria Metrics

Registry

Inngest

Control Plane Replicas

GitHub Integration (Optional)

Generating Secrets

Services

Database Migrations

Common Commands

​Prerequisites

​Quick Start

​Manual Setup

​Manual upgrades

​Environment Variables

​Required

​AWS KMS BYOK

​Control plane in the Techulus AWS account

​Control plane deployment

​Victoria Logs

​Victoria Metrics

​Registry

​Inngest

​Control Plane Replicas

​GitHub Integration (Optional)

​Generating Secrets

​Services

​Database Migrations

​Common Commands

Prerequisites

Quick Start

Manual Setup

Manual upgrades

Environment Variables

Required

AWS KMS BYOK

Control plane in the Techulus AWS account

Control plane deployment

Victoria Logs

Victoria Metrics

Registry

Inngest

Control Plane Replicas

GitHub Integration (Optional)

Generating Secrets

Services

Database Migrations

Common Commands