Docker

Learn how to run moclojer with Docker. Official images, Docker Compose, volumes, networks and production-ready deployment.

moclojer offers official Docker images to simplify deployment and development. This guide shows how to use Docker and Docker Compose to run your mock server.

Why Use Docker?

✅ Isolation: Consistent environment on any machine ✅ Portability: Works in dev, staging and production ✅ Easy deployment: Pull, run, done! ✅ Versioning: Lock specific versions ✅ CI/CD: Easy integration with pipelines

Official Image

Repository

ghcr.io/moclojer/moclojer:latest

Available tags:

latest - Latest stable version
v0.4.0 - Specific version
main - Build from main branch (bleeding edge)

Check Version

docker run --rm ghcr.io/moclojer/moclojer:latest --version

Quick Start

1. Create Configuration File

Create moclojer.yml:

- endpoint:
    method: GET
    path: /hello
    response:
      status: 200
      body: >
        {
          "message": "Hello from Docker!",
          "timestamp": "2024-01-15T10:00:00Z"
        }

- endpoint:
    method: GET
    path: /users
    response:
      status: 200
      body: >
        [
          {"id": 1, "name": "Alice"},
          {"id": 2, "name": "Bob"}
        ]

2. Run with Docker

docker run -it \
  -p 8000:8000 \
  -v $(pwd)/moclojer.yml:/app/moclojer.yml \
  ghcr.io/moclojer/moclojer:latest \
  --config /app/moclojer.yml

3. Test

curl http://localhost:8000/hello
curl http://localhost:8000/users

🎉 It works!

Bind Mount vs Volume

Bind Mount (Development)

Advantages: Edit local file, changes reflect immediately

docker run -it \
  -p 8000:8000 \
  -v $(pwd)/moclojer.yml:/app/moclojer.yml \
  ghcr.io/moclojer/moclojer:latest \
  --config /app/moclojer.yml --watch

With --watch: Automatically reloads when file changes!

Named Volume (Production)

# Create volume
docker volume create moclojer-config

# Copy config to volume
docker run --rm \
  -v moclojer-config:/config \
  -v $(pwd)/moclojer.yml:/source/moclojer.yml \
  busybox cp /source/moclojer.yml /config/

# Run moclojer
docker run -d \
  --name moclojer \
  -p 8000:8000 \
  -v moclojer-config:/config \
  ghcr.io/moclojer/moclojer:latest \
  --config /config/moclojer.yml

Docker Compose

Basic Setup

Create docker-compose.yml:

version: '3.8'

services:
  moclojer:
    image: ghcr.io/moclojer/moclojer:latest
    container_name: moclojer
    ports:
      - "8000:8000"
    volumes:
      - ./moclojer.yml:/app/moclojer.yml:ro
    command: --config /app/moclojer.yml
    restart: unless-stopped

Run:

docker-compose up

Run in background:

docker-compose up -d

View logs:

docker-compose logs -f moclojer

Stop:

docker-compose down

With Hot-Reload (Dev)

version: '3.8'

services:
  moclojer-dev:
    image: ghcr.io/moclojer/moclojer:latest
    ports:
      - "8000:8000"
    volumes:
      - ./moclojer.yml:/app/moclojer.yml
    command: --config /app/moclojer.yml --watch
    environment:
      - MOCLOJER_ENABLE_CORS=true

With Environment Variables

version: '3.8'

services:
  moclojer:
    image: ghcr.io/moclojer/moclojer:latest
    ports:
      - "${MOCLOJER_PORT:-8000}:8000"
    volumes:
      - ./mocks/${ENV:-dev}.yml:/app/moclojer.yml:ro
    command: --config /app/moclojer.yml
    environment:
      - MOCLOJER_ENABLE_CORS=${ENABLE_CORS:-true}
      - MOCLOJER_HOST=0.0.0.0

Create .env:

MOCLOJER_PORT=3000
ENV=staging
ENABLE_CORS=true

Run:

