Quick start

Install Citadel on a Linux machine with Docker, create your administrator account, and deploy your first application. Start Citadel with Docker Compose in the terminal, then complete setup in your browser.

You need: Docker, Docker Compose version 2.30 or newer, curl, and a text editor. Check with docker --version, docker compose version, and curl --version.

1. Start Citadel

Download the installation files into a new directory:

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

If repository access is restricted, use the signed-in download steps in the installation guide.

Open .env in a text editor. Leave CITADEL_IMAGE blank to select ghcr.io/citadel-p/citadel:latest, or set an accessible published image address. Set PG_PASSWORD to a long, unique password containing letters and numbers, without surrounding quotes, and save the file. This is the database password; you will choose your sign-in password separately.

Start Citadel:

docker compose pull
docker compose up -d
docker compose ps

The first image download can take several minutes. Wait until server and pg_db are healthy. If either fails, use the troubleshooting guide.

This setup listens only on this machine. It gives Citadel administrative access to its Docker engine. Follow the installation guide before making Citadel available to other people over a network.

2. Create your account

Open http://localhost:18000 on the machine where Citadel is running. Enter your name, email, and a password of 15 to 128 characters, then select Create administrator.

There is no default username or password. If you see the sign-in page instead, this installation already has an administrator. Ask that administrator for your account details before continuing.

3. Connect Docker

1. Open Platforms and select Add Platform.
2. Select Docker Standalone as the platform type and Local as the connector.
3. Name it local-docker and select Save. Names use 3 to 64 letters, numbers, hyphens, or underscores.
4. Wait for it to come online, then open it to see the containers on this host.

A Platform is a Docker host that Citadel manages. You do not need an Agent for this local setup. See connect a platform to connect another machine.

4. Run an application

1. Open Deployments and select Add Deployment.
2. Name it hello-web and choose local-docker.
3. Set Image Source to External, choose Docker Hub, and enter nginx:alpine.
4. Under Networks, select bridge.
5. In the Ports editor, enter 8080:80/tcp. This publishes host port 8080 to container port 80. Choose another host port if 8080 is in use.
6. Select Save, then Deploy. Enter hello-web in the confirmation dialog, select Deploy, and wait for the operation to finish.
7. Open http://localhost:8080. You should see the Nginx welcome page.

Port 8080 makes this example website reachable on the Docker host. Its firewall controls who else can reach it. Citadel itself stays on port 18000.

What next?

• Deploy a Compose Stack for an application with several services.
• Explore resources to learn about backups, builds, and Git repositories.
• Follow a guide to configure access, secrets, and integrations.
• Secure network access before sharing this installation.

To stop Citadel while keeping its accounts and settings, run docker compose stop from your citadel installation directory. To start it again, run docker compose up -d. Avoid down -v: it deletes the database and Citadel data volumes.