piSignage Server with FerretDB on Ubuntu 24.04 on Azure User Guide

Overview

This guide covers the deployment and use of piSignage Server with FerretDB on Ubuntu 24.04 on Azure using cloudimg Azure Marketplace images.

The image bundles the open source signage server with a permissively licensed database:

• piSignage Server (MIT OR Apache 2.0) — the open source, self hosted server for managing digital signage. You upload media, build playlists, organise displays into groups and labels, and manage the signage players that connect back to the server, all from a web browser. This is the open source self hosted server, not the piSignage cloud or hardware offering.
• FerretDB (Apache 2.0) — a truly open source database that speaks the MongoDB wire protocol while storing your data in PostgreSQL through the DocumentDB extension. piSignage stores its assets, groups, labels, players and settings here.

Why FerretDB rather than MongoDB Community Server: MongoDB Community is distributed under the Server Side Public License (SSPL), which is not freely redistributable in a paid marketplace image. FerretDB is a permissively licensed, MongoDB compatible alternative, so the whole stack in this image is open source and free of restrictive licensing. The datastore is FerretDB, backed by PostgreSQL — it is compatible with MongoDB, not MongoDB itself.

Runs stand alone. Physical signage players connect to the server over the network, but the server itself boots and is fully usable with no hardware attached, so you can set up media, playlists and groups, and preview your content, before you register a single screen.

Security by design, no baked credential. Nothing in this image ships with a known password. piSignage stores its login in its database with a well known default (pi / pi) and bakes a fixed session secret; both are overridden. On first boot each VM generates a unique web console administrator password, a unique database password and a unique session secret, writes the console and database passwords to root only files, and the well known default login is overridden and rejected. The MongoDB compatible endpoint is bound to loopback only, so only the local server reaches it; the web console is the single network facing service and its entire interface and REST API are protected by HTTP authentication.

What is included:

• piSignage Server 3.2 running under systemd as pisignage.service on port 3000, with its whole UI and REST API behind HTTP authentication
• FerretDB 2.7.0 running under systemd as ferretdb.service, MongoDB wire protocol on loopback 127.0.0.1:27017
• PostgreSQL 17 with the DocumentDB extension as the storage backend (loopback only), running as postgresql.service
• The mongosh MongoDB shell, plus ffmpeg, ImageMagick and GraphicsMagick for media processing, preinstalled
• A demo playlist CloudimgDemo, two demo media slides and a Lobby Display group seeded on first boot, so the console shows real content immediately
• A per VM web console password, database password and session secret generated on first boot; the console and database passwords are written to root only credentials files
• No swap in the image; PostgreSQL is tuned to fit a Standard_B2s in RAM

Deploying the VM

Launch the image from the Azure Marketplace as you would any other VM. The recommended size is Standard_B2s (2 vCPU / 4 GiB), which the shipped configuration is tuned for.

The web console listens on TCP 3000. In the Azure network security group, open 3000 only to the client addresses that genuinely need it — never to the whole internet — and add 22 for SSH. The MongoDB compatible database on 27017 is bound to loopback and is deliberately not exposed.

First boot

On the first boot of each VM, two ordered one shot services run before the application starts:

1. ferretdb-firstboot.service generates a unique database password, creates the PostgreSQL role that FerretDB authenticates as, and writes /root/ferretdb-credentials.txt.
2. pisignage-firstboot.service generates a unique web console administrator password and a unique session secret, wires piSignage to the database, seeds the demo playlist, media and group, and writes /root/pisignage-credentials.txt.

The application service, pisignage.service, only starts once first boot has finished seeding the per VM credentials, so the well known default login is never live. Both one shot services complete within a few seconds of boot. You can confirm the whole stack is up:

systemctl status postgresql ferretdb pisignage

Signing in to the web console

Retrieve the generated web console credentials (root only):

sudo cat /root/pisignage-credentials.txt

You will see the username (admin), a unique password and the URL. Open the console in your browser:

http://<vm-public-ip>:3000/

Sign in with admin and the generated password. The upstream default login (pi / pi) is overridden and will be rejected. On the Assets page you will see the seeded demo media slides and the CloudimgDemo playlist; on the Players page you will see the seeded Lobby Display group. Because this content is seeded, a freshly launched VM shows a working, populated console with no signage hardware attached.

Managing media, playlists and groups

From the web console you can:

• Assets — upload images, video and other media, and see them listed with thumbnails. Build playlists from your media in the Playlists panel on the same page.
• Players — organise your displays into groups, assign a playlist to a group, and monitor the players that report back to the server.
• Settings — configure server wide options for your deployment.

The server is ready to accept players immediately. When you set up a physical piSignage player, point it at this server's address so it registers, then assign it to a group to start playing your content.

Working with the database directly

The MongoDB compatible database (FerretDB) runs on the loopback interface. The mongosh shell is preinstalled. Read the database password (root only):

sudo cat /root/ferretdb-credentials.txt

Then connect locally, substituting the password from that file:

mongosh "mongodb://admin:<database-password>@127.0.0.1:27017/pisignage?authMechanism=SCRAM-SHA-256&authSource=admin"

Your existing MongoDB drivers work unchanged against the same endpoint. The database is bound to loopback and is not exposed on the network; to reach it remotely you would open 27017 in the network security group and change FERRETDB_LISTEN_ADDR in /etc/ferretdb/ferretdb.env, ideally fronted with TLS.

Security notes

• The web console is the only network facing service. Open port 3000 only to trusted client addresses in the network security group, and put it behind TLS (for example an nginx or Caddy reverse proxy, or an Azure Application Gateway) before exposing it beyond a private network.
• The web console administrator password, the database password and the session secret are unique per VM and generated on first boot. No two machines share a secret, and there is no default login to guess.
• The database endpoint is bound to loopback and never exposed by default.
• The base OS is fully patched at build time and keeps unattended security updates enabled, so security patches continue to flow on your running VM.

Maintenance

The stack runs as ordinary systemd services and starts automatically on boot:

# Status of all three services
systemctl status postgresql ferretdb pisignage

# Restart the application after a configuration change
sudo systemctl restart pisignage

# Application logs (recent)
sudo journalctl -u pisignage -n 50 --no-pager

Take regular backups of your media directory (/opt/media) and of the database. For the database, use standard MongoDB compatible tooling against the loopback endpoint, or back up the underlying PostgreSQL cluster.

Support

Every cloudimg image comes with a deploy guide tested against the exact build and 24/7 cloudimg support by email and chat, covering the web console, media and playlists, player registration, authentication, the PostgreSQL and DocumentDB backend, backups and capacity planning.