docker-compose up

With Health Check

version: '3.8'

services:
  moclojer:
    image: ghcr.io/moclojer/moclojer:latest
    ports:
      - "8000:8000"
    volumes:
      - ./moclojer.yml:/app/moclojer.yml:ro
    command: --config /app/moclojer.yml
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Check status:

docker-compose ps

External Bodies with Global Configuration

When using external body files in Docker, you can leverage the global folder configuration to simplify your setup. This is especially useful when mounting volumes with response data.

Setup

1. Create directory structure:

my-mock-project/
├── docker-compose.yml
├── moclojer.yml
└── data/
    ├── users.json
    ├── products.json
    └── orders.json

2. Configure moclojer.yml with global folder:

# Global configuration for external bodies
- external-body:
    folder: /app/data

# Endpoints use simple filenames
- endpoint:
    method: GET
    path: /api/users
    response:
      status: 200
      external-body:
        provider: json
        path: users.json  # Resolves to /app/data/users.json

- endpoint:
    method: GET
    path: /api/products
    response:
      status: 200
      external-body:
        provider: json
        path: products.json  # Resolves to /app/data/products.json

3. docker-compose.yml:

services:
  moclojer:
    image: ghcr.io/moclojer/moclojer:latest
    ports:
      - "8000:8000"
    volumes:
      - ./moclojer.yml:/app/moclojer.yml:ro
      - ./data:/app/data:ro  # Mount data directory
    environment:
      - PORT=8000
      - HOST=0.0.0.0

4. Run:

docker-compose up

Benefits

✅ Clean configuration: No repeated paths ✅ Easy updates: Update JSON files without changing config ✅ Volume management: Single mount point for all data ✅ Team collaboration: Clear separation between config and data

Testing

# Get users
curl http://localhost:8000/api/users

# Get products
curl http://localhost:8000/api/products

See Example

Full working example available at: examples/external-body-global/

Multiple Environments

File Structure

project/
├── docker-compose.yml
├── mocks/
│   ├── dev.yml         # Development environment
│   ├── staging.yml     # Staging environment
│   └── prod.yml        # Production environment
└── .env

docker-compose.yml

version: '3.8'

services:
  moclojer:
    image: ghcr.io/moclojer/moclojer:${MOCLOJER_VERSION:-latest}
    ports:
      - "${PORT:-8000}:8000"
    volumes:
      - ./mocks/${ENV}.yml:/app/moclojer.yml:ro
    command: --config /app/moclojer.yml
    restart: unless-stopped

.env files

.env.dev:

ENV=dev
PORT=8000
MOCLOJER_VERSION=latest

.env.staging:

ENV=staging
PORT=8001
MOCLOJER_VERSION=v0.4.0

.env.prod:

ENV=prod
PORT=8080
MOCLOJER_VERSION=v0.4.0

Run:

# Development
docker-compose --env-file .env.dev up

# Staging
docker-compose --env-file .env.staging up

# Production
docker-compose --env-file .env.prod up -d

Networking

With Other Services

version: '3.8'

services:
  # Your application
  app:
    image: myapp:latest
    ports:
      - "3000:3000"
    environment:
      - API_URL=http://moclojer:8000
    depends_on:
      - moclojer

  # Mock server
  moclojer:
    image: ghcr.io/moclojer/moclojer:latest
    volumes:
      - ./mocks/api.yml:/app/moclojer.yml:ro
    command: --config /app/moclojer.yml
    # Doesn't expose external port (only internal network)
    expose:
      - "8000"

Application accesses: http://moclojer:8000/api/users

Custom Network

version: '3.8'

networks:
  backend:
    driver: bridge

services:
  moclojer:
    image: ghcr.io/moclojer/moclojer:latest
    ports:
      - "8000:8000"
    volumes:
      - ./moclojer.yml:/app/moclojer.yml:ro
    command: --config /app/moclojer.yml
    networks:
      - backend

  app:
    image: myapp:latest
    networks:
      - backend
    environment:
      - MOCK_API=http://moclojer:8000

