Home Download FAQ / Knowledge Base Screenshots Documentation Support

Installing and running Citadel using the Docker container

The entire Citadel system is now available as a Docker image. The container image is downloadable from Docker Hub:

Currently we are offering AMD64, i386, ARMv7, and ARM64 builds.

How to run a test installation

First, install Docker Engine (of course):

With Docker running, to begin deploying Citadel, execute the following commands:

mkdir /usr/local/citadel
docker run -i --rm --network host --volume=/usr/local/citadel:/citadel-data citadeldotorg/citadel

On the first run, it will download the Citadel container image. Subsequent runs will use the existing image.

That's it! Your entire Citadel system is now running. Try connecting to port 80 on your host. It's all there. Log in with username admin and password citadel (and change it of course).

How to run a permanent installation

mkdir /usr/local/citadel
docker run -d --restart=unless-stopped --network host --volume=/usr/local/citadel:/citadel-data --name=citadel citadeldotorg/citadel

Citadel will now automatically start and stop along with the Docker service.

Upgrading

To upgrade, simply download the latest container image with the following command:

docker stop citadel
docker rm citadel
docker pull citadeldotorg/citadel
docker run -d --restart=unless-stopped --network host --volume=/usr/local/citadel:/citadel-data --name=citadel citadeldotorg/citadel

Yes, you are removing the old container, but don't worry: your data is in the persistent volume, not in the container itself.

If you are running the "Snap" version of Docker...

If you are running the "Snap" version of Docker, which is common on Ubuntu systems, you might not be able to perform the bind mount to /usr/local/citadel and you will see a cryptic message about a read-only file system. This is because "Snap" can only access /var and /home. You can put your Citadel data in one of those places instead of /usr/local, or you can start the container with a volume mount instead of a bind mount. See your local documentation for the details on this.

For container experts...

If you're already a container guru and you want to run Citadel under kubernetes or some other cloud platform, here are the details of this container image:

Converting from Easy Install

You can easily move from the Easy Install distribution of Citadel to the Docker distribution, as long as you are on the same architecture (for example, 64-bit AMD/Intel). Simply stop the running Citadel installation and remove all files and directories except the following:

/usr/local/citadel/data
/usr/local/citadel/files
/usr/local/citadel/keys
/usr/local/citadel/messages

All other files in /usr/local/citadel may be deleted. /usr/local/ctdlsupport and /usr/local/webcit may be deleted in their entirety. Also be sure to delete any Citadel-related unit files in /etc/systemd/system.

After you've removed everything except your data, proceed with the installation as shown above. Your existing data will be preserved.

Usage -- other options

The container can also be launched in a few special modes. Please make sure it is not running in the background before launching it in any of these ways.

Compatibility test

docker run -i --rm citadeldotorg/citadel -c

The -c flag starts the container in a mode which tests it for compatibility with your system. It does not launch any services; it does not perform any disk or network operations. If the container package is compatible with your system, it will exit with a zero (0) error code.

Export and Import modes

The -e and -i flags cause the container to run ctdldump or ctdlload for migrating databases. For example:

docker run -i --network host --rm --volume=/usr/local/citadel:/citadel-data citadeldotorg/citadel -e >dump.dat
docker run -i --network host --rm --volume=/usr/local/citadel:/citadel-data citadeldotorg/citadel -i <dump.dat

As always, be careful with the dump and load utilities. Do not run either one while Citadel Server is running; shut it down first. And as always, be aware that ctdlload will overwrite any existing database on your system.

Database cleanup mode

docker run -i --rm [network, volume,etc.] citadeldotorg/citadel -d

The -d flag starts the container in database cleanup mode. In this mode, Citadel services are not started. The database_cleanup.sh script will be run interactively. This will "dump and load" your database, which is helpful if it has become corrupt for some reason. Please note that the dump will be saved to the container's writable layer, and then your mounted database will be deleted and re-loaded from the dump. Be sure you have enough disk space in both locations to do this.

Log verbosity

docker run -i [network, volume,etc.] citadeldotorg/citadel -x log_level

The -i flag increases the syslog verbosity of all Citadel services (any value from 1 to 9, with 1 as the default). If you wish to view the logs, you must capture the container's logging output in whatever manner is appropriate for your installation.

There are no social media links here. Enjoy a friendly Citadel community instead. Or go outside.