Installation

Self-hosted with Docker Compose, or managed by us.

You can install RANCAQ yourself on your own server with Docker Compose, or we can install and operate it for you. This page describes both options at a high level.

Two options

Option	Who operates it
Self-hosted	Your team runs RANCAQ on your own server with the Docker Compose profile included in the source code.
Managed	We install and operate RANCAQ for you.

Components

The reference Compose profile lives in the ops/compose directory and contains these services:

Service	Purpose
`postgres`	PostgreSQL 17 database.
`minio`	Object storage for attachments. It can be turned off if you use your own S3-compatible storage.
`migrate`	Runs the database migrations once, before the application starts. Also the place to run the `itsm` administration commands.
`api`	The application backend.
`worker`	Background jobs: fetching email, composing notifications, and sending them.
`web`	The agent console and requester portal.
`proxy`	Caddy reverse proxy (`proxy` profile). The console and API must share one address, so the application is opened through this service.

api, worker, and the itsm CLI are in a single image. api and worker connect to the database with an application role that is subject to Row-Level Security; the maintenance credentials exist only in the migrate service.

Self-hosted

Prerequisites

Docker Engine 24 or newer with Compose v2.
The RANCAQ source code on the server where you install it.
A POP3 and SMTP mailbox if you will use the email channel.

1. Prepare the configuration

cd ops/compose
cp .env.example .env

Open .env and replace every default value. In outline:

Variable	Contents
`POSTGRES_PASSWORD`, `ITSM_APP_PASSWORD`	The database maintenance password and the application role password.
`MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD`	The object storage account.
`ITSM_SECRET_KEY`	Key used to encrypt mailbox passwords. Required before a mailbox is used.
`ITSM_REPLY_KEY`	Key used for email reply-address tokens. Required before a mailbox is used.
`ITSM_PORTAL_BASE_URL`	The RANCAQ address that email recipients can open, used for links in emails.
`ITSM_ORG_NAME`	The name in the closing of notification emails.
`ITSM_FETCH_INTERVAL`, `ITSM_MAX_EMAIL_MB`	The mailbox polling interval and the size limit for inbound email.

The two email keys are 32 random bytes in base64. Generate each one once:

openssl rand -base64 32

Keep .env the way you keep database passwords, and do not commit it to a repository. If ITSM_SECRET_KEY is lost, every mailbox password has to be entered again.

A few other settings are read from the same environment:

ITSM_COOKIE_SECURE=true is required when RANCAQ is opened over HTTPS.
ITSM_S3_PUBLIC_ENDPOINT must be an object storage address that users' browsers can reach, because attachments are downloaded through signed links.
ITSM_MAX_ATTACHMENT_MB limits attachment size; the default is 10.

For HTTPS, replace :80 in the Caddyfile with your domain name, or put RANCAQ behind your own reverse proxy.

2. Start the services

docker compose --profile proxy up -d

The migrate service runs first and applies all migrations. api and worker only start after the migrations have completed successfully.

3. Create the first tenant and admin

The first account is created through the CLI, not through the API. This command creates a tenant, the baseline roles, and one tenant admin:

ITSM_BOOTSTRAP_ADMIN_PASSWORD='<initial-admin-password>' \
docker compose run --rm -e ITSM_BOOTSTRAP_ADMIN_PASSWORD migrate \
  itsm bootstrap-admin --tenant-slug <slug> --tenant-name "<company name>" \
  --admin-email <admin-email> --admin-name "<admin name>"

The password is passed through an environment variable so that it is not recorded in the shell history.

docker compose run --rm migrate itsm doctor

doctor checks the database connections, pending migrations, and the object storage configuration. Then open the RANCAQ address in a browser and sign in with the admin account you created. See Signing in and navigation.

5. Set up the tenant

From the Administration menu, continue in this order:

Day-to-day operations

All administration commands run through the migrate service:

docker compose run --rm migrate itsm migrate status
docker compose run --rm -v "$PWD/backups:/backup" -w /backup migrate \
  itsm backup itsm-$(date +%Y%m%d).dump

Backup. itsm backup backs up the database. Attachments in object storage are backed up separately, for example by copying the bucket or snapshotting the minio volume. Keep .env separate from the database backup files.
Restore. Stop api and worker, run itsm restore <file> through migrate, start both again, then run itsm doctor. Practice this restore before you rely on it.
Updates. Get the new version of the source code, then run docker compose --profile proxy up -d --build again. New migrations are applied before api and worker start.

Existing database and storage

If you already have your own PostgreSQL and object storage, the source code provides a Compose variant, docker-compose.remote.yml, that does not include postgres and minio. With this variant, you must prepare the database and the application role on your database server first, because the built-in role setup script only runs in the postgres service.

Managed

If you do not want to operate a server yourself, we can install and operate RANCAQ for you. Contact us to discuss your needs and terms.