CI/CD Integration

GitHub Actions

# .github/workflows/test.yml
name: E2E Tests with moclojer

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      moclojer:
        image: ghcr.io/moclojer/moclojer:latest
        ports:
          - 8000:8000
        volumes:
          - ${{ github.workspace }}/mocks/api.yml:/app/moclojer.yml:ro
        options: >-
          --health-cmd "curl -f http://localhost:8000/health || exit 1"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - uses: actions/checkout@v3

      - name: Wait for moclojer
        run: |
          timeout 30 bash -c 'until curl -f http://localhost:8000/health; do sleep 1; done'

      - name: Run E2E tests
        run: |
          npm test
        env:
          API_URL: http://localhost:8000

GitLab CI

# .gitlab-ci.yml
test:
  image: node:18
  services:
    - name: ghcr.io/moclojer/moclojer:latest
      alias: moclojer
      command: ["--config", "/app/moclojer.yml"]
      volumes:
        - ./mocks/api.yml:/app/moclojer.yml:ro

  variables:
    API_URL: http://moclojer:8000

  script:
    - npm install
    - npm test

Docker Compose in CI

# CI script
docker-compose -f docker-compose.ci.yml up -d
docker-compose -f docker-compose.ci.yml run --rm tests
docker-compose -f docker-compose.ci.yml down

docker-compose.ci.yml:

version: '3.8'

services:
  moclojer:
    image: ghcr.io/moclojer/moclojer:latest
    volumes:
      - ./mocks/api.yml:/app/moclojer.yml:ro
    command: --config /app/moclojer.yml

  tests:
    image: node:18
    depends_on:
      - moclojer
    environment:
      - API_URL=http://moclojer:8000
    volumes:
      - .:/app
    working_dir: /app
    command: npm test

Production

docker-compose.prod.yml

version: '3.8'

services:
  moclojer:
    image: ghcr.io/moclojer/moclojer:v0.4.0  # Fixed version!
    container_name: moclojer-prod
    restart: always
    ports:
      - "8080:8000"
    volumes:
      - ./mocks/prod.yml:/app/moclojer.yml:ro
      - moclojer-logs:/var/log/moclojer
    command: --config /app/moclojer.yml --host 0.0.0.0
    environment:
      - MOCLOJER_ENABLE_CORS=false  # Disable in prod
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

volumes:
  moclojer-logs:

Deploy:

docker-compose -f docker-compose.prod.yml up -d

With Nginx Reverse Proxy

version: '3.8'

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - moclojer

  moclojer:
    image: ghcr.io/moclojer/moclojer:latest
    expose:
      - "8000"
    volumes:
      - ./mocks/api.yml:/app/moclojer.yml:ro
    command: --config /app/moclojer.yml

nginx.conf:

upstream moclojer {
    server moclojer:8000;
}

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://moclojer;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Troubleshooting

Container won't start

Problem: docker: Error response from daemon: Conflict

Solution: Remove old container

docker rm -f moclojer
docker-compose down

Config file not found

Problem: Config file not found

Solution: Check mount

# List files inside container
docker run --rm \
  -v $(pwd)/moclojer.yml:/app/moclojer.yml \
  ghcr.io/moclojer/moclojer:latest \
  ls -la /app/

# Should show moclojer.yml

Port already in use

Problem: Bind for 0.0.0.0:8000 failed: port is already allocated

Solution: Change host port

docker run -p 8001:8000 ...
# Or
docker-compose -f docker-compose.yml up  # with ports: "8001:8000"

Hot-reload not working

Problem: File changes don't reload

Causes:

Didn't pass --watch
Using native image (GraalVM) - doesn't support watch

Solution:

# Check if it's native
docker run --rm ghcr.io/moclojer/moclojer:latest --version

# If native, use JAR version (if available)
# Or restart container manually
docker-compose restart moclojer

Volume permissions

