Docker Setup¶

This is the recommended setup path for running PowerBeacon with minimal host dependencies.

Prerequisites¶

• Docker Engine / Docker Desktop
• Docker Compose v2 (docker compose)
• Open ports: 3000 (frontend), 8000 (backend), 5432 (db for dev compose)

Environment Preparation¶

Create .env from the template at the repository root.

Linux/macOS:

cp .env.example .env

PowerShell:

Copy-Item .env.example .env

At minimum, set these values:

DB_PASSWORD=changeMe
JWT_SECRET=replace-with-strong-secret

Run Production-Like Stack¶

Uses docker-compose.yml.

docker compose up --build

Endpoints:

• Frontend: http://localhost:3000
• Backend API docs: http://localhost:8000/api/docs
• Health: http://localhost:8000/health

Stop:

docker compose down

docker compose up --build

docker compose up -d --build
docker compose logs -f

Run Development Stack (Hot Reload)¶

Uses docker-compose.dev.yml.

docker compose -f docker-compose.dev.yml up --build

Endpoints:

• Frontend (Vite): http://localhost:5173
• Backend: http://localhost:8000
• PostgreSQL (host): localhost:5432

Logs:

docker compose -f docker-compose.dev.yml logs -f

Stop:

docker compose -f docker-compose.dev.yml down

flowchart TD
  A[Start docker-compose.dev.yml] --> B[Backend with reload]
  A --> C[Frontend with Vite HMR]
  A --> D[PostgreSQL]
  B --> E[Instant API feedback]
  C --> F[Instant UI feedback]
  style A fill:#0284c7,stroke:#075985,color:#fff
  style E fill:#16a34a,stroke:#166534,color:#fff
  style F fill:#16a34a,stroke:#166534,color:#fff

Verify Containers¶

docker compose ps

Expected services:

• db
• backend
• frontend

WOL and the Agent Architecture¶

On Docker Desktop (Windows/macOS), direct UDP broadcast from containers is unreliable for LAN wake. PowerBeacon solves this with agents: install the lightweight powerbeacon-agent on a Linux machine in the target LAN, register it in the UI, and assign it to your devices. The backend dispatches WOL packets through the agent over HTTP instead of broadcasting directly.

Troubleshooting¶

Build fails¶

1. Rebuild without cache:

docker compose build --no-cache

1. Check available disk space.

Port conflict¶

If startup fails with bind errors, free or remap conflicting ports (3000, 5173, 8000, 5432).

Backend cannot connect to DB¶

1. Confirm db is healthy:

docker compose ps

1. Confirm DB_PASSWORD in .env matches compose environment assumptions.

Clean reset¶

Use this when local state is corrupted:

docker compose down -v
docker compose up --build

Next Step¶

If you plan to develop features, continue with Local Development.