> For the complete documentation index, see [llms.txt](https://docs.xibosignage.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xibosignage.com/cms-installation/self-hosted-cms.md). # Self hosted CMS Containers provided are for x86-64/AMD64 architecture only which are suitable for most servers: [Docker](https://docker.com/)​ ### Getting Started * You will need a Linux host machine * Docker must be installed and working ​[Install Docker docs ](https://docs.docker.com/engine/install/#server)​[Docker Compose READ ME](https://github.com/docker/compose#linux)​ #### Download and extract the Xibo Docker archive To install Xibo, you’ll need to be the `root` user in your command line shell by: * running sudo su * or logging in as root directly Download the latest Docker Installation: [Docker Installation Download](https://xibosignage.com/api/downloads/cms)​ The archive should be extracted in a suitable location on your host machine. We 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 it to `config.env` and then edit the file in a text editor, e.g. nano, gedit, etc. If you don’t want Xibo to have the ability to send email messages, then you can opt to not configure those options. Docker will map data folders to contain database data and any custom files for the CMS. These will appear by default in the folder containing the release archive in a shared sub-folder. #### 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, run: ``` docker compose up -d ``` {% hint style="warning" %} You may experience a delay whilst the CMS finishes setting up after the command is run. {% endhint %} This will bootstrap and start your Xibo CMS. The CMS will be fully installed with the default credentials: * **Username**: xibo\_admin * **Password:** password Log in to the CMS and change the password on that account. You can log on to the CMS at `http://localhost`. {% hint style="warning" %} If you configured an alternative port number then be sure to add that to the URL, for example, `http://localhost:8080`. {% endhint %} #### 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) Docker installs come with XMR running automatically for you, and with most of the configuration in place. However, you do need to adjust a few settings, on first log in, as detailed below: #### XMR WebSocket Address The XMR web socket address of the CMS defaults to empty, which means players will try to connect to your CMS at `/xmr`. The Apache container provided will handle web socket requests at that URL, but if you run Xibo from a sub-folder, or wish to run XMR separately you should adjust the XMR web socket address to suit. We recommend including this address in your reverse proxy configuration so that it can handle SSL termination. #### XMR public address The XMR public address of the CMS is how any player which does not support web sockets will connect to XMR for push messaging. 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 select 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://:` The default \ 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](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. #### 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: [nginx-proxy container](https://github.com/jwilder/nginx-proxy) If you already have a web server running on your Host machine, configuring a reverse proxy should be straightforward. ### 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 ``` ### 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` ### Community Resources * [Xibo CMS with Docker on Ubuntu 22.04](https://community.xibo.org.uk/t/xibo-cms-with-docker-on-ubuntu-22-04/9392) * [Windows 10 64bit](https://community.xibo.org.uk/t/xibo-for-docker-on-windows-10-64-bit/16298) * [Windows 64bit, other than Windows 10](https://community.xibo.org.uk/t/xibo-for-docker-on-windows-64bit-other-than-windows-10/16300/2) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.xibosignage.com/cms-installation/self-hosted-cms.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.