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 filesCopy Anchor Link

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

The commands below target native Linux with rootful Docker. Open a root shell with sudo -i first so the installation directory and files have the ownership required by the updater. For rootless Docker, use the daemon user's own directory and the supported socket/data mounts; do not run these commands with sudo. See update setup requirements.

mkdir -p /opt/citadel
cd /opt/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 the Compose file and .env in this directory.

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 CitadelCopy Anchor Link

Open .env in a text editor and set PG_PASSWORD to a long, unique password containing letters and numbers, without surrounding quotes. You can generate one with openssl rand -hex 32. This is the only required setting and is separate from your Citadel sign-in password.

If port 18000 is already in use, uncomment CITADEL_HTTP_PORT and choose another port. The local browser URL follows that port automatically.

Compose uses ghcr.io/citadel-p/citadel:latest by default. To pin a version, add CITADEL_IMAGE with 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 accessCopy Anchor Link

The supplied .env uses local HTTP. Its default browser address is http://localhost:18000; only the browser/API port is published, bound to 127.0.0.1. Edge Agent host access is optional; see Edge Agent access.

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 CITADEL_PUBLIC_URL to the browser address users will actually open. Whenever Core uses HTTPS—through a reverse proxy or with its own certificate—it also requires an HTTPS CITADEL_EDGE_PUBLIC_GRPC_URL, even when you do not use Edge Agents. In that case, set it to the same HTTPS URL as CITADEL_PUBLIC_URL; no Edge port publication or gRPC proxy route is needed. Before connecting Edge Agents, configure it to the reachable gRPC endpoint and enable the corresponding route or port publication.

For a complete reverse-proxy setup using the same Compose installation, follow Reverse proxy with Caddy.

3. Start and checkCopy Anchor Link

For local HTTP, run from your citadel installation directory:

docker compose up -d

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 up -d

The overlay mounts the certificate directory; the base Compose file controls the browser host binding and port. For Edge Agents, also include the Edge overlay as shown in the TLS guide. Include your overlays in later Compose commands too. For a reverse proxy, use the Compose commands in your chosen proxy guide.

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. Automatic update setupCopy Anchor Link

The supplied Compose file configures updates automatically after you create the administrator account. Core verifies the Compose files, running containers and database identity, then enables in-app Core and bundled PostgreSQL updates. No Python scripts, extra setup command or update settings in .env are required. Neither Core nor PostgreSQL is restarted by registration. Installing an update still requires the normal approval; PostgreSQL updates require explicit approval.

Update registration and recovery files live in .citadel-updates beside your Compose file. Keep this directory with your installation; do not delete it or edit its contents. Compose mounts it read-only into Core; short-lived updater helpers access it on the Docker host when needed.

Custom layouts must satisfy the supported update profile. If automatic setup cannot finish, check docker compose logs server, correct the reported issue, and restart Core with docker compose restart server to retry. See setup recovery.