Photobooth: a self-hosted photo box for Raspberry Pi and Linux events

A photo booth aimed at event operators, not photo galleries

Photobooth is a web interface for Linux and Windows that the README calls a Photobooth web interface, often referred to as a photo box in some languages and regions. Its origin story is specific: it was first developed by Andre Rinas to run on a Raspberry Pi, and in 2019 Andreas Blaesius picked up the work and continued on it. That lineage explains almost every design decision in the current code, including the emphasis on Raspberry Pi OS, GPIO input, and the admin panel.

The audience is a person running an event, not a person building a photo-sharing website. The repository topics list photobooth-wedding, raspberry, and raspberry-pi. The intended flow is a guest walks up to a screen, sees a live preview, takes a picture, gets a printed frame or a QR code to download it, and the shot joins a gallery that the operator browses afterwards. Configuration for a specific occasion, such as a wedding or a birthday, can even show a symbol between text on the start page.

Because everything runs on the box itself, the operational surface is unusually physical. The admin panel at localhost/admin exposes disk usage, gallery appearance, login protection, print behaviour and hardware button wiring. That is a different product category from a hosted photo service, and it means the decisions you make about cameras and printing hardware shape the software experience as much as the code does.

Live preview, GD processing and a PhotoSwipe gallery

The runtime is PHP with image handling done by GD. The gallery is built on PhotoSwipe v5, and the project points at its own PhotoSwipe fork hosted under the PhotoboothProject organisation rather than the upstream release. On top of that base the README lists a set of concrete features that map to real code paths in the tree.

Photo composition happens in the app itself. The admin panel offers a filter to apply after taking a picture, a photo collage function, chroma keying, and several live preview options. Images can carry an optional printed frame, optional text, and an optional QR code on the right side. File names can be date-formatted or random, which matters when a job runs all night and you want to order the gallery by capture time.

Three read-only pages sit beside the main flow. A standalone gallery is reachable at localhost/gallery, a standalone slideshow at localhost/slideshow, and an offline manual with settings explained at localhost/manual, plus an offline FAQ at localhost/manual/faq. Both gallery and slideshow are based on the same PhotoSwipe v5 code, so the operator can put a screen in a different room from the capture device without hunting for a second frontend.

One structural point is worth stating plainly: Node.js is a build dependency here, not a runtime one. The package.json scripts compile Sass with gulp, run eslint and prettier, and install PHP packages through php bin/composer. The server process that actually serves photos is PHP behind Apache or Nginx.

Two install paths: the shell installer and the Docker image

The repository ships install-photobooth.sh at the top level alongside a Dockerfile and a docker-compose.yml, and the README states that the installer checks your Node.js version and suggests an update or downgrade when needed. That script is the documented path for a bare Raspberry Pi or Linux host, and the container route exists for people who would rather pin the stack.

The container is built from a PHP 8.4 Apache base image and pulls in the tooling a real camera booth needs, including gphoto2 for DSLR control and libimage-exiftool-perl for metadata handling:

FROM webdevops/php-apache:8.4
WORKDIR /app
COPY . .
USER application

The image raises the Apache request line limit because large uploads and camera transfers need it, installs Node 20 from NodeSource, and builds the frontend as a non-root user. The companion compose file exposes HTTP and HTTPS and pins the Composer version:

version: "3.9"

services:
  photobooth:
    build: .
    ports:
      - "80:80"
      - "443:443"
    environment:
      - COMPOSER_VERSION=2

The build itself runs the npm script chain that also produces distributable archives:

    "build": "npm-run-all --serial composer:install format build:gulp build:head clean:skipwelcome",
    "build:gulp": "gulp",
    "pack:zip": "node scripts/pack-build.js",
    "composer:install": "php bin/composer install",

Note that the container bakes the built assets into the image. If you change gallery styling or language files you must rebuild, because there is no runtime asset pipeline described for the PHP side.

Version floors that the README and package.json disagree on

The README publishes a prerequisites table: Node.js at v20.15.0 or newer, npm at v10.7.0 or newer, php at v8.4 or newer, and Apache or Nginx as the webserver, with the note that by default Apache is installed by the installer. The Node.js row adds that only v20 is currently tested and that versions below v20 are not supported anymore.

The package.json tells a slightly different story. Its engines block asks for node at 20.15.0 or newer and npm at 9.6.5 or newer, which is a lower npm floor than the README states. Small gap, but it is exactly the sort of mismatch that surfaces when a scripted install runs against the machine rather than against the documentation.

The practical consequence is that you should treat the README table as the contract and let the installer do the check. It is documented to inspect the Node.js version and offer an update or downgrade suggestion, which is a better path than hand-tuning versions on a Pi that also has to run a camera stack.

