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.

Become root in your command line shell either by running sudo su or 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 config.env.template.

Take a copy of this file, renaming to config.env and 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 shared sub-folder.

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 thecms_custom-ports.yml.template file and change the ports section for cms-web.
The file should be saved as cms_custom-ports.yml.

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.template file and changing the ports section for cms-xmr.
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 8080:80.

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.

Remote MySQL

The default 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.env file on the template config.evn.template-remote-mysql and replace any docker-compose up -d commands in the below instructions with docker-compose -f cms_remote-mysql.yml up -d.

HTTPS/SSL

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 cms-web container.

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.

An example VirtualHost for Apache is below, it assumes you’ve configured your custom ports for port 8080:

Listen 443

NameVirtualHost *:443
<VirtualHost *:443>

    SSLEngine On
    ProxyPreserveHost On
    RequestHeader set X-Forwarded-Proto "https"

    # Set the path to SSL certificate
    # Usage: SSLCertificateFile /path/to/cert.pem
    SSLCertificateFile /etc/apache2/ssl/file.pem


    # Servers to proxy the connection, or;
    # List of application servers:
    # Usage:
    # ProxyPass / http://[IP Addr.]:[port]/
    # ProxyPassReverse / http://[IP Addr.]:[port]/
    # Example:
    ProxyPass / http://0.0.0.0:8080/
    ProxyPassReverse / http://0.0.0.0:8080/

</VirtualHost>

A worked example for setting up an Apache reverse proxy for SSL with LetsEncrypt SSL certificates can be found here

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 docker command, simply run:

docker-compose up -d

You may experience a delay whilst the CMS finishes setting up after the command is run, please be patient.

This will bootstrap and start your Xibo CMS.

The CMS will be fully installed with the default credentials:

Username: xibo_admin
Password: password

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, http://localhost:8080.

Configuration adjustments

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:

tcp://<ip_address>:<port>

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 cms.example.org for mydomain.com . If your CMS is only available by an IP address, then enter the IP address instead.

If you run a local firewall on your CMS server, you will need to allow port 9505 inbound for XMR to work, as well as port 80/443 inbound for the web interface.

XTR - Routine Tasks

XTR is configured by default on installing docker.

Once your Xibo CMS is installed, take a look at the Xibo CMS Post-installation Set-up Guide for further configuration options!

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.

The stop command will stop the Xibo CMS services running. If you want to start them up again, issue the start command.

docker-compose stop
docker-compose start

Uninstalling / removing

The CMS installation and its associated containers can be completely removed by issuing the down command.

Before running docker-compose down, please be sure that your media and database files are being correctly written to the shared directory.

To do so, upload for example an image into the CMS, and check that the same image appears in the shared/cms/library directory.
Another good check is to make sure that shared/backup/db/latest.tar.gz was 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 down command.

docker-compose down

Community Resources

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:

shared/backup/db/latest.sql.gz
shared/cms
config.env
*.yml

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 /shared folders.

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 http://localhost/userscripts

Other shared folders

Docker also makes the library and backup available as shared folders:

/shared/backup :
/shared/cms/library

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.

You can also apply a limit for the amount of bandwidth that a Display can consume!

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.

Containers

There are 2 containers provided:

These are built by Docker Hub and packaged into xibo-signage/xibo-cms and xibosignage/xibo-xmr.

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:

MYSQL_HOST
MYSQL_PORT
MYSQL_DATABASE
MYSQL_USER
MYSQL_PASSWORD

If you decide to run the containers yourself you should read and understand the DockerFile which can be found for each container in the /containers folder.

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 and config.env.template-remote-mysql files found in our archives.

Storing Data

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 /shared/cms/library
The database storage can be found in /shared/db
Automated daily database backups can be found in /shared/backup
Custom themes should be placed in /shared/cms/web/theme/custom
Custom modules should be placed in /shared/cms/custom
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 http://localhost/userscripts/

Xibo for Docker

On this page

Xibo for Docker

Quick Start Guide

Docker on Linux

Download and extract the Xibo Docker archive

Check and edit configuration

Using different ports

Remote MySQL

HTTPS/SSL

Installing the CMS containers

Configuration adjustments

XMR - Push Messaging

XTR - Routine Tasks

Starting and Stopping Xibo

Uninstalling / removing

Community Resources

Backing up your CMS/Database

Custom Scripts and Pages

Other shared folders

Library and Bandwidth Limits

Existing Docker Cluster

Containers

Storing Data

Search Results