GitHubTry the live demo
  1. Home
  2. Quick start

Quick start

From one command on your machine to your own wall on Cloudflare's free tier. Start on your machine; add the TV when you want it.

Source: README.md, “Try it” and “Make it yours”Read it on GitHub ↗

The TV shows a new photo full screen with its caption while the guest's phone says You're live
Where the first run ends: a photo from your phone, live on the wall

Before you start

What you need

  • Node 24
  • pnpm 10, through corepack
  • Git

With Node installed, corepack provides the pnpm version the repo pins:

Terminal
$ corepack enable

Try it

On your machine, in one command

No Vega SDK and no Cloudflare account needed:

Terminal
git clone https://github.com/ddedic/boothwall && cd boothwall
pnpm install
pnpm demo --lan

It starts the API and web app on your machine’s network address, adds approved demo photos to a fresh wall and prints display, guest and Control addresses plus the local passcode. Open / on a laptop or projector, scan its QR code with your phone, send a photo and approve it in /control. Your phone needs to be on the same network. Plain pnpm demo keeps everything on localhost, where /snap in a second browser tab stands in for the phone. Ctrl+C stops it.

pnpm web:dev runs the web app alone against the API in your config, at http://localhost:5173. Arrow keys, Enter, Space and Escape stand in for the remote. Add ?demo to run the wall on the bundled photos with no API at all, ?kiosk to hide the cursor and hints, or ?fullscreen to go full screen on the first key press.

On the Vega Virtual Device

You need the Vega SDK with the Virtual Device, Node 24 and pnpm 10. Start the Virtual Device, then run the whole thing:

Terminal
export PATH="$HOME/vega/bin:$PATH"
pnpm tv:vvd:start:1080   # the Virtual Device at 1920×1080
pnpm try

pnpm try is pnpm demo --lan plus the TV: it points urls in the config at your machine while it runs (the TV reads its API at build time; stopping puts the config back), builds the app and opens it on the Virtual Device. The QR code on the TV leads phones to your local wall. To do it by hand, set the urls that pnpm demo --lan prints and run pnpm tv:build:debug && pnpm tv:run:vvd.

Use the Virtual Device’s on-screen remote, or run pnpm remote for a bigger one in your browser. To run without a network, set demo: true in the config and rebuild; in demo mode the remote’s Menu button steps through the four themes.

Make it yours

For developers: about 15 minutes to your own wall on Cloudflare’s free tier.

  1. Configure. Everything event-specific lives in packages/shared/src/config/boothwall.config.ts: the event name, hashtag, categories, brand colours, the badge beside the logo and where it deploys. Set deploy.apiDomain and deploy.webDomain to domains on your Cloudflare account, or to "" for free workers.dev addresses. docs/customising.md explains every field.

  2. Brand it. Swap the logo, the TV backdrop and the icons for yours, keeping the file names (list). To see a fully branded wall first, run pnpm boothwall example conference-booth.

  3. Deploy. Run pnpm exec cf auth login, then pnpm boothwall setup. It creates the D1 database and R2 bucket in your account, sets the Control panel passcode, deploys the API and the web app, and writes the addresses back into the config. After that, pnpm boothwall deploy ships changes.

  4. Put it on the TV. Set tv.wallId in the config (and tv.displayCredential only if your host checks one), then build a release and install it on a Fire TV in developer mode, or on the Virtual Device. The build is yours: it shows that one wall, a different wall means a rebuild, and the config inside it can be extracted, so keep it on your own TVs and never publish the .vpkg (details).

    Terminal
    pnpm tv:build:release
vega run-app apps/tv-vega/build/armv7-release/tv_armv7.vpkg com.boothwall.app.main -d <device>