There is also a channel choice to make. The default branch is dev, where the package.json version reads 4.99.0, while the newest tagged releases are v4.5.1 and v4.5.0 from 2024-09-17. Development commits are therefore ahead of the published tags by a wide margin, and a self-hosted operator has to decide deliberately whether to track the dev branch or pin to a tag.

Driving the screen with buttons, a rotary encoder and the print queue

The hardware integration is the part that separates a photo booth from a web page with a camera attached. The admin panel offers two modes for GPIO input, and the README spells out what each does.

In Button Mode, distinct hardware buttons connect to distinct GPIOs and each button triggers a separate function, so a physical shutter button can sit next to a button that jumps to the gallery. In Rotary Mode, a rotary encoder connected to GPIOs drives the on-screen input, letting you scroll through the photobooth interface buttons and click to select actions. For a wooden enclosure with a single knob, Rotary Mode is the only one of the two that makes sense, and the fact that it ships as a first-class mode rather than a community patch says something about how much real hardware this project has faced.

Printing is configurable in fine-grained steps rather than as one toggle. You can print a frame on the picture, print text on the picture, and print a QR code on the right side. Auto print is optional, the delay before auto printing can be adjusted, the visibility window for the started printing message can be adjusted, a defined key can trigger a print, and the print button can be shown independently, for example visible only in the gallery.

Around that sit the non-physical channels: pictures can be sent by e-mail, and a QR code on screen lets guests download from the booth directly. The gallery look and feel is adjustable from the same admin panel, and login can be enabled for the admin panel, the start page, or the manual and FAQ independently, so a public kiosk screen does not have to expose the configuration surface.

Where photobooth is the wrong tool

The supported platforms table is short enough to expose the hard limits. On Raspberry Pi 3, 4 and 5 running Raspberry Pi OS 64bit Bookworm or Trixie, the camera options are camera modules, gphoto2 supported DSLRs, and webcam. On a generic PC with Debian or Ubuntu, the options are gphoto2 DSLRs and webcam. On Windows, the options are digiCamControl and webcam. There is no generic IP camera entry anywhere in that table.

The webcam footnote is the sharpest constraint in the README. Capture from a webcam works through third-party software such as fswebcam on Linux, and otherwise it only works on access via http://localhost. That local-only limitation means a headless booth with a USB webcam on a remote machine is not a supported configuration, and no amount of configuration will change it.

There is a second, softer limit: the project assumes a physical interaction loop with a screen, a trigger, and a printer. If your goal is remote monitoring, cloud-hosted galleries with sharing links, or multi-site fleet management, none of those appear anywhere in the repository layout. The top-level directories are capture, gallery, slideshow, login, admin, api, chroma, faq, and manual, all local.

Printers are the other silent gap. The admin panel exposes every option around printing, but no printer model or driver is named in the documentation, so the printing path is worth verifying on your own hardware before promising it to a paying event.

Maintenance pace, licence and the cost of running the dev branch

The repository is not archived, and the last push was on 2026-10-19. Recent releases sit much further back: v4.5.1 and v4.5.0 were both tagged on 2024-09-17, and v4.4.1 on 2024-02-19. Commits have continued to land on the dev branch while the published tags have not moved, so the release history is thin relative to the activity in the tree. The homepage photoboothproject.github.io is where the README points for the full changelog.

Running the dev branch means running untagged commits, and the tooling for that is part of the repository rather than an external setup. A pre-commit config, phpstan.neon, phpunit.xml, an eslint config and a gulpfile all sit at the top level, and the build script chains composer install, formatting, gulp and a clean step in sequence. A team that only wants to operate the booth can ignore those, but anyone changing the frontend inherits a formatting and linting gate that runs on every build.

The licence is MIT, as recorded in both the LICENSE file and the package.json metadata. A separate LICENSE_NOTICE file also exists in the repository root, which is the file to read for the obligations attached to bundled third-party code such as the PhotoSwipe fork and the packaged PHP dependencies. Licence implications for a self-hosted internal deployment are usually straightforward, but a hosted service built on top of the project is where attribution and notice handling start to matter.

Editorial conclusion

Adopt Photobooth if you are running a wedding or birthday event, you control the hardware, and you are comfortable maintaining a PHP plus Node build chain on a Raspberry Pi. Skip it if you need a camera over the network, a managed service, or a Windows workstation without digiCamControl. Verify first that your exact camera combination appears in the supported platforms table, that your Node, npm and PHP versions clear the stated floors, and that you can accept tagged releases lagging behind the dev branch, since the last push was on 2026-10-19 while the newest tag is v4.5.1 from 2024-09-17.

Frequently asked questions

Official sources

1. License: MIT
2. PhotoboothProject/photobooth on GitHub
3. Project website
4. README
5. Releases