Docker Setup

Flowstate uses Docker Compose for local development, providing a consistent environment across all team members. All services run in containers, managed via just commands that wrap Docker Compose with secrets injection.

Prerequisites

Before starting, ensure you have:

1. Docker Desktop (or Docker Engine + Docker Compose)

   • macOS: Docker Desktop for Mac
   • Windows: Docker Desktop for Windows
   • Linux: Docker Engine + Docker Compose

2. Secrets management tooling — required to inject development secrets at runtime. Contact your administrator for setup instructions.

3. Just (command runner)

   • Install: brew install just (macOS) or other methods

4. Node.js 22 and pnpm 10 (for local tooling)

   • Install: brew install node@22 pnpm (macOS)

Quick Start

# Clone the repository
git clone https://github.com/your-org/flowstate-canvas.git
cd flowstate-canvas

# One-command setup (checks prereqs, installs deps, starts services)
just setup

# Or manually:
pnpm install
just up
just db-push

# View logs
just logs

# Stop all services
just down

After running just up, the services will be available at the URLs configured for your environment. See your administrator for the local service addresses.

Services

Docker Compose runs the following services:

Service	Description	Image
backend	Express.js REST API + RPC Gateway	Node.js 22
web	Astro frontend (main app)	Node.js 22
admin	Astro admin dashboard	Node.js 22
mongodb	MongoDB 7 replica set	mongo:7
mongodb-init	MongoDB replica set initializer	mongo:7
redis	Redis 7 cache and pub/sub	redis:7-alpine
minio	S3-compatible object storage	minio/minio

Service Dependencies

web ──────┐
admin ────┼──> backend ──┬──> mongodb
          │              └──> redis
          │
          └──> minio (for uploads)

All services start automatically in the correct order based on depends_on configuration.

Just Commands

The justfile provides convenient commands for managing the Docker environment. Always use just commands instead of running docker compose directly to ensure secrets are injected properly.

Starting and Stopping

Command	Description
just setup	First-time setup (prereqs + install + start + schema)
just up	Start all services (detached mode)
just down	Stop all services
just restart	Restart all services
just stop	Stop services without removing containers
just teardown	Complete teardown (Docker + host deps + caches + artifacts)

Logs

Command	Description
just logs	View logs from all services (follow mode)
just logs-backend	View backend logs only
just logs-web	View web logs only
just logs-admin	View admin logs only
just logs-db	View MongoDB logs

Example:

# View all logs
just logs

# View backend logs only
just logs-backend

Building

Command	Description
just rebuild	Rebuild all images without cache
just build	Build images (uses cache)

When to rebuild:

• After changing Dockerfile or docker-compose.yml
• After updating dependencies in package.json
• When experiencing unexplained errors (cache issues)

Shell Access

Command	Description
just shell-backend	Open shell in backend container
just shell-web	Open shell in web container
just shell-admin	Open shell in admin container
just shell-db	Open MongoDB shell (mongosh)
just redis-cli	Open Redis CLI

Example:

# Shell into backend container
just shell-backend

# Inside container, run commands
pnpm tsc --noEmit
pnpm build
exit

Database Commands

Command	Description
just db-generate	Generate Prisma client
just db-push	Push Prisma schema to MongoDB
just db-seed	Seed demo data
just db-studio	Open Prisma Studio
just db-reset	Reset database (drops all data!)

Example workflow:

# After modifying prisma/schema.prisma
just db-generate  # Regenerate Prisma client
just db-push      # Apply schema changes to MongoDB
just db-seed      # Seed demo data (optional)

Type Checking

Command	Description
just typecheck	Run TypeScript checks on all apps
just typecheck-backend	Check backend only
just typecheck-web	Check web only

Desktop App

Command	Description
just desktop	Start Electron desktop app (dev mode)
just desktop-restart	Restart desktop app
just desktop-stop	Stop desktop app

The desktop app runs locally (not in Docker) because it needs GPU and display access.

MongoDB Replica Set

Prisma requires MongoDB to run as a replica set (even for single-node development). The mongodb-init service automatically initializes the replica set on first startup.

Initialization process:

