BEFORE YOU START
A computer. A browser.
A little terminal time.
You need Python 3.11 or newer, Git, and Poetry 2.x. Use a modern browser for the room display and admin panel.
The display, admin panel, timer, hints, sounds and settings. Physical GPIO and Raspberry Pi monitor-power controls aren’t available on a standard macOS computer. Expected GPIO warnings don’t stop the app.
The project’s local guide covers Windows, Linux and macOS. The macOS steps use Homebrew and the project’s Poetry environment.
These steps use Flask’s development server on port 5000. For a dedicated Pi, follow the production kiosk guide: Gunicorn on internal port 8080, with NGINX on port 80 so you can open the Pi’s address without a port. Changing to 8080 alone does not remove the port from the URL.
Install the tools.
Install Homebrew using its official instructions. Follow its printed Next steps to add it to your shell PATH, then open a new Terminal window:
brew install python git pipx
pipx ensurepathOpen a new Terminal window again to load the updated PATH:
pipx install poetry
python3 --version
poetry --versionIf an older system Python is still first on PATH, use the Homebrew interpreter explicitly in the project: poetry env use "$(brew --prefix)/bin/python3".
Get the application.
Clone the public repository using HTTPS — no GitHub SSH key is required.
git clone https://github.com/Your-Grandad/Escape-Room-Screen.git
cd Escape-Room-Screen
poetry env use "$(brew --prefix)/bin/python3"
poetry installSet your secrets. Start the server.
Replace the admin password below with a long, unique password. These environment variables only last for the current terminal window. Keep your signing key stable between launches; save it securely outside the repository.
export SECRET_KEY="$(poetry run python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export ADMIN_PASSWORD="replace-with-a-long-unique-password"
poetry run flask --app escape_room_screen.app:create_app run --host=0.0.0.0 --port=50000.0.0.0 allows other devices on your network to connect. Use --host=127.0.0.1 for this computer only. Don’t port-forward this Flask server to the public internet.
Meet your room screen.
Keep the server terminal open. Open these addresses in your browser:
Sign in to the installed app with username admin and the password you set. This is the app’s staff login, not an account on this website. The superuser can create operator accounts under Settings > Users.
From another device on the same network, replace 127.0.0.1 with this computer’s local IP address:
Find your local IP under System Settings > Network > your active connection > Details > TCP/IP.
Press Ctrl + C in the server terminal to stop it. To make a temporary full-screen display, use your browser’s full-screen command. For unattended boot-to-screen operation, follow the Raspberry Pi kiosk guide.
The embedded live preview is deliberately silent. Open the main display, allow browser audio with an initial click if needed, and check tab mute, system volume and the output device. Save custom event files under Settings > Sounds, then trigger the matching event; without a custom file, the app uses a built-in tone. Audio hint presets are separate. Pi HDMI card names, .asoundrc and X11 cursor flags are not desktop setup steps.
Settings, statistics and uploaded sounds live in src/instance/. Back up that directory before replacing your checkout. Passwords changed in the app are stored in its database; the stored admin password takes precedence over ADMIN_PASSWORD on later starts.
WHEN SOMETHING DOESN’T CLICK
Quick fixes.
Poetry is not recognized or not found
Close and reopen the terminal after pipx ensurepath. Run pipx list and follow its PATH instructions if it’s still missing.
Port 5000 is already in use
Use another port, then open the display and admin URLs with :5001 instead.
poetry run flask --app escape_room_screen.app:create_app run --host=0.0.0.0 --port=5001Another device can’t open the screen
Use the server’s local IP, not 127.0.0.1. Check that both devices are on the same trusted network, the server uses --host=0.0.0.0, and the firewall permits your local connection. Guest Wi-Fi may isolate devices.
GPIO warnings appear, or monitor controls are disabled
That’s expected without Raspberry Pi hardware and vcgencmd. The browser display and staff controls still work. Use the Pi guide for GPIO and HDMI-power support.
Make it your room.
Open Settings > Customisation in the admin panel to set the title, starting duration, colours and images. Save custom audio under Settings > Sounds, then test a full run on the main player display before opening the room. The embedded live preview is deliberately silent.
Follow the game screen customisation guide ↗
Learn hints, room controls & recorded results ↗
Back to installation guides ↗