Move config files to config/ directory (tailwind.config.js, workbox-config.js, weeder.toml). Move documentation to docs/ (DEVELOPMENT.md, DOCKER_COMPOSE_README.md). Update all references in Dockerfile, Makefile, tailwind.css, and documentation.
5.5 KiB
Docker Compose Setup for Monoscope
This Docker Compose configuration provides a complete development environment for Monoscope with TimescaleDB.
Quick Start
1. Basic Usage
Start both TimescaleDB and Monoscope:
# Pull the latest Monoscope image from GitHub Packages (if needed)
docker pull ghcr.io/monoscope-tech/monoscope:latest
# Start services
docker-compose up -d
This will:
- Start TimescaleDB on port 5432
- Pull and start Monoscope from GitHub Packages on port 8080 (HTTP) and 4317 (gRPC)
- Automatically run database migrations
- Set up with basic authentication (admin/changeme)
2. Access the Application
- Monoscope Web UI: http://localhost:8080
- gRPC/OTLP Endpoint: localhost:4317
- PostgreSQL/TimescaleDB: localhost:5432
- Database:
apitoolkit - User:
postgres - Password:
postgres
- Database:
3. Testing with Telemetrygen
Send test telemetry to verify your setup:
# Install telemetrygen
go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
# Send test traces with API key
telemetrygen traces --otlp-endpoint localhost:4317 \
--otlp-insecure \
--otlp-header 'Authorization="Bearer YOUR_API_KEY"' \
--traces 10 --duration 5s
Replace YOUR_API_KEY with a valid API key from Monoscope's settings.
4. Configuration
Using Environment Variables
-
Copy
.env.exampleto.env:cp .env.example .env -
Edit
.envwith your specific configuration values -
Docker Compose will automatically use the
.envfile
Direct Database Connection (for local development)
If you want to run Monoscope locally but use the Docker TimescaleDB:
# Start only TimescaleDB
docker-compose up -d timescaledb
# Set your local DATABASE_URL
export DATABASE_URL="host=localhost user=postgres password=postgres dbname=apitoolkit port=5432 sslmode=disable"
# Run Monoscope locally
cabal run
Available Services
Core Services (always start)
- timescaledb: PostgreSQL 16 with TimescaleDB extension
- monoscope: The Monoscope application
Optional Services
pgAdmin (Database Management UI)
Start with the dev profile:
docker-compose --profile dev up -d
Access at: http://localhost:5050
- Email: admin@apitoolkit.io
- Password: admin
Test Database (Ephemeral)
Start with the test profile for integration testing:
docker-compose --profile test up -d
This starts a separate TimescaleDB instance on port 5433 with temporary storage.
Building Locally for Development
By default, Docker Compose uses the pre-built Monoscope image from GitHub Packages. To build locally:
Option 1: Using Override File (Recommended)
# Copy the override example
cp docker-compose.override.yml.example docker-compose.override.yml
# Docker Compose will automatically use both files
docker-compose up -d
Option 2: Using docker-compose build
# Force local build
docker-compose build monoscope
# Or build and run
docker-compose up -d --build monoscope
Option 3: Manual Override
# Build locally with a custom tag
docker build -t monoscope:local .
# Run with the local image
docker run -d \
--name monoscope-local \
--network monoscope-network \
-p 8080:8080 -p 4317:4317 \
-e DATABASE_URL="host=timescaledb user=postgres password=postgres dbname=apitoolkit port=5432 sslmode=disable" \
monoscope:local
Common Commands
View logs
# All services
docker-compose logs -f
# Specific service
docker-compose logs -f monoscope
docker-compose logs -f timescaledb
Update to latest Monoscope image
docker pull ghcr.io/monoscope-tech/monoscope:latest
docker-compose up -d monoscope
Stop all services
docker-compose down
Stop and remove all data
docker-compose down -v
Run integration tests with test database
# Start test database
docker-compose --profile test up -d timescaledb-test
# Run tests (adjust DATABASE_URL to use port 5433)
USE_EXTERNAL_DB=true DATABASE_URL="host=localhost user=postgres password=postgres dbname=apitoolkit_test_template port=5433 sslmode=disable" cabal test integration-tests
Troubleshooting
Port Conflicts
If you have PostgreSQL running locally on port 5432, you can change the port mapping in docker-compose.yml:
ports:
- '5433:5432' # Change host port to 5433
Then update your DATABASE_URL to use port 5433.
Build Issues
If the Monoscope build fails, check:
- Docker has enough memory allocated (at least 4GB)
- Build cache might be stale:
docker-compose build --no-cache monoscope
Database Connection Issues
If Monoscope can't connect to TimescaleDB:
- Ensure TimescaleDB is healthy:
docker-compose ps - Check logs:
docker-compose logs timescaledb - Verify network connectivity:
docker exec monoscope-app ping timescaledb
Migration Issues
If migrations fail:
- Check migration files exist:
ls ./static/migrations/ - Verify database is ready:
docker-compose exec timescaledb pg_isready - Check Monoscope logs:
docker-compose logs monoscope
Performance Tuning
For Development
The current configuration is optimized for development with:
- Full query logging enabled
- Max connections set to 200
- Shared memory optimized for TimescaleDB
For Production
Consider adjusting in docker-compose.yml:
- Remove query logging: Remove
-c log_statement='all' - Increase shared_buffers
- Adjust max_connections based on load
- Use Docker secrets for sensitive environment variables