Self-Hosting PiSignage Server with Docker

What Is PiSignage?

PiSignage is a digital signage platform built around the Raspberry Pi. A central server manages content and playlists that get pushed to Pi-based player devices connected to displays. Upload images, videos, and web content through a web dashboard, arrange them into playlists, assign playlists to player groups, and schedule when content plays. The server component (PiSignage Server) can run on any Docker host; the players run PiSignage player software on Raspberry Pi hardware. GitHub

Updated March 2026: Verified with latest Docker images and configurations.

Prerequisites

A Linux server (Ubuntu 22.04+ recommended)
Docker and Docker Compose installed (guide)
2 GB of RAM minimum
30 GB of free disk space (more for video content)
At least one Raspberry Pi with PiSignage player image for display output

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  pisignage-db:
    image: mongo:5.0
    container_name: pisignage-db
    restart: unless-stopped
    volumes:
      - pisignage-mongodb:/data/db
      - pisignage-mongodb-config:/data/configdb
    networks:
      - pisignage

  pisignage-server:
    image: pisignage/pisignage-server:latest  # No versioned Docker tags published — :latest is the only option
    container_name: pisignage-server
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - pisignage-media:/media
      - pisignage-data:/data
    depends_on:
      - pisignage-db
    networks:
      - pisignage

volumes:
  pisignage-mongodb:
  pisignage-mongodb-config:
  pisignage-media:
  pisignage-data:

networks:
  pisignage:

Note: PiSignage Server only publishes a latest tag on Docker Hub — no versioned tags are available. The current version is 3.2.0a. Pin to latest and document the running version for reproducibility.

Start the stack:

docker compose up -d

Initial Setup

Open http://your-server:3000 in a browser.
Log in with the default credentials: username pi, password pi.
Change the default password immediately — Settings → Admin → Change Password.
Upload media (images, videos) through the Assets section.
Create a playlist and add your media items.
Register your Raspberry Pi player devices — they auto-discover the server on the local network.
Assign playlists to player groups.

Configuration

Key Features

Feature	Support
Media types	Images (JPEG, PNG), Videos (MP4, WebM), Web pages, Live streams
Playlists	Yes — ordered or shuffled, with per-item duration
Scheduling	Yes — time-of-day and day-of-week scheduling
Player groups	Yes — assign different content to different display groups
Ticker/crawl	Yes — scrolling text overlay
Multi-zone layouts	Yes — split screen into regions
Remote management	Yes — push content updates over the network
Player monitoring	Yes — online status, screenshots, hardware info
API	Yes — REST API for automation
Supported players	Raspberry Pi (official), Android (beta)

Network Configuration

PiSignage players discover the server using mDNS or direct IP configuration. For players on different subnets or remote locations:

Configure the player with the server IP/hostname manually
Ensure port 3000 is accessible from player devices
For remote players over the internet, put the server behind a reverse proxy with SSL

Content Management

Assets: Upload files through the web UI or API. Supported formats include JPEG, PNG, MP4, and WebM.
Playlists: Group assets into playlists with configurable duration per item. Multiple playlists can be assigned to different groups.
Templates: Create multi-zone layouts — main content area, ticker bar, side panel, clock.
Scheduling: Define which playlist plays during which hours. Useful for restaurant menus (breakfast vs. lunch vs. dinner).

Reverse Proxy

signage.example.com {
    reverse_proxy pisignage-server:3000
}

See Reverse Proxy Setup for detailed configurations with Nginx Proxy Manager, Traefik, or Caddy.

Backup

# Database backup
docker exec pisignage-db mongodump --out /data/backup
docker cp pisignage-db:/data/backup ./pisignage-db-backup-$(date +%Y%m%d)

# Media backup
docker run --rm -v pisignage-media:/media -v $(pwd):/backup alpine \
  tar czf /backup/pisignage-media-$(date +%Y%m%d).tar.gz -C /media .

See Backup Strategy for automated approaches.

