@walkeros/docker

Runtime Docker container for walkerOS - executes pre-built flow bundles with instant startup and includes working demos for quick testing.

Installation

docker pull walkeros/docker:latest

Overview

This is a demo-enabled runtime container designed for both testing and production deployment. It executes pre-built .mjs bundles and includes ready-to-run demo flows for instant exploration.

Key Characteristics:

• ⚡ <1s startup - No npm downloads or build steps at runtime
• 📦 ~199MB image - Runtime dependencies + demo bundles for instant testing
• 🎯 Dual-purpose - Test with included demos OR deploy your own flows
• 🔒 Secure - No build tools or package managers in production
• ☁️ Cloud-optimized - Perfect for GCP Cloud Run, Kubernetes, ECS
• 🚀 Try instantly - Pre-built demos work out-of-the-box

Architecture

Build Phase (CLI)          Runtime Phase (Docker)
─────────────────         ────────────────────────
flow.json                 flow.mjs (pre-built)
    ↓                            ↓
CLI bundles              Docker imports & runs
    ↓                            ↓
flow.mjs  ──────────────→  Running collector

What's included: Express server, flow executor, graceful shutdown, demo bundles What's NOT included: CLI, bundler, npm, build tools

This is a minimal runtime image optimized for production deployments.

Quick Start

Step 1: Build Your Flow

Use @walkeros/cli to bundle your flow configuration:

# Install CLI
npm install -g @walkeros/cli

# Create and bundle your flow
walkeros bundle flow.json --output flow.mjs

Step 2: Run in Docker

docker run -p 8080:8080 \
  -v $(pwd)/flow.mjs:/app/flow.mjs \
  -e MODE=collect \
  -e FLOW=/app/flow.mjs \
  walkeros/docker:latest

Instant Demo

Want to try walkerOS Docker immediately? Use the included demo bundles - no CLI or bundling required:

Event Collector Demo

docker run -p 8080:8080 \
  -e MODE=collect \
  -e FLOW=/app/demos/demo-collect.mjs \
  walkeros/docker:latest

Test it:

curl -X POST http://localhost:8080/collect \
  -H "Content-Type: application/json" \
  -d '{"name":"page view","data":{"title":"Test"}}'

Web Bundle Demo

docker run -p 3000:8080 \
  -e MODE=serve \
  -e FLOW=/app/demos/demo-serve.mjs \
  walkeros/docker:latest

Open http://localhost:3000 in your browser to see automatic event tracking.

Full Demo Loop

Run both demos together to see the complete event flow from browser to collector:

Terminal 1 - Start Collector:

docker run -p 8080:8080 \
  -e MODE=collect \
  -e FLOW=/app/demos/demo-collect.mjs \
  --name walker-collector \
  walkeros/docker:latest

Terminal 2 - Start Web Bundle:

docker run -p 3000:8080 \
  -e MODE=serve \
  -e FLOW=/app/demos/demo-serve.mjs \
  --name walker-web \
  walkeros/docker:latest

Open http://localhost:3000 and watch events flow from browser → Terminal 1 collector logs.

Cleanup:

docker stop walker-collector walker-web && docker rm walker-collector walker-web

See demos/README.md for detailed demo documentation.

Usage Patterns

Local Development with Volume Mount

# Bundle your flow
walkeros bundle flow.json --output flow.mjs

# Run with volume mount
docker run -p 8080:8080 \
  -v $(pwd)/flow.mjs:/app/flow.mjs \
  -e MODE=collect \
  -e FLOW=/app/flow.mjs \
  walkeros/docker:latest

Production Deployment (Recommended)

Build a custom image with your bundled flow:

FROM walkeros/docker:latest
COPY flow.mjs /app/flow.mjs
ENV MODE=collect
ENV FLOW=/app/flow.mjs

docker build -t my-collector .
docker run -p 8080:8080 my-collector

GCP Cloud Run Deployment

# Build production bundle
walkeros bundle production.json --output flow.mjs

# Create Dockerfile
cat > Dockerfile <<EOF
FROM walkeros/docker:latest
COPY flow.mjs /app/flow.mjs
ENV MODE=collect
ENV FLOW=/app/flow.mjs
EOF

# Deploy
gcloud run deploy my-collector \
  --source . \
  --port 8080 \
  --allow-unauthenticated

Operational Modes

Two operational modes via MODE environment variable:

collect

Runs event collection server - executes the flow bundle which typically starts an HTTP server.

docker run -p 8080:8080 \
  -e MODE=collect \
  -e FLOW=/app/flow.mjs \
  -v $(pwd)/flow.mjs:/app/flow.mjs \
  walkeros/docker:latest

serve

Serves static files (useful for web bundles):

docker run -p 8080:8080 \
  -e MODE=serve \
  -e STATIC_DIR=/app/dist \
  -v $(pwd)/dist:/app/dist \
  walkeros/docker:latest

Environment Variables

Required

