Self-Hosted Deployment

Deploy xiboplayer with a self-hosted Xibo CMS.

CMS options

Recommended: xibo-cms fork (Docker)

Our xibo-cms fork is rebased daily on upstream — you get all upstream features, bug fixes, and security patches without delay. On top of that, the fork adds:

• REST API v2 — JWT auth, ETag caching, ~30% smaller payloads than SOAP
• PWA player built into the CMS — no separate deployment needed
• No ext-soap required — the #1 reason upstream CMS Docker deployments fail

# Pull and run our CMS fork
docker compose -f docker-compose.yml up -d

The player auto-detects which transport the CMS supports and uses the best one available. Works with both our fork and upstream Xibo CMS.

Alternative: upstream Xibo CMS

Any Xibo CMS v3 or v4 works. Follow the official installation guide. The player falls back to SOAP when REST is unavailable.

Requirements

• Docker + Docker Compose
• 2GB+ RAM, 20GB+ storage
• A domain name with HTTPS (required for PWA, recommended for all)

After setup, note your CMS URL and CMS Secret Key (Settings → Display Settings).

Player installation

RPM/DEB packages

# Add the xiboplayer repository
sudo dnf install https://dl.xiboplayer.org/rpm/fedora/43/noarch/xiboplayer-release-43-7.fc43.noarch.rpm

# Install your preferred player
sudo dnf install xiboplayer-electron    # Full-featured, bundles Chromium
sudo dnf install xiboplayer-chromium    # Lightweight, uses system browser
sudo dnf install xiboplayer-kiosk       # Auto-start kiosk meta-package

PWA (browser-based)

The PWA must be served from the same domain as the CMS:

git clone https://github.com/xibo-players/xiboplayer.git
cd xiboplayer && pnpm install
pnpm --filter @xiboplayer/pwa build
# Deploy dist/ to your CMS web root

Kiosk image

Download a pre-built ISO from Downloads. Flash to USB/SD, boot, and the player auto-starts.

Network requirements

All player-to-CMS communication uses HTTPS. XMR is initiated by the player as an outbound WebSocket upgrade.

CORS proxy

Electron and Chromium include a built-in CORS proxy (@xiboplayer/proxy) that:

• Forwards XMDS/REST API calls to the CMS
• Downloads media with Range support
• Serves the PWA as static files
• Hosts the WebSocket sync relay for video walls

No manual proxy configuration needed for single-display setups.

Reverse proxy (optional)

For HTTPS termination, use SWAG or nginx in front of the CMS:

Internet → SWAG (HTTPS:443) → Xibo CMS (HTTP:80)

SWAG provides automatic Let's Encrypt certificates and production-grade nginx.

Auto-start

# Enable player auto-start
systemctl --user enable xiboplayer-electron.service
# or
systemctl --user enable xiboplayer-chromium.service

Kiosk images auto-start by default.

File locations