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

Download the installation files into a new directory:

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

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

Open .env in a text editor. 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.

Compose selects the published latest image automatically. If port 18000 is already in use, uncomment CITADEL_HTTP_PORT in .env and choose another port; use that port in the browser address below.

Start Citadel:

docker compose up -d

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

Open http://localhost:18000 on the machine where Citadel is running. Enter your username, 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.

Core automatically verifies the installation and enables in-app Core and bundled PostgreSQL updates after account creation. No extra command or Python scripts are needed, and registration does not restart either container. Database upgrades still require explicit approval. Keep the generated .citadel-updates directory beside your Compose file; it holds update registration and recovery state.

3. Connect DockerCopy Anchor Link

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

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?Copy Anchor Link

• 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.