This guide relates to Xibo 1.8 series. Looking for information relating to 1.7 series? The old article is archived here.
Once your 1.8 series Xibo CMS is installed, there’s some additional setup required to enable all functionality and to keep things running smoothly.
This article will list those steps and link out to specialised articles where appropriate.
You’ll need a Xibo CMS. If you haven’t installed one already, basic instructions for installing a CMS with Docker can be found here:
Alternatively, if you’d rather not host your own CMS, the project Sponsors Xibo Signage and others can host a CMS for you. I’ve made note below where Xibo in the Cloud customers can skip steps as they have been pre-configured for you.
If you are running with Docker, please upload a test file (say an image) to your CMS, and ensure that the same image then appears in the
shared/cms/library directory on your local filesystem. If not, please do not proceed as your changes may not be saved.
Time and timezone
Xibo in the Cloud customers can skip directly to Timezone
It’s really important that the time is correct on your CMS, and that the CMS timezone setting is set correctly for the timezone you’re working in.
You might want to consider setting up your Operating System to sync time automatically from the Internet so that the time is always correct.
So now your clock is correct (and will remain so automatically), we need to let the CMS know what timezone it should be using. The installer attempts to make an intelligent guess from the timezone that your OS has been set up to use, but it’s not always able to make the best choice.
Log in to your CMS and go to the
Settings page, and then the
Select the nearest major city in your timezone. Click Save at the bottom of the page.
CMS Maintenance and Email Alerts
The Xibo CMS is only ever running when a user is actively interacting with the system, or a Player is connecting to update its content. At other times, Xibo isn’t running at all. That means in order to carry out certain background routines (eg clearing out old records) or to alert you if one of your Players stops connecting as expected, we need a regular “wakeup” to run Xibo to allow those things to happen. Xibo uses Tasks and XTR to run these routines. In the Cloud, or wtih Docker, running XTR will happen automatically for you.
Now the CMS is being regularly woken up, we can optionally configure email alerts to be sent when Players stop connecting properly, and when they come back online after a period of downtime.
Firstly head to the Settings page of the CMS and move to the
Maintenance tab. You’ll see some settings referring to the sending of emails. Xibo in the Cloud customers note that some of these are pre-populated for you but are available for you to change, and others are locked for editing
Enabled Email Alerts(
MAINTENANCE_EMAIL_ALERTS) is set to On
- Enter the email address that should receive an email when a display goes offline or comes back online in the
Admin email address(
- Enter the email address alerts from the CMS should come from in the
Sending email address(
Send repeat Display Timeouts(
MAINTENANCE_ALWAYS_ALERT) field, if set to
Onwill mean for each offline display, you’ll receive an email every time the
maintenance.phproutine is run. Most people will want this set to
Offwhich means that you’ll be notified only once per downtime period.
- The value of
Max Display Timeout(
MAINTENANCE_ALERT_TOUT) is the time in minutes after we last see a Player connect to the CMS that we consider it to have gone offline. It can be overridden on a per-display settings profile basis should you need that. Do not set this value lower than your normal Player collection interval. If in doubt, set it higher. The default is 30 minutes.
- Save your settings by clicking the Save button at the bottom of the page.
In some cases, it’s also useful to alert users if a Player goes offline. If you want to alert all users who have view permissions to a display, then move to the Displays tab and tick the box
Maintenance Alerts for Users (
MAINTENANCE_ALERTS_FOR_VIEW_USERS) and click Save.
Next, we need to decide which Displays we want to receive alerts for.
Go to the
Displays page in the CMS. For each display that you want to receive alerts for, edit the display and move to the
Email Alerts is set to
Yes. For any display you don’t want to receive email alerts for, set
Email Alerts to
No. If you aren’t using Display Settings Profiles (see the section below), be sure to tick the
Use Global Timeout tick box so that the value we set earlier for the time a display needs to be offline before we’re alerted is used. If you’re using Display Settings Profiles, then if that box is unticked, the display collection interval from the Display Profile is used instead.
And that’s Email Alerts configured. Now if you turn off one of your displays, you should be notified by email. The email will be sent once the global timeout or display profile collection interval has elapsed since the Player last connected, on the subsequent run of the maintenance script. If the global timeout is 10 minutes and your maintenance script is set to run every 5 minutes, then you may not be notified for up to 15 minutes after the Player last connects.
When the Player comes back online, you will be notified instantly via email. Note that multiple recovery emails are sent if the Player in use makes multiple simultaneous calls to the CMS when it starts up.
Log and Statistics Retention
Xibo in the Cloud customers should be aware that these settings are pre-configured and aren’t available to be modified.
The CMS generates log output when it’s running, and also receives log output from the Players connected to it for the purposes of debugging and checking the system’s state. It can also collect proof of play records called Statistics. All these records are held in the database and should be purged periodically to keep the size of the database manageable and to prevent system performance problems. The maintenance script performs that function.
Settings page in the CMS, move to the
Max Log Age (MAINTENANCE_LOG_MAXAGE)controls how many days logs should be retained in the CMS database before being automatically deleted. A setting of
5would keep logs for 5 days and that’s reasonable for most debugging purposes.
Max Statistics Age (MAINTENANCE_STAT_MAXAGE)controls how many days proof of play statistics are retained in the CMS database before being automatically deleted. A setting of
30would keep statistics for 30 days. If you need to keep them for audit purposes, they can be exported from the
Statisticspage in the CMS and archived for later use.
The Xibo has built-in support for display of the user interface in alternative languages, and to show dates in alternative formats too (eg DD/MM/YYYY vs MM/DD/YYYY).
All translations are contributed by the community and we are very grateful for peoples efforts to keep the system translations updated and accurate. If you’re interested in improving the translations for a specific language, you can contribute directly via Launchpad Translations:
Edits made there will be automatically included in a future Xibo CMS release.
By default, the CMS will use the language preferences set in your web browser to auto-detect which language to display the CMS interface in. In some instances, for example, where only small parts of the CMS have been translated into a particular language, it may be desirable to disable language detection and enforce a specific language instead.
- From the
Settingspage of the CMS, move to the
- Untick the
Detect Language (DETECT_LANGUAGE)tick box
- Select a suitable default language (see below)
- Save your changes
If you disable language detection, the CMS will need to know which language file to take its translations from.
- From the
Settingspage of the CMS, move to the
- Find the
Default Language (DEFAULT_LANGUAGE)box
- The default is
en_GBwhich will give you English (British) translations. You can enter any valid code from the list of languages Xibo is currently translated in to. You can see a list here
- Enter the language code, without the trailing .mo. So for example, to select Spanish, enter
- Save your changes
Regionalised Date Formats
By default Xibo CMS shows dates in
Y-m-d H:i format (eg 2015-03-29 10:00:00)
The date format used throughout the CMS can be adjusted from the Settings screen by adjusting the date format setting.
Display Settings Profiles
Display Settings Profiles offer a powerful way of centrally configuring your Player settings from the CMS. When the Players connect to the CMS, they will receive any default or assigned profile you’ve created and reconfigure themselves with those settings automatically.
You’ll find the profiles in the
Display Settings page of the CMS. You can create default profiles for each Player type or individual profiles which can then be applied to one or more Players to override the default settings.
Full details on managing Display Settings Profiles can be found in the manual here:
Display Settings Profiles
Important Note On Collection Intervals
1.8 series comes with XMR push technology, which means that by default when you make changes to content assigned to displays in the CMS, the Players are notified to connect in and download that update straight away. It’s therefore strongly advisable to set relatively long collection intervals for your Players since those only really serve as a failsafe for any missed push messages. You certainly do not want 1.8 series CMS and Players with 1-minute collection intervals. 5 minutes is the absolute minimum for normal operation, and we strongly advise setting this value to 30 minutes or longer.
Xibo in the Cloud customers can skip this section
The CMS will need to be able to contact external servers to pull in RSS feeds from outside your local network, or for integrations such as Twitter. If your network uses a proxy server then you’ll need to tell the Xibo CMS about it so it knows where to look.
From the Settings page of the CMS, move to the
Fill in the proxy server details for your network. Your network administrator will be able to help you if you’re not sure what they are.
Proxy URL (PROXY_HOST)should be the http URL of your proxy server (eg
Proxy Port (PROXY_PORT)should be the port number that your proxy server is listening on (eg
Proxy Credentials (PROXY_AUTH)should be any username and password required to use the proxy server, in the format
jdoe:secretPassword. Leave this blank if your proxy does not require authenticated access.
Proxy Exceptions (PROXY_EXCEPTIONS)are any host or keyword that should be excluded from being sent to the proxy server. For example if you have an intranet server then you could exclude it by entering
intranet.domain.com. Multiple entries can be included by separating them with commas. Leave this blank if you don’t require any proxy exceptions.
Save your changes at the bottom of the page.
Xibo in the Cloud accounts come with XMR pre-configured so you can skip this section
Docker installs of Xibo CMS 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.
From the CMS Settings, go to the Displays tab:
The XMR Public Address field defaults to
tcp://cms.example.org:9505. We need to adjust this value to be suitable for your network.
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.
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.
Third Party Integrations
Weather Forecast API Key
Xibo in the Cloud accounts come pre-configured with a Forecast API key so you can start using the Weather module straight away with no additional setup
Since version 1.7, Xibo CMS has the ability to show weather forecasts and current weather conditions thanks to an integration with Darksky
Access to the Darksky API is protected and users must register for an API key and enter that key into the Xibo CMS settings. Full details are available in the manual here:
Twitter API Key
Since version 1.7, Xibo CMS has the ability to search Twitter for interesting tweets and show them as part of a layout.
Access to the Twitter API is protected and users must register for an API key and enter that key into the Xibo CMS settings. The process differs slightly for Xibo in the Cloud customers as detailed below.
Xibo Open Source Users
- Go to https://dev.twitter.com/apps/new and log in, if necessary
- Supply the necessary required fields, accept the terms of service, and solve the CAPTCHA.
- Submit the form
- Make a note of the generated consumer key (API key) and consumer secret (API secret)
- Move to the
Modulespage of the CMS and edit the Twitter module
- Enter your API key and secret.
- Optionally adjust the
Cache Periodvalue to determine how long to cache a results set for each Twitter search. Note that setting low values can cause your access to the Twitter API to be disabled for generating too many requests.
- Save your changes
Xibo in the Cloud Customers
The process of connecting to the Twitter API is simplified for Xibo in the Cloud customers.
Modulespage of the CMS, find the
Twitter Providermodule and click the dropdown arrow at the end of the row to reveal a
Connect to Twitterbutton:
That will bring up a Login with Twitter button to allow you to authorise the CMS to connect via your Twitter account:
Press the Login with Twitter button and follow the on-screen instructions to authorise the CMS.
Xibo in the Cloud customer accounts are backed up daily as part of your service plan
As with any system containing user data, it’s vital to maintain regular backups of your Xibo CMS.
Docker-based installs 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
How you opt to make regular backups is left as an exercise for each administrator.
Remember for a backup strategy to be reliable and effective, it must be automatic. Don’t rely on remembering to take periodic backups manually.