Getting Started

Prerequisites

Install these on the machine that will run the server:

Install

Clone the repository and install dependencies:

git clone https://github.com/JoeMighty/DisplayGrid.git
cd DisplayGrid
pnpm install

Configure

Copy the example environment files and fill in your values:

cp apps/dashboard/.env.example apps/dashboard/.env.local

Edit apps/dashboard/.env.local:

# Generate a secret (run this in your terminal):
# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
NEXTAUTH_SECRET=your-secret-here

# The public URL of your dashboard
NEXTAUTH_URL=http://localhost:3000

# Absolute path to the SQLite database file
# Windows:   C:/path/to/DisplayGrid/data/displaygrid.db
# Mac/Linux: /path/to/DisplayGrid/data/displaygrid.db
DB_PATH=/path/to/DisplayGrid/data/displaygrid.db

Database

Create the data directory and run the database migrations:

mkdir -p data
pnpm db:migrate

This creates the SQLite database at the path you specified in DB_PATH. Keep regular backups of the data/ folder, which contains your database and all uploaded assets.

Start the services

DisplayGrid needs two processes running simultaneously. Open two terminal windows in the project root:

Terminal 1: Dashboard and display client

pnpm dev

This starts the dashboard at http://localhost:3000 and the display client at http://localhost:5173.

Terminal 2: WebSocket server

node apps/dashboard/ws-server.js

The WebSocket server listens on port 3001 and pushes playlist updates to connected display clients in real time.

Setup wizard

On your first visit to http://localhost:3000, you'll be redirected to the setup wizard. It walks through:

1. App name: shown in the dashboard sidebar and browser tab
2. Super Admin account: the primary administrator username and password
3. Kiosk PIN: used to unlock display clients from kiosk mode
4. Kiosk key combo: the key combination that triggers the unlock panel

After the wizard completes, you'll be redirected to the dashboard login page. Sign in with the Super Admin credentials you just created.

Add your first screen

1. Go to Zones and create a zone (e.g. "Main Lobby").
2. Go to Screens and click New Screen. Give it a name, assign it to your zone, and set the resolution. Click Add screen.
3. Go to Playlists. You'll see a playlist was automatically created for your new screen. Click it to open the playlist builder.
4. Go to Assets and upload an image or video. Then go back to the playlist and add it as a slide.

Connect a display

1. On the Screens page, click the key icon on your screen card to view its token.
2. On the device you want to use as a display, open a browser and go to http://<server-ip>:5173.
3. Enter the screen token when prompted. The display will connect to the WebSocket server and start playing your playlist.

To skip the token entry screen on future boots, set VITE_SCREEN_TOKEN in apps/display-client/.env.local. See the Kiosk Setup guide for details.

Local domain (optional)

For a cleaner URL (http://displaygrid.test instead of http://localhost:3000), add a hosts file entry. Run the setup script for your OS:

Windows (run PowerShell as Administrator)

.\scripts\add-hosts.ps1

macOS / Linux

sudo ./scripts/add-hosts.sh

Then update NEXTAUTH_URL in your .env.local to http://displaygrid.test:3000.

For truly clean URLs with no port number, use Caddy as a reverse proxy. See the Network guide.