openstatus.dev
Openstatus
www.openstatus.dev
1# Docker Setup Guide
2
3Complete guide for running OpenStatus with Docker
4
5## Quick Start
6
7```bash
8# 1. Copy environment file
9cp .env.docker.example .env.docker
10
11# 2. Configure required variables (see Configuration section)
12vim .env.docker
13
14# 3. Build and start services (migrations will run automatically)
15export DOCKER_BUILDKIT=1
16docker compose up -d
17
18# 4. Check service health
19docker compose ps
20
21# 5. (Optional) Seed database with test data
22docker run --rm --network openstatus \
23 -e DATABASE_URL=http://libsql:8080 \
24 $(docker build -q -f apps/workflows/Dockerfile --target build .) \
25 sh -c "cd /app/packages/db && bun src/seed.mts"
26
27# 6. (Optional) Deploy Tinybird local - requires tb CLI
28cd packages/tinybird
29tb --local deploy
30
31# 7. Access the application
32open http://localhost:3002 # Dashboard
33open http://localhost:3003 # Status Page Theme Explorer
34# Note: Status pages are accessed via subdomain/slug (e.g., http://localhost:3003/status)
35```
36
37## Cleanup
38
39```bash
40# Remove stopped containers
41docker compose down
42
43# Remove volumes
44docker compose down -v
45
46# Clean build cache
47docker builder prune
48```
49
50## Services
51
52| Service | Port | Purpose |
53|---------|------|---------|
54| workflows | 3000 | Background jobs |
55| server | 3001 | API backend (tRPC) |
56| dashboard | 3002 | Admin interface |
57| status-page | 3003 | Public status pages |
58| private-location | 8081 | Monitoring agent |
59| libsql | 8080 | Database (HTTP) |
60| libsql | 5001 | Database (gRPC) |
61| tinybird-local | 7181 | Analytics |
62
63
64## Architecture
65
66```
67┌─────────────┐ ┌─────────────┐
68│ Dashboard │────▶│ Server │
69│ (Next.js) │ │ (Bun) │
70└─────────────┘ └─────────────┘
71 │ │
72 ▼ ▼
73┌─────────────┐ ┌─────────────┐
74│ Status Page │ │ Workflows │
75│ (Next.js) │ │ (Bun) │
76└─────────────┘ └─────────────┘
77 │ │
78 └────────┬───────────┘
79 ▼
80 ┌─────────────┐
81 │ LibSQL │
82 │ (Database) │
83 └─────────────┘
84```
85
86## Database Setup
87
88### Automatic Migrations
89
90Migrations run **automatically** when you start the stack with `docker compose up -d`.
91
92**Verifying migrations:**
93```bash
94# Check workflows logs for migration output
95docker compose logs workflows | grep -A 5 "Running database migrations"
96
97# Should show:
98# openstatus-workflows | Running database migrations...
99# openstatus-workflows | Migrated successfully
100# openstatus-workflows | Starting workflows service...
101```
102
103**Manual migration:**
104
105If you need to re-run migrations or troubleshoot:
106
107```bash
108# Run migrations using workflows container
109docker compose exec workflows sh -c "cd /app/packages/db && bun src/migrate.mts"
110
111# Or restart workflows to trigger migrations again
112docker compose restart workflows
113```
114
115### Seeding Test Data (Optional)
116
117**Note:** Migrations run automatically, but seeding does **not**. You must manually seed the database if you want test data.
118
119After migrations complete, seed the database with sample data:
120
121```bash
122docker run --rm --network openstatus \
123 -e DATABASE_URL=http://libsql:8080 \
124 $(docker build -q -f apps/workflows/Dockerfile --target build .) \
125 sh -c "cd /app/packages/db && bun src/seed.mts"
126```
127
128This creates:
129- 3 workspaces (`love-openstatus`, `test2`, `test3`)
130- 5 sample monitors and 1 status page with slug `status`
131- Test user account: `ping@openstatus.dev`
132- Sample incidents, status reports, and maintenance windows
133
134**Verifying seeded data:**
135```bash
136# Check table counts via libsql HTTP API
137curl -s http://localhost:8080/ -H "Content-Type: application/json" \
138 -d '{"statements":["SELECT COUNT(*) FROM page"]}' | jq -r '.[0].results.rows[0][0]'
139
140# Should output: 1
141```
142
143**Accessing Seeded Data:**
144
145After seeding, you can access the test data:
146
147**Dashboard:**
1481. Navigate to http://localhost:3002/login
1492. Use magic link authentication with email: `ping@openstatus.dev`
1503. Check your console/logs for the magic link (with `SELF_HOST=true` in `.env.docker`)
1514. After logging in, you'll see the `love-openstatus` workspace with all seeded monitors and status page
152
153**Status Page:**
154- The seeded status page has slug `status`
155- Access it via subdomain routing: http://status.localhost:3003
156- Or view theme explorer at: http://localhost:3003
157
158**If you use a different email address**, the system will create a new empty workspace for you instead of showing the seeded data. To access seeded data with a different account, you must add your user to the seeded workspace using SQL:
159
160 ```bash
161 # First, find your user_id
162 curl -X POST http://localhost:8080/ -H "Content-Type: application/json" \
163 -d '{"statements":["SELECT id, email FROM user"]}'
164
165 # Then add association (replace USER_ID with your id)
166 curl -X POST http://localhost:8080/ -H "Content-Type: application/json" \
167 -d '{"statements":["INSERT INTO users_to_workspaces (user_id, workspace_id, role) VALUES (USER_ID, 1, '\''owner'\'')"]}'
168 ```
169
170
171## Tinybird Setup (Optional)
172
173Tinybird is used for analytics and monitoring metrics. The application will work without it, but analytics features will be unavailable.
174
175If you want to enable analytics, you can:
1761. Use Tinybird Cloud and configure `TINY_BIRD_API_KEY` in `.env.docker`
1772. Manually configure Tinybird Local (requires additional setup beyond this guide)
178
179## Configuration
180
181### Required Environment Variables
182
183Edit `.env.docker` and set:
184
185```bash
186# Authentication
187AUTH_SECRET=your-secret-here
188
189# Database
190DATABASE_URL=http://libsql:8080
191DATABASE_AUTH_TOKEN=basic:token
192
193# Email
194RESEND_API_KEY=test
195```
196
197### Optional Services
198
199Configure these for full functionality:
200
201```bash
202# Redis
203UPSTASH_REDIS_REST_URL=
204UPSTASH_REDIS_REST_TOKEN=
205
206# Analytics
207TINY_BIRD_API_KEY=
208
209# OAuth providers
210AUTH_GITHUB_ID=
211AUTH_GITHUB_SECRET=
212AUTH_GOOGLE_ID=
213AUTH_GOOGLE_SECRET=
214```
215
216See [.env.docker.example](.env.docker.example) for complete list.
217
218## Development Workflow
219
220### Common Commands
221
222```bash
223# View logs
224docker compose logs -f [service-name]
225
226# Restart service
227docker compose restart [service-name]
228
229# Rebuild after code changes
230docker compose up -d --build [service-name]
231
232# Stop all services
233docker compose down
234
235# Reset database (removes all data)
236docker compose down -v
237docker compose up -d
238# Migrations run automatically on startup
239```
240
241### Authentication
242
243**Magic Link**:
244
245Set `SELF_HOST=true` in `.env.docker` to enable email-based magic link authentication. This allows users to sign in without configuring OAuth providers.
246
247**OAuth Providers**:
248
249Configure GitHub/Google OAuth credentials in `.env.docker` and set up callback URLs:
250 - GitHub: `http://localhost:3002/api/auth/callback/github`
251 - Google: `http://localhost:3002/api/auth/callback/google`
252
253### Creating Status Pages
254
255**Via Dashboard (Recommended)**:
2561. Login to http://localhost:3002
2572. Create a workspace
2583. Create a status page with a slug
2594. Access at http://localhost:3003/[slug]
260
261**Via Database (Testing)**:
262```bash
263# Insert test data
264curl -s http://localhost:8080/v2/pipeline \
265 -H 'Content-Type: application/json' \
266 --data-raw '{
267 "requests":[{
268 "type":"execute",
269 "stmt":{
270 "sql":"INSERT INTO workspace (id, slug, name) VALUES (1, '\''test'\'', '\''Test Workspace'\'');"
271 }
272 }]
273 }'
274```
275
276### Resource Limits
277
278Add to `docker-compose.yaml`:
279
280```yaml
281services:
282 dashboard:
283 deploy:
284 resources:
285 limits:
286 cpus: '1.0'
287 memory: 1G
288 reservations:
289 cpus: '0.5'
290 memory: 512M
291```
292
293## Monitoring
294
295### Health Checks
296
297All services have automated health checks:
298
299```bash
300# View health status
301docker compose ps
302
303# Inspect specific service
304docker inspect openstatus-dashboard --format='{{.State.Health.Status}}'
305```
306
307## Getting Help
308
309- **Documentation**: [docs.openstatus.dev](https://docs.openstatus.dev)
310- **Discord**: [openstatus.dev/discord](https://www.openstatus.dev/discord)
311- **GitHub Issues**: [github.com/openstatusHQ/openstatus/issues](https://github.com/openstatusHQ/openstatus/issues)