Problem: Permission denied

Solution: Adjust permissions

chmod 644 moclojer.yml

Best Practices

✅ Do

Use fixed versions in production

image: ghcr.io/moclojer/moclojer:v0.4.0  # ✅
# image: ghcr.io/moclojer/moclojer:latest  # ❌ In prod

Read-only volumes when possible

volumes:
  - ./moclojer.yml:/app/moclojer.yml:ro  # Read-only

Health checks

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/health"]

Resource limits

deploy:
  resources:
    limits:
      cpus: '1'
      memory: 512M

Configure logging

logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

❌ Avoid

:latest in production
Running as root (if possible, use USER in Dockerfile)
Exposing unnecessary ports
Volumes without :ro when write is not needed

Complete Examples

E2E Testing Setup

# docker-compose.test.yml
version: '3.8'

services:
  # External API mock
  mock-api:
    image: ghcr.io/moclojer/moclojer:latest
    volumes:
      - ./mocks/external-api.yml:/app/moclojer.yml:ro
    expose:
      - "8000"

  # Your application
  app:
    build: .
    environment:
      - EXTERNAL_API_URL=http://mock-api:8000
    depends_on:
      - mock-api

  # Tests
  tests:
    image: cypress/included:latest
    depends_on:
      - app
    environment:
      - CYPRESS_baseUrl=http://app:3000
    volumes:
      - ./cypress:/cypress
    command: cypress run

Run tests:

docker-compose -f docker-compose.test.yml run --rm tests

Next Steps

Kubernetes Deployment - Deploy to K8s
Cloud Run - Deploy to Google Cloud
CI/CD Integration - Continuous integration

hashtagWhy Use Docker?

hashtagOfficial Image

hashtagRepository

hashtagCheck Version

hashtagQuick Start

hashtag1. Create Configuration File

hashtag2. Run with Docker

hashtag3. Test

hashtagBind Mount vs Volume

hashtagBind Mount (Development)

hashtagNamed Volume (Production)

hashtagDocker Compose

hashtagBasic Setup

hashtagWith Hot-Reload (Dev)

hashtagWith Environment Variables

hashtagWith Health Check

hashtagExternal Bodies with Global Configuration

hashtagSetup

hashtagBenefits

hashtagTesting

hashtagSee Example

hashtagMultiple Environments

hashtagFile Structure

hashtagdocker-compose.yml

hashtag.env files

hashtagNetworking

hashtagWith Other Services

hashtagCustom Network

hashtagCI/CD Integration

hashtagGitHub Actions

hashtagGitLab CI

hashtagDocker Compose in CI

hashtagProduction

hashtagdocker-compose.prod.yml

hashtagWith Nginx Reverse Proxy

hashtagTroubleshooting

hashtagContainer won't start

hashtagConfig file not found

hashtagPort already in use

hashtagHot-reload not working

hashtagVolume permissions

hashtagBest Practices

hashtag✅ Do

hashtag❌ Avoid

hashtagComplete Examples

hashtagE2E Testing Setup

hashtagNext Steps

hashtagSee Also

Why Use Docker?

Official Image

Repository

Check Version

Quick Start

1. Create Configuration File

2. Run with Docker

3. Test

Bind Mount vs Volume

Bind Mount (Development)

Named Volume (Production)

Docker Compose

Basic Setup

With Hot-Reload (Dev)

With Environment Variables

With Health Check

External Bodies with Global Configuration

Setup

Benefits

Testing

See Example

Multiple Environments

File Structure

docker-compose.yml

.env files

Networking

With Other Services

Custom Network

CI/CD Integration

GitHub Actions

GitLab CI

Docker Compose in CI

Production

docker-compose.prod.yml

With Nginx Reverse Proxy

Troubleshooting

Container won't start

Config file not found

Port already in use

Hot-reload not working

Volume permissions

Best Practices

✅ Do

❌ Avoid

Complete Examples

E2E Testing Setup

Next Steps

See Also