1. mongodb service starts
2. mongodb-init waits for MongoDB to be ready
3. mongodb-init runs rs.initiate() to create replica set
4. mongodb-init exits (one-time setup)
5. Backend connects to replica set

Troubleshooting:

If you see “not master and slaveOk=false” errors:

# Restart MongoDB and re-initialize
just down
docker volume rm flowstatecanvas_mongodb_data
just up

Environment Variables

Environment variables are injected via your secrets management solution and never written to disk.

The project uses a template file that maps environment variable names to secret references. When you run just up, the secrets tool resolves those references and injects real values as environment variables. Docker Compose picks them up via ${VAR} substitution.

Never run docker compose directly — it won’t have access to secrets.

Health Checks

All services include health checks to ensure they’re ready before dependent services start:

healthcheck:
  test: ['CMD', 'curl', '-f', 'http://localhost:<port>/health']
  interval: 10s
  timeout: 5s
  retries: 5
  start_period: 30s

Check service health:

docker compose ps

Output shows health status:

NAME                    STATUS
backend                 Up (healthy)
web                     Up (healthy)
mongodb                 Up (healthy)
redis                   Up (healthy)

Hot Reload

All services support hot reload for rapid development:

Service	Hot Reload Method
Backend	tsx watch (restarts on file changes)
Web	Astro dev server (HMR)
Admin	Astro dev server (HMR)

Changes to source files are immediately reflected in running containers without a rebuild.

Networking

Docker Compose creates a bridge network where services communicate using service names as hostnames:

backend -> mongodb:27017
backend -> redis:6379
web -> backend:3000 (via SERVER_API_URL)

Important: Use service names (not localhost) in container-to-container communication.

Data Persistence

Data is persisted in Docker volumes:

Volume	Purpose
mongodb_data	MongoDB database files
redis_data	Redis persistence (AOF)
minio_data	MinIO object storage

Volumes survive container restarts but are deleted when running docker compose down -v.

Backup data:

# Backup MongoDB
docker compose exec mongodb mongodump --out /dump
docker compose cp mongodb:/dump ./backup

# Backup MinIO
docker compose exec minio mc mirror /data ./backup/minio

Troubleshooting

Services won’t start

# Check logs for errors
just logs

# Rebuild without cache
just rebuild

# Reset everything
just down
docker volume prune
just up

Port conflicts

If ports are already in use, identify the conflicting process and stop it, or update the port mapping in docker-compose.yml.

MongoDB connection errors

# Check MongoDB is running
docker compose ps mongodb

# Check replica set status
just shell-db
rs.status()
exit

# Re-initialize replica set
just down
docker volume rm flowstatecanvas_mongodb_data
just up

Secrets / environment errors

Verify your secrets management tooling is correctly configured. Contact your administrator if you do not have access to the development vault.

Out of disk space

# Remove unused images and volumes
docker system prune -a --volumes

# Check disk usage
docker system df

Slow performance

Increase Docker Desktop resources: Docker Desktop → Settings → Resources. Recommended: 4 CPUs, 8GB RAM.

Best Practices

1. Always use just commands — Never run docker compose directly
2. Check logs first — Most issues are visible in logs
3. Rebuild after dependency changes — Run just rebuild after updating package.json
4. Use health checks — Wait for services to be healthy before testing
5. Clean up regularly — Run docker system prune weekly to free disk space
6. Monitor resource usage — Check Docker Desktop dashboard for CPU/memory usage
7. Backup data before resets — just db-reset is destructive
8. Test in containers — Don’t rely on local Node.js for testing
9. Keep Docker Desktop updated — Latest version has performance improvements

Production Differences

Development and production Docker setups differ:

Aspect	Development	Production
Images	Built locally	Pre-built on container registry
Secrets	Secrets management tooling	Environment variables / vault
Volumes	Source code mounted	No mounts (baked into image)
Hot reload	Enabled	Disabled
Ports	All exposed	Only public ports exposed
Networking	Bridge network	Overlay network (Swarm/K8s)
Logging	stdout	Centralized logging (Loki, etc.)
Health checks	Basic	Comprehensive with alerts

See Production Deployment for production setup details.