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
15export DOCKER_BUILDKIT=1
16docker compose up -d
17
18# 4. Check service health
19docker compose ps
20
21# 5. Run database migrations (required)
22cd packages/db
23pnpm migrate
24
25# 6. Deploy Tinybird local
26cd packages/tinybird
27tb --local deploy
28
29# 7. Seed database with test data (optional)
30cd packages/db
31pnpm seed
32
33
34# 8. Access the application
35open http://localhost:3002 # Dashboard
36open http://localhost:3003 # Status Pages
37```
38
39## Cleanup
40
41```bash
42# Remove stopped containers
43docker compose down
44
45# Remove volumes
46docker compose down -v
47
48# Clean build cache
49docker builder prune
50```
51
52## Services
53
54| Service | Port | Purpose |
55|---------|------|---------|
56| workflows | 3000 | Background jobs |
57| server | 3001 | API backend (tRPC) |
58| dashboard | 3002 | Admin interface |
59| status-page | 3003 | Public status pages |
60| private-location | 8081 | Monitoring agent |
61| libsql | 8080 | Database (HTTP) |
62| libsql | 5001 | Database (gRPC) |
63| tinybird-local | 7181 | Analytics |
64
65
66## Architecture
67
68```
69┌─────────────┐ ┌─────────────┐
70│ Dashboard │────▶│ Server │
71│ (Next.js) │ │ (Bun) │
72└─────────────┘ └─────────────┘
73 │ │
74 ▼ ▼
75┌─────────────┐ ┌─────────────┐
76│ Status Page │ │ Workflows │
77│ (Next.js) │ │ (Bun) │
78└─────────────┘ └─────────────┘
79 │ │
80 └────────┬───────────┘
81 ▼
82 ┌─────────────┐
83 │ LibSQL │
84 │ (Database) │
85 └─────────────┘
86```
87
88## Database Setup
89
90The LibSQL container starts with an empty database. You must run migrations before using the application:
91
92```bash
93cd packages/db
94pnpm migrate
95```
96
97### Seeding Test Data (Optional)
98
99For development, you can populate the database with sample data:
100
101```bash
102cd packages/db
103pnpm seed
104```
105
106This creates:
107- 3 workspaces (`love-openstatus`, `test2`, `test3`)
108- 5 sample monitors and 1 status page
109- Test user account: `ping@openstatus.dev`
110- Sample incidents, status reports, and maintenance windows
111
112**Accessing Seeded Data:**
113
114To view the seeded data in the dashboard, you must log in using the seeded test email:
115
1161. Navigate to http://localhost:3002/login
1172. Use magic link authentication with email: `ping@openstatus.dev`
1183. Check your console/logs for the magic link
1194. After logging in, you'll be in the `love-openstatus` workspace with all seeded data
120
121**If you use a different email address**, the system will create a new empty workspace for you. To access seeded data with a different account:
122
1231. Add your user to the seeded workspace using SQL:
124 ```bash
125 # First, find your user_id
126 curl -X POST http://localhost:8080/ -H "Content-Type: application/json" \
127 -d '{"statements":["SELECT id, email FROM user"]}'
128
129 # Then add association (replace USER_ID with your id)
130 curl -X POST http://localhost:8080/ -H "Content-Type: application/json" \
131 -d '{"statements":["INSERT INTO users_to_workspaces (user_id, workspace_id, role) VALUES (USER_ID, 1, '\''owner'\'')"]}'
132 ```
133
1342. Switch to the `love-openstatus` workspace using the workspace switcher in the dashboard sidebar
135
136## Tinybird Setup (Optional)
137
138Tinybird is used for analytics and monitoring metrics. The application will work without it, but analytics features will be unavailable.
139
140If you want to enable analytics, you can:
1411. Use Tinybird Cloud and configure `TINY_BIRD_API_KEY` in `.env.docker`
1422. Manually configure Tinybird Local (requires additional setup beyond this guide)
143
144## Configuration
145
146### Required Environment Variables
147
148Edit `.env.docker` and set:
149
150```bash
151# Authentication
152AUTH_SECRET=your-secret-here
153
154# Database
155DATABASE_URL=http://libsql:8080
156DATABASE_AUTH_TOKEN=basic:token
157
158# Email
159RESEND_API_KEY=test
160```
161
162### Optional Services
163
164Configure these for full functionality:
165
166```bash
167# Redis
168UPSTASH_REDIS_REST_URL=
169UPSTASH_REDIS_REST_TOKEN=
170
171# Analytics
172TINY_BIRD_API_KEY=
173
174# OAuth providers
175AUTH_GITHUB_ID=
176AUTH_GITHUB_SECRET=
177AUTH_GOOGLE_ID=
178AUTH_GOOGLE_SECRET=
179```
180
181See [.env.docker.example](.env.docker.example) for complete list.
182
183## Development Workflow
184
185### Common Commands
186
187```bash
188# View logs
189docker compose logs -f [service-name]
190
191# Restart service
192docker compose restart [service-name]
193
194# Rebuild after code changes
195docker compose up -d --build [service-name]
196
197# Stop all services
198docker compose down
199
200# Reset database (removes all data)
201docker compose down -v
202# After resetting, re-run migrations:
203# cd packages/db && pnpm migrate
204```
205
206### Authentication
207
208**Magic Link**:
209
210Set `SELF_HOST=true` in `.env.docker` to enable email-based magic link authentication. This allows users to sign in without configuring OAuth providers.
211
212**OAuth Providers**:
213
214Configure GitHub/Google OAuth credentials in `.env.docker` and set up callback URLs:
215 - GitHub: `http://localhost:3002/api/auth/callback/github`
216 - Google: `http://localhost:3002/api/auth/callback/google`
217
218### Creating Status Pages
219
220**Via Dashboard (Recommended)**:
2211. Login to http://localhost:3002
2222. Create a workspace
2233. Create a status page with a slug
2244. Access at http://localhost:3003/[slug]
225
226**Via Database (Testing)**:
227```bash
228# Insert test data
229curl -s http://localhost:8080/v2/pipeline \
230 -H 'Content-Type: application/json' \
231 --data-raw '{
232 "requests":[{
233 "type":"execute",
234 "stmt":{
235 "sql":"INSERT INTO workspace (id, slug, name) VALUES (1, '\''test'\'', '\''Test Workspace'\'');"
236 }
237 }]
238 }'
239```
240
241### Resource Limits
242
243Add to `docker-compose.yaml`:
244
245```yaml
246services:
247 dashboard:
248 deploy:
249 resources:
250 limits:
251 cpus: '1.0'
252 memory: 1G
253 reservations:
254 cpus: '0.5'
255 memory: 512M
256```
257
258## Monitoring
259
260### Health Checks
261
262All services have automated health checks:
263
264```bash
265# View health status
266docker compose ps
267
268# Inspect specific service
269docker inspect openstatus-dashboard --format='{{.State.Health.Status}}'
270```
271
272## Getting Help
273
274- **Documentation**: [docs.openstatus.dev](https://docs.openstatus.dev)
275- **Discord**: [openstatus.dev/discord](https://www.openstatus.dev/discord)
276- **GitHub Issues**: [github.com/openstatusHQ/openstatus/issues](https://github.com/openstatusHQ/openstatus/issues)