Install and secure Citadel

Install Citadel and PostgreSQL with Docker Compose. You need a Linux Docker host, Docker Compose 2.30 or newer, curl, and a text editor. The installation uses published container images.

1. Download the installation files

For a new installation, create a directory and download the Compose file and environment template:

mkdir -p citadel
cd citadel
curl -fSL https://raw.githubusercontent.com/Citadel-P/Citadel/main/deploy/install/docker-compose.yml -o docker-compose.yml
curl -fSL https://raw.githubusercontent.com/Citadel-P/Citadel/main/deploy/install/.env.example -o .env
chmod 600 .env

Keep both files in this directory. For an existing installation, follow upgrade and rollback and keep your existing .env and Compose project name.

If the download returns 404 because repository access is restricted, open the installation folder while signed in to GitHub. Download docker-compose.yml and .env.example, save them in your installation directory, rename .env.example to .env, and run chmod 600 .env.

2. Configure Citadel

Open .env in a text editor and set:

• CITADEL_IMAGE: leave blank to use the default latest image tag, or set a complete published image address.
• PG_PASSWORD: a long, unique database password containing letters and numbers, without surrounding quotes. You can generate one with openssl rand -hex 32.

The database password is separate from your Citadel sign-in password. With CITADEL_IMAGE blank, Compose uses ghcr.io/citadel-p/citadel:latest. To pin a specific version instead, set it to the complete image address from your chosen release.

The selected image must be published and accessible to your Docker host. Restricted packages require registry access; a tag that has not been published cannot be pulled. If a download fails, check the image address and access before retrying, or use the source-development setup to build from a checkout.

Network access

The supplied .env uses local HTTP. Its default browser address is http://localhost:18000; both published ports bind to 127.0.0.1.

For a shared installation, choose one of these options:

Follow TLS and secure Agent transport for the full settings. Do not simply change the bind address to 0.0.0.0 while leaving local HTTP enabled. Set Transport__PublicUrl to the browser address users will actually open. If you use Edge Agents, also set EdgeAgent__PublicGrpcUrl to the separate address those Agents can reach.

3. Start and check

For local HTTP or a configured reverse proxy, run from your citadel installation directory:

docker compose pull
docker compose up -d
docker compose ps

For direct TLS, download the overlay described in the TLS guide and use these commands instead:

docker compose -f docker-compose.yml -f compose.direct-tls.yml pull
docker compose -f docker-compose.yml -f compose.direct-tls.yml up -d
docker compose -f docker-compose.yml -f compose.direct-tls.yml ps

The overlay mounts the certificate directory; the base Compose file controls host bindings and ports. Include the overlay in later Compose commands too.

Wait until server and pg_db are healthy. For the default local setup, open http://localhost:18000 on the Docker host and create your administrator account. There are no default credentials. If you installed on a remote server, use the HTTPS address you configured above.

Complete first-run setup, then connect your first Platform.

4. Protect your installation data

Keep .env private. Keep the citadel_data and postgres_data volumes: together they hold accounts, settings, history, and the keys used to protect saved secrets. Configure a control-plane backup and keep a copy away from the Docker host. Do not delete these volumes during an upgrade.

See requirements, configuration, and upgrade and rollback when planning a permanent installation.