Docker Setup
FiestaBoard runs as a single Docker container that bundles the web UI, API, and display service together. This page explains the architecture for users who want to understand what's running under the hood or customize their deployment.
Most users don't need this page
If you followed the Quick Start or Beginner's Guide, everything is already configured correctly. This page is for advanced configuration and troubleshooting.
Upgrading from V1?
V1 used two containers (fiestaboard-api on port 8000 and fiestaboard-ui on port 8080). V2 consolidates everything into one container on port 4420. See the V2 Migration Guide for full upgrade instructions.
Architecture
FiestaBoard runs in a single unified container:
| Container | Service | Port | Description |
|---|---|---|---|
fiestaboard | Nginx + FastAPI + Next.js | 4420 | Web UI, REST API, display service, plugin system |
┌──────────────────────────────────────────────┐
│ Browser │
│ http://localhost:4420 │
└──────────────────┬───────────────────────────┘
│
┌──────────────────▼───────────────────────────┐
│ fiestaboard (Nginx) │
│ Port 4420 │
│ ┌────────────┐ ┌───────────────────────┐ │
│ │ Static UI │ │ Proxy /api → FastAPI │ │
│ └────────────┘ └───────────────────────┘ │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ FastAPI Backend │ │
│ │ ┌────────────┐ ┌──────────────┐ │ │
│ │ │ REST API │ │Display Service│ │ │
│ │ │ │ │Plugin System │ │ │
│ │ └────────────┘ └──────────────┘ │ │
│ └──────────────────────────────────────┘ │
└──────────────────────────────────────────────┘
Docker Compose Files
| File | Use Case |
|---|---|
docker-compose.yml | Standard deployment |
docker-compose.dev.yml | Development with hot reload |
docker-compose.prod.yml | Production-optimized |
docker-compose.hub.yml | Using pre-built images from Docker Hub |
Quick Start
# Standard deployment
docker compose up -d --build
# Development with hot reload
docker compose -f docker-compose.dev.yml up --build
# Using pre-built images (no build needed)
docker compose -f docker-compose.hub.yml up -d
Access Points
| Service | URL | Description |
|---|---|---|
| Web UI | http://localhost:4420 | Main application interface (from the same machine) |
| Web UI (network) | http://<host-ip>:4420 | Access from other devices with the default bridge setup |
| Find it | https://fiestaboard.app/find/ | Searches your network for FiestaBoard when you don't know the host's IP |
| API | http://localhost:4420/api | API access (via nginx proxy) |
| API Docs | http://localhost:4420/api/docs | Interactive FastAPI documentation |
Accessing from other devices
The default Docker bridge publishes port 4420 but does not publish its mDNS records onto your LAN. Use the host's IP address, for example http://192.168.1.50:4420. The FiestaPi image separately advertises fiestapi.local from the host. On other installations, configure a host-level mDNS service for Bonjour discovery. Host networking can expose the container advertisement, but nginx then listens on port 3000, so set MDNS_PORT=3000 unless you provide a separate port 4420 proxy.
Key API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/health | GET | Health check |
/status | GET | Service status and configuration |
/config | GET | Current configuration |
/refresh | POST | Refresh current display |
/force-refresh | POST | Force refresh (bypasses cache) |
/dev-mode | POST | Toggle development mode |
/send-message | POST | Send a message to the board |
/plugins | GET | List all plugins |
/plugins/{id}/data | GET | Get plugin data |
See the API Endpoints reference for the complete list.
Data Persistence
FiestaBoard stores all runtime state on disk so that configuration, pages, and schedules survive container restarts and image upgrades.
What is persisted
Two host directories are bind-mounted into the container:
| Host path | Container path | Contents |
|---|---|---|
./data/ | /app/data/ | All application state (see table below) |
./external_plugins/ | /app/external_plugins/ | Marketplace plugins installed via the Integrations page |
Files inside data/:
| File | Description |
|---|---|
config.json | Board connection settings, API keys, plugin configuration |
settings.json | Display preferences, transitions, schedule, MQTT, active page |
pages.json | All board pages you have created |
schedules.json | Time-based scheduling rules |
carousels.json | Carousel display settings |
logs/ | Application, API, and nginx log files |
*.backup | Pre-migration backups created automatically before schema upgrades |
This is configured in every Docker Compose file:
volumes:
- ./data:/app/data
- ./external_plugins:/app/external_plugins
Running with plain docker run
If you start the container directly without Docker Compose, pass the volume flags explicitly — otherwise data is lost when the container is removed:
docker run -d \
--name fiestaboard \
-p 4420:3000 \
-v "$(pwd)/data:/app/data" \
-v "$(pwd)/external_plugins:/app/external_plugins" \
fiestaboard/fiestaboard:latest
Data loss without volume mounts
If you run docker run without -v flags, Docker creates an anonymous volume for /app/data (from the VOLUME directive in the image). The data still persists between restarts of the same container, but is permanently lost when you run docker rm. Always use explicit bind-mounts or named volumes for anything you want to keep.
Backup and restore
# Backup (from the directory containing your docker compose file)
tar -czf fiestaboard-backup-$(date +%Y%m%d).tar.gz data/ external_plugins/
# Restore
tar -xzf fiestaboard-backup-20240101.tar.gz
docker compose up -d
All configuration, pages, schedules, and installed plugins are captured in a single archive.
Updating FiestaBoard
# Pull latest code
git pull
# Rebuild and restart
docker compose down
docker compose up -d --build
Environment Variables
The .env file holds the board connection and system settings. See the Environment Variables reference for the complete list.
Configure plugins in the web UI. A plugin variable that is set in .env (for example HOME_ASSISTANT_BASE_URL) overrides the value saved in the UI for as long as it is set, and FiestaBoard logs a warning when it does. The plugin lines in env.example are commented out for this reason. Leave them that way unless you want the environment to win. To go back to the UI value, delete the line and recreate the container with docker compose up -d. A restart does not reload .env.
Next Steps
- Cloud API Setup - Use cloud API instead of local
- Raspberry Pi Deployment - Deploy on a Pi
- Environment Variables - All configuration options