Troubleshooting

Players Not Discovering Server

Symptom: Pi players don’t appear in the server dashboard after booting.

Fix: mDNS discovery only works on the same subnet. For cross-subnet deployments, configure the server IP directly on the player:

# On the Pi player, edit the server config
echo "YOUR_SERVER_IP" > /home/pi/.pisignage/server

Verify port 3000 is not blocked by firewalls between the player and server.

Video Playback Stuttering on Player

Symptom: Videos play with stuttering or dropped frames on the Raspberry Pi.

Fix: Re-encode videos for Pi hardware acceleration:

ffmpeg -i input.mp4 -c:v h264 -b:v 4M -c:a aac output.mp4

Keep resolution at 1080p or below. Avoid 4K content on Pi 3/4 — the GPU can’t decode it smoothly.

MongoDB Connection Errors

Symptom: Server fails to start with database connection errors.

Fix: Ensure MongoDB is fully initialized before the server starts:

docker compose logs pisignage-db

If MongoDB is taking long to initialize (first run), wait 30-60 seconds and restart the server container:

docker compose restart pisignage-server

Resource Requirements

RAM: 512 MB - 1 GB (server), 1 GB (MongoDB)
CPU: Low — Node.js handles requests asynchronously
Disk: Application is small; media files dominate storage needs

Deployment	Server RAM	Storage
Small (1-5 displays, images only)	1 GB	5 GB
Medium (5-20 displays, mixed media)	2 GB	30 GB
Large (20+ displays, video-heavy)	4 GB	100+ GB

Verdict

PiSignage fills the gap between Anthias (single-display, no central server) and Xibo (enterprise-grade, complex setup). It gives you a central management server with multi-player support, scheduling, and multi-zone layouts — without the complexity of Xibo’s 4-container stack. The main limitation: it’s tightly coupled to Raspberry Pi hardware for players (Android support is beta). If your displays are all Pi-powered, PiSignage is a practical choice. For cross-platform player support, look at Xibo. For a single display with minimal setup, Anthias is simpler.

Frequently Asked Questions

Does PiSignage work with non-Raspberry Pi displays?

The server runs on any Docker host, but the player software is designed for Raspberry Pi. Android player support exists in beta but isn’t as mature. If you need cross-platform player support (Windows, Android, Linux), Xibo is a better fit. PiSignage is best when all your display hardware is Raspberry Pi-based.

Can PiSignage play video content?

Yes. PiSignage supports video playback including MP4 and H.264 content. Keep resolution at 1080p or below on Pi 3/4 — the GPU can’t smoothly decode 4K. The Pi 5 handles 4K better. Video files can be uploaded through the web dashboard and scheduled alongside images and web content.

How many displays can one PiSignage server manage?

There’s no hard limit in the self-hosted server. The practical limit depends on your server resources and network bandwidth. Small deployments (1-5 displays) run fine on 1 GB RAM. Medium deployments (5-20 displays) need 2 GB. For 20+ displays with video-heavy content, allocate 4 GB RAM and plan for storage.

Does PiSignage support multi-zone layouts?

Yes. PiSignage supports multi-zone screen layouts where different areas of the display show different content simultaneously. You can define zones for video, images, tickers, clocks, and web content. This is configured through the web dashboard’s layout editor.

Can PiSignage schedule content by time of day?

Yes. PiSignage includes playlist scheduling based on time of day and day of week. You can configure different playlists for morning, afternoon, and evening, or set specific content to display during business hours only. Schedules are managed centrally on the server and pushed to players automatically.

How does PiSignage compare to Xibo?

PiSignage is simpler to set up and tightly integrated with Raspberry Pi hardware. Xibo is enterprise-grade with a more complex four-container stack but offers cross-platform player support, advanced scheduling, and a richer layout designer. Choose PiSignage for Pi-based deployments where simplicity matters. Choose Xibo for larger deployments needing Windows/Android/Linux player support.