Xibo for Docker
On this page
Xibo for Docker
Docker is an application to package and run any application in a pre-configured container. This makes it much easier to deploy a Xibo CMS whilst following our recommended configuration. We provide containers for x86-64/AMD64 architecture only. These are suitable for most servers.
Quick Start Guide
We have a complete worked example of installing a CMS on an Ubuntu 22.04 server in the guide here: Quick Start Guide
Docker on Linux
Docker is pre-packaged on many Linux distributions, and can normally be installed as follows:
apt install docker.io docker-compose
Alternatively, Docker can be installed on 64 bit Linux based systems by following the instructions on the Docker website for your particular Linux distribution. You should install the Stable build, and install Docker CE (Community Edition) unless you have a pre-existing Docker EE (Enterprise Edition) install or wish to explore that option.
- Instructions for Installing Docker can be found on the Docker website in the following location: Docker Install for Linux Distributions
- On Linux is it also necessary to install Docker Compose as it is not shipped with the above package. To do so visit Docker Compose README and follow the instructions there.
Download and extract the Xibo Docker archive
You’ll need to be the
root user to install Xibo.
rootin your command line shell either by running
sudo suor logging in as root directly.
The latest Xibo Docker installation files can be downloaded by clicking here.
- The archive should be extracted in a suitable location on your host machine we’d suggest
/opt/xibo. Your library content and database will be written under this folder.
Please note that the archive already contains a sub-folder called
xibo-docker-n.n.n, which is ‘best practice’ for archives.
For the subsequent instructions please make sure you are inside the sub-folder contained in the archive.
Check and edit configuration
The first time Xibo is installed a configuration file is needed to tell Docker how the environment is configured.
- This file is called
config.env. This file covers where you want files to be stored, email config, etc.
A template file with detailed instructions is provided in the release archive and is called
- Take a copy of this file, renaming to
config.envand then edit the file in a text editor, e.g. nano, gedit, etc.
If you don’t want Xibo to be able to send email messages, then you can omit to configure those options.
Docker will map data folders to contain database data and any custom files for the CMS. These will, by default, appear in the folder containing the release archive in a
Using different ports
By default, Xibo will start a web server listening on port 80.
- If you already have a web server listening on port 80 of your host machine, or would prefer to use an alternative port number, then you need to copy the
cms_custom-ports.yml.templatefile and change the
- The file should be saved as
Similarly, Xibo’s XMR server will be started listening on port 9505.
If you would prefer to use an alternative port number, then you’ll need to do so by copying the
cms_custom-ports.yml.templatefile and changing the
The ports section of a Docker Compose YML file lists ports in the format
<host>:<container>- to move to port 8080 the declaration would be
To use this file replace any
docker-compose up -d commands in the below instructions with
docker-compose -f cms_custom-ports.yml up -d.
docker-compose.yml file includes a container for MySQL, however, it is possible to run with an external/remote MySQL instance as the database for Xibo.
- To do this base the
config.envfile on the template
config.evn.template-remote-mysqland replace any
docker-compose up -dcommands in the below instructions with
docker-compose -f cms_remote-mysql.yml up -d.
Xibo should be run over SSL if running on anything other than a secure private network. The Docker containers do not provide SSL and this must be provided by an external web server which handles SSL termination and reverse proxy into the
There are many good resources for achieving this architecture, for example a nginx-proxy container could be used.
If you already have a web server running on your Host machine, configuring a reverse proxy should be straightforward.
VirtualHost for Apache is below, it assumes you’ve configured your custom ports for port 8080:
RequestHeader set X-Forwarded-Proto "https"
# Set the path to SSL certificate
# Usage: SSLCertificateFile /path/to/cert.pem
# Servers to proxy the connection, or;
# List of application servers:
# ProxyPass / http://[IP Addr.]:[port]/
# ProxyPassReverse / http://[IP Addr.]:[port]/
ProxyPass / http://0.0.0.0:8080/
ProxyPassReverse / http://0.0.0.0:8080/
Installing the CMS containers
Once you’ve made your changes to
config.env and have saved the file, open a terminal/command window in the folder where you extracted the archive.
- As a user who has permissions to run the
dockercommand, simply run:
docker-compose up -d
This will bootstrap and start your Xibo CMS.
- The CMS will be fully installed with the default credentials:
Log on to the CMS straight away and change the password on that account.
- You can log on to the CMS at
http://localhost. If you configured an alternative port number then be sure to add that to the URL, for example,
If you are running an iptables based firewall on your computer you will need to allow the ports you’ve configured the CMS to run on inbound.
If you haven’t specifically configured alternative ports, then the following is required:
- Inbound TCP Port 9505 (for XMR Push Messaging)
- Inbound TCP Port 80 (for HTTP Traffic) AND/OR
- Inbound TCP Port 443 (for HTTPS Traffic - if you are using SSL)
XMR - Push Messaging
Docker installs come with XMR running automatically for you, and with most of the configuration in place. However, you do need to adjust the XMR public address of the CMS, on first log in, as detailed below:
This only needs to be done on the first bootstrap.
- Navigate to the Settings page under the Administration section of the CMS main menu and selecting the Displays tab.
The XMR public Address field defaults to
tcp://cms.example.org:9505 which needs to be adjusted to be suitable for your network.
- The format of the address needs to be:
- The default
<port>is 9505 and should be set to that unless you have specified a custom port in your docker-compose configuration.
If your CMS is available by a DNS name - for example, if your CMS web page is available at https://mydomain.com, then simply swap
mydomain.com . If your CMS is only available by an IP address, then enter the IP address instead.
XTR - Routine Tasks
XTR is configured by default on installing docker.
Starting and Stopping Xibo
Once the CMS containers have been initialised with
docker-compose up -d, it is possible to start and stop them without removing the underlying container.
stop command will stop the Xibo CMS services running. If you want to start them up again, issue the
Uninstalling / removing
The CMS installation and its associated containers can be completely removed by issuing the
Before running docker-compose down, please be sure that your media and database files are being correctly written to the
- To do so, upload for example an image into the CMS, and check that the same image appears in the
- Another good check is to make sure that
shared/backup/db/latest.tar.gzwas created within the last 24 hours.
If either of those checks fail, please do not run
docker-compose down as this will lead to data loss. Seek support to resolve the situation.
If your intention is to remove all traces of Xibo you may delete the
/opt/xibo folder after running the
Backing up your CMS/Database
As with any system containing user data, it is vital to maintain regular backups of your Xibo CMS.
Docker installations automatically take a daily database backup for you, as well as one as part of the upgrade routine.
- As part of your backup plan, you should regularly take a backup of at least the following files/directories:
Custom Scripts and Pages
If you want to use the environment provided by Docker to run custom developments, themes, modules or standalone files you can do so using the
The following locations are available:
/shared/cms/custom: Used for custom middleware
/shared/cms/web/theme/custom: Used for custom themes
/shared/cms/web/userscripts: Use for standalone files, will be served as
Other shared folders
Docker also makes the library and backup available as shared folders:
Library and Bandwidth Limits
Manage limits on the library file size and monthly bandwidth usage.
- This is done by virtue of two settings in the database table; (LIBRARY_SIZE_LIMIT_KB & MONTHLY_XMDS_TRANSFER_LIMIT_KB)
If no limits are entered in the database, everything continues to work without restriction; however once a limit is entered Xibo will start validating against these limits, and when they are exceeded will prevent the upload of new media/updates to Players.
However, these two settings are currently not available through the user interface; only the statistical data is shown.
Existing Docker Cluster
If you have your own docker environment you may want to run without the automation provided by docker-compose. If this is the case you will be responsible for pulling the docker containers, starting them and manually installing Xibo.
The structure expected by the containers is outlined below.
There are 2 containers provided:
These are built by Docker Hub and packaged into
Xibo also requires a database - we recommend using the
mysql container available on Docker Hub. Any MySQL based container can be used, provided it can be linked to the
cms-web container. It is also possible to use an external database by providing those details to the
cms-web container as environment variables, as below:
If you decide to run the containers yourself you should read and understand the
DockerFile which can be found for each container in the
You may also want to pass in environment variables to configure SMTP in the container. All options are fully documented in the
config.env.template-remote-mysql files found in our archives.
Data folders should be mapped outside the Docker containers as volumes so that data is persisted across Container upgrades.
The following Data folders are used by
docker-compose and should be configured for your environment:
- The Library storage can be found in
- The database storage can be found in
- Automated daily database backups can be found in
- Custom themes should be placed in
- Custom modules should be placed in
- Any user-generated PHP or resources external to Xibo that you want to be hosted on the same web server go in
/shared/cms/web/userscripts. They will then be available to you at