• MODE - Operational mode: collect or serve
• FLOW - Path to pre-built flow bundle (.mjs file) - required for collect mode

Optional

• PORT - Server port (default: from flow or 8080)
• HOST - Server host (default: 0.0.0.0)
• STATIC_DIR - Static files directory for serve mode (default: /app/dist)

Example:

docker run -p 3000:3000 \
  -e MODE=collect \
  -e FLOW=/app/flow.mjs \
  -e PORT=3000 \
  -e HOST=0.0.0.0 \
  -v $(pwd)/flow.mjs:/app/flow.mjs \
  walkeros/docker:latest

Docker Compose

version: '3.8'

services:
  collector:
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      MODE: collect
      FLOW: /app/flow.mjs
      PORT: 8080
    ports:
      - '8080:8080'
    restart: unless-stopped
    healthcheck:
      test:
        [
          'CMD',
          'node',
          '-e',
          "require('http').get('http://localhost:8080/health', (r) =>
          process.exit(r.statusCode === 200 ? 0 : 1))",
        ]
      interval: 30s
      timeout: 10s
      retries: 3

Dockerfile:

FROM walkeros/docker:latest
COPY flow.mjs /app/flow.mjs
ENV MODE=collect
ENV FLOW=/app/flow.mjs

Development

Build Package

npm run build

Run Locally (without Docker)

The Docker package exports functions that can be used directly in Node.js:

import { runFlow, runServeMode } from '@walkeros/docker';

// Run a pre-built flow
await runFlow('/path/to/flow.mjs', {
  port: 8080,
  host: '0.0.0.0',
});

// Or run serve mode
await runServeMode({
  port: 8080,
  staticDir: '/path/to/dist',
});

Build Docker Image

# From monorepo root
docker build -t walkeros/docker:latest -f packages/docker/Dockerfile .

# Test with a bundled flow
walkeros bundle flow.json --output flow.mjs
docker run -p 8080:8080 \
  -v $(pwd)/flow.mjs:/app/flow.mjs \
  -e MODE=collect \
  -e FLOW=/app/flow.mjs \
  walkeros/docker:latest

Testing

npm test

Library Usage

The Docker package can be imported as a library (used by @walkeros/cli):

import {
  runFlow,
  runServeMode,
  type RuntimeConfig,
  type ServeConfig,
} from '@walkeros/docker';

// Execute a pre-built flow
await runFlow('/path/to/flow.mjs', {
  port: 8080,
  host: '0.0.0.0',
});

// Or run in serve mode
await runServeMode({
  port: 3000,
  staticDir: './dist',
});

This is how @walkeros/cli uses the Docker package - no Docker daemon required!

Troubleshooting

"FLOW environment variable required"

Ensure you're providing the FLOW env var pointing to a pre-built .mjs file:

docker run \
  -e MODE=collect \
  -e FLOW=/app/flow.mjs \
  -v $(pwd)/flow.mjs:/app/flow.mjs \
  walkeros/docker:latest

"Cannot find module"

The FLOW path must point to a pre-built .mjs bundle, not a .json config:

# ❌ Wrong - JSON config
-e FLOW=/app/flow.json

# ✅ Correct - Pre-built bundle
-e FLOW=/app/flow.mjs

Port already in use

• Check what's using the port: lsof -i :8080
• Use a different port: -p 3000:8080
• Port in flow configuration vs Docker mapping must match

Docker Hub

Official image: walkeros/docker

# Pull latest
docker pull walkeros/docker:latest

# Pull specific version
docker pull walkeros/docker:0.1.0

What's Different from CLI?

| Feature | @walkeros/docker | @walkeros/cli | | ------------------- | -------------------- | --------------------------- | | Purpose | Runtime execution | Build + orchestration | | Bundling | ❌ No | ✅ Yes | | Dependencies | Runtime + demos | 10 (includes Docker) | | Image Size | ~199MB | N/A | | Startup | <1s | N/A | | Docker Required | For containerization | No (uses Docker as library) | | Use Case | Testing + Production | Development + build |

Version & Status

Current Version: 0.1.0 Recommended Next Version: 0.2.0 (breaking changes)

Production Ready ✅

• ✅ Demo-enabled runtime architecture - zero build dependencies
• ✅ Included demo bundles for instant testing
• ✅ Library exports for CLI integration
• ✅ Collect and serve modes
• ✅ <1s startup time
• ✅ ~199MB Docker image
• ✅ Graceful shutdown handling
• ✅ GCP Cloud Run optimized

Breaking Changes from Previous Versions

• ❌ No longer accepts JSON configs at runtime
• ❌ Must receive pre-built .mjs bundles via FLOW env var
• ❌ Removed all bundling, build, and package download capabilities
• ✅ Use @walkeros/cli to bundle flows first

License

MIT

Support

• GitHub Issues: https://github.com/elbwalker/walkerOS/issues
• Documentation: https://github.com/elbwalker/walkerOS