← All docs

Before you start

• A machine that runs Docker: a Linux server, a NAS (Synology, QNAP, Unraid, TrueNAS) or a Raspberry Pi 4 or 5 (64-bit).
• The Beebo server image. It is called beebo-server below; testers receive it or its build instructions.
• Your movies, TV, music and photos in folders the container can read.
• A safe place to keep one secret key (step 2).

Step by step

1. Make folders for settings and media

   Create a folder for Beebo’s own data (settings, accounts, watch history, artwork cache and certificates), for example /srv/beebo/config, and know where your media folders are. Read-only media is fine for watching. Uploads from the phone app, the Inbox and file clean-up write to the media folders, so give it write access if you want those.

2. Make a secret key and keep it

   Beebo encrypts saved secrets (password hashes, sign-in signing keys, your TMDB key, webhook secrets) in its settings file. The key comes from an environment variable. Make one, for example with openssl rand -hex 32, and save it somewhere safe. If you change or lose it, the saved secrets become unreadable, and Beebo stops at start-up with a message instead of quietly signing everyone out.

   What you’ll see: A 64-character string. Keep it outside the config folder if you want real separation: anyone who has the whole config folder and the key file has both.

3. Start the container

   Run the container with your folders and key. This is the quick start from the server’s README:

   docker run -d --name beebo --restart unless-stopped \
     -p 47811:47811 \
     -e BEEBO_UPNP=0 \
     -e BEEBO_SECRET_KEY="<your key>" \
     -v /srv/beebo/config:/config \
     -v /srv/media/movies:/media/movies \
     -v /srv/media/tv:/media/tv \
     -v /srv/media/music:/media/music \
     -v /srv/media/photos:/media/photos \
     beebo-server

   A compose file that keeps the key in a Docker secret comes with the image. A wrong setting stops the container with a message listing every problem (exit code 78), so a typo does not start an empty server.

   Screenshot coming. A NAS container manager with the Beebo container running.

4. Read the first-run message

   A new server has no accounts. It prints a one-time message to its log. Run docker logs beebo.

   What you’ll see: Lines like “First-run setup: this server has no owner account yet.”, an address such as https://192.168.1.20:47811/setup and a setup code shaped like 7KQ2-M9XD-4TNB.

5. Create the owner account

   Open that address. Your browser will warn about the certificate, because Beebo made it itself; accept the warning. Enter the setup code, then choose the owner username and a password of 8 or more characters. Setup closes for good once the account exists. If you miss the message, restart the container for a new code. The code lives only in the log and in memory.

   What you’ll see: A sign-in page. Sign in at https://<server-ip>:47811/. The admin pages only open over HTTPS. Phones and TVs on your network can keep using http://<server-ip>:47811.

6. Add posters and connect your devices

   Give it a TMDB key with the BEEBO_TMDB_API_KEY environment variable (see the free key steps in Get started on Windows). Then connect phones and TVs to http://<server-ip>:47811 as in Connect your phone.

Folders and users

The server never runs as root. Media and /config must be readable, and /config writable, by whoever runs it. Either run the container as the owner of your files (user: in compose, or --user with docker run), or start as root and set PUID and PGID so Beebo takes ownership of /config and then drops to that user. Typical values: Synology 1026:100, Unraid 99:100, TrueNAS SCALE 568:568. On QNAP use your user’s id (id <user> over SSH). Beebo’s port can be changed with BEEBO_PORT, but that changes the address phones use.

Networking and video conversion

• Bridge (default): publish port 47811. Phones on your network use http://<nas-ip>:47811. The router cannot be reached from a bridged container, so automatic port mapping (UPnP) does not work: keep BEEBO_UPNP=0.
• Host network (Linux): the container uses the machine’s network, so router port mapping works as on the desktop. TCP 47811 and UDP 47820–47829 then belong to this container.
• Reverse proxy: Beebo’s admin pages need HTTPS to Beebo itself, so proxy to https://<nas>:47811 and accept its certificate, or place your own cert.pem and key.pem in /config/certs.
• Hardware conversion: video that a device cannot play as it is gets converted while it plays. It works on the processor by default. Pass in an Intel or AMD device (/dev/dri) or use the NVIDIA container toolkit for hardware help. Raspberry Pi uses the processor only. This has not been tested on real graphics hardware; tell us what works for you.

What is in v1, and what is not

Beebo itself is proprietary software. The image includes FFmpeg under the LGPL; you may swap in your own build with BEEBO_FFMPEG. You can also run the same server directly with Node 22 or newer, without Docker.

If something goes wrong

Related pages

Written for Beebo for Windows 0.1.57 and the Beebo Android app 1.38, as of September 21, 2026. Found something that doesn’t match what you see? Tell us at testers@beeboentertainment.com. It is a plain email, with no form and no sign-up.