walkerOS Docker
The walkerOS Docker package (@walkeros/docker) is a pure runtime container for executing pre-built flow bundles in production. It's designed for fast startup (< 1 second), minimal footprint (~150-200MB), and cloud-native deployment.
Key Philosophy: Docker handles runtime, CLI handles build-time. You bundle with the CLI, deploy with Docker.
What It Does
- ✅ Executes pre-built
.mjsbundles from the CLI - ✅ Runs collection servers (HTTP endpoints for event ingestion)
- ✅ Serves static files (web tracking scripts)
- ✅ Sub-1 second startup - No npm downloads, no build steps
- ✅ Production-ready - Health checks, non-root user, signal handling
What It Doesn't Do
- ❌ No bundling - Flows must be pre-built with the CLI
- ❌ No package downloads - All dependencies must be bundled
- ❌ No configuration generation - Configuration comes from your bundle
Think of it as the deployment target, not the build tool.
Prerequisites
- Docker installed (Get Docker)
- (Optional) Pre-built flow bundle from the CLI
Quick Start with Demos
The Docker image includes demo bundles for instant testing.
Demo: Event Collection
Output:
✓ Loading flow: /app/demos/demo-collect.mjs
✓ Starting collection server on port 8080
✓ Health check available at /health
[Demo Output] page view
[Demo Output] product add
The demo is self-contained and generates test events automatically.
Demo: Static File Serving
Visit http://localhost:3000/demo-serve.js to download the demo web bundle.
Configuration
The Docker container is configured via environment variables:
Collect Mode
| Environment Variable | Required | Default | Description |
|---|---|---|---|
MODE | Yes | - | Must be collect |
FLOW | Yes | - | Path to pre-built .mjs bundle |
PORT | No | 8080 | Server port |
HOST | No | 0.0.0.0 | Bind address |
Serve Mode
| Environment Variable | Required | Default | Description |
|---|---|---|---|
MODE | Yes | - | Must be serve |
STATIC_DIR | No | /app/dist | Directory to serve |
PORT | No | 3000 | Server port |
HOST | No | 0.0.0.0 | Bind address |
Deployment Workflows
Workflow 1: Volume Mount (Development)
Mount pre-built bundles directly into the container.
1. Build with CLI
This creates dist/flow.mjs.
2. Run with Docker
3. Test it
4. View logs
Workflow 2: Custom Docker Image (Production)
Build a custom Docker image with your bundle baked in.
1. Build with CLI
2. Create Dockerfile
3. Build image
4. Run it
5. Push to registry
Workflow 3: Multi-Stage Build
Build and bundle in a single Dockerfile.
Build and run:
Docker Compose
Single Service
Run it:
Multiple Services (Web + Server)
Cloud Deployment
Google Cloud Run
Cloud Run is ideal for serverless deployment of walkerOS flows.
Deploy Collection Endpoint
1. Create server flow
Create bigquery-collect.json:
The config above includes both BigQuery and console destinations. This is a best practice:
- Console logs help debug issues in Cloud Run logs
- Start with console only, verify events flow correctly
- Then uncomment BigQuery destination for production
To start console-only: remove the bigquery destination block.
2. Bundle the flow
3. Create Dockerfile
4. Build and push to Google Container Registry
5. Deploy to Cloud Run
6. Get the URL
7. Test it
8. View logs
You should see console logs showing the received events.
Deploy Web Bundle Server
1. Create web flow
Create web-tracker.json:
2. Bundle
This creates tracker.js.
3. Create Dockerfile for serving
4. Deploy to Cloud Run
5. Use in your website
For production, consider:
- Use a CDN: Serve static files from Cloud Storage + Cloud CDN instead of Cloud Run
- Custom domain: Map your own domain (e.g.,
cdn.example.com/tracker.js) - Versioning: Include version in filename (e.g.,
tracker.v1.2.3.js) - Caching: Set appropriate cache headers
AWS (ECS/Fargate)
Similar workflow for AWS:
Kubernetes
Deploy to any Kubernetes cluster:
Apply:
Health Checks
The Docker container provides a /health endpoint:
Response:
Use this for:
- Docker health checks
- Kubernetes liveness/readiness probes
- Load balancer health checks
- Monitoring systems
Monitoring and Logs
View Docker Logs
Cloud Run Logs
Structured Logging
For better observability, use structured logging in your destinations:
Security
The Docker image follows security best practices:
- ✅ Non-root user - Runs as
walker(UID 1001) - ✅ Minimal base - Alpine Linux (~150-200MB)
- ✅ No build tools - Production dependencies only
- ✅ Signal handling - Graceful shutdown with Tini
- ✅ Health checks - Built-in endpoint for orchestrators
Environment Secrets
For sensitive configuration (API keys, credentials), use environment variables:
Reference secrets in your flow configuration using environment variable substitution.
Performance
Startup Time
- Cold start: < 1 second (flow already bundled)
- Warm start: < 100ms (container reuse)
Resource Usage
Typical resource consumption:
| Metric | Idle | Active (1000 req/min) |
|---|---|---|
| Memory | ~50MB | ~100-150MB |
| CPU | < 1% | 5-15% |
| Startup | < 1s | < 1s |
Scaling
The container is designed for horizontal scaling:
Troubleshooting
Container Won't Start
Events Not Being Received
Port Conflicts
Bundle Not Found
Next Steps
- CLI - Learn how to build flows
- Flow Configuration - Understand flow structure
- Sources - Configure event sources
- Destinations - Set up analytics destinations
- Docker Hub - Official Docker images