Instruction file imported from videohead/langgraph-copilottoolkit (.github/instructions/docker-lando.instructions.md). Copyright stays with the author.

Modifying Docker / Lando Service Definitions

Service map

Required sync updates when adding a service

When adding or renaming any service in docker-compose.yml or .lando.yml, also update all of the following in the same change:

1. Runtime stack config:

• docker-compose.yml service definition, healthcheck/dependencies, volumes, and env wiring.
• .lando.yml service definition, proxy URL, and tooling commands.

2. User-facing docs:

• readme.md architecture diagram and the "Additional services" table.

3. User-facing services map API:

• frontend/app/api/services/data.mjs in all three places:
  • DEFAULT_ENDPOINTS
  • PUBLIC_LOCATIONS
  • services array in buildServicesDashboardData()

Minimum expected entries include both durable and coordination stores (postgres and redis) so they appear in docs and in the services dashboard. MCP services should also stay represented in docs and dashboard (mcp-filesystem, mcp-shell).

MCP shell allowlist management

mcp-shell enforces command execution policy via environment variables:

• MCP_SHELL_ALLOWLIST — comma-separated executable names.
• MCP_SHELL_ROOT — command working-directory sandbox root.
• MCP_SHELL_TIMEOUT_SECONDS — command timeout.
• MCP_SHELL_MAX_OUTPUT_BYTES — stdout/stderr truncation bound.

When editing allowlist values, update both docker-compose.yml and .lando.yml in the same change. The allowlist is loaded at process startup, so changes are not hot-reloaded. Restart/recreate mcp-shell after updates.

Build context rules

Django — build context MUST be repo root

django/Dockerfile COPYs from both django/ and src/:

COPY django/requirements.txt ./requirements.txt
COPY src/ ./src/
COPY django/ .

In docker-compose.yml:

django:
  build:
    context: .              # repo root
    dockerfile: django/Dockerfile

In .lando.yml:

django:
  services:
    build:
      context: .            # repo root
      dockerfile: django/Dockerfile

Never set context: ./django — the Dockerfile will fail to find src/.

Frontend — build context is ./frontend

frontend/Dockerfile only needs files inside frontend/:

frontend:
  build:
    context: ./frontend
    dockerfile: Dockerfile

Volume mount patterns

Hot-reload: override image files with host source

volumes:
  - ./django:/app           # Django source
  - ./src:/app/src:ro       # shared graphs (read-only)

volumes:
  - ./frontend:/app         # Next.js source
  - /app/node_modules       # anonymous volume — preserves image's node_modules

The anonymous /app/node_modules volume is essential for the frontend. Without it, the host mount would shadow the container's installed packages with an empty host directory.

src/ is always :ro inside Django

Never mount src/ read-write into the Django container. The graphs are Python library code; Django should not write to them.

Environment variables

Internal service URLs use Docker/Lando DNS — not localhost:

# Correct (Compose)
OLLAMA_BASE_URL: http://ollama:11434
DJANGO_INTERNAL_URL: http://django:8080

# Correct (Lando — service names resolve as <name>.<appname>.internal)
OLLAMA_BASE_URL: http://ollama.langgraph.internal:11434
DJANGO_INTERNAL_URL: http://django.langgraph.internal:8080

OLLAMA_MODEL and OLLAMA_BASE_URL must be set on both langgraph/appserver and django — both services run graphs against Ollama.

Lando service format (API 3)

All services use api: 3 with type: lando. The services: block is a standard Docker Compose service definition:

myservice:
  api: 3
  type: lando
  app_mount: false          # disable Lando's default app volume mount
  services:
    build:
      context: .
      dockerfile: myservice/Dockerfile
    command: my-start-command
    environment:
      MY_VAR: value
    ports:
      - "8090"              # expose to Lando's internal network (no host binding needed)
    volumes:
      - ./myservice:/app
  moreHttpPorts:
    - 8090                  # tell Lando to proxy this port

Add a proxy entry to expose it via .lndo.site:

proxy:
  myservice:
    - myservice.langgraph.lndo.site:8090

Add tooling to run commands in the container:

tooling:
  myservice-cmd:
    service: myservice
    cmd: my-binary
    description: "Run my-binary in the myservice container"

Adding a Python dependency (Django)

1. Add to django/requirements.txt
2. lando rebuild -y or docker compose build django

Do not pip install in a running container — it won't persist.

Adding a Node.js dependency (frontend)

1. lando npm install <pkg> --save (updates package.json in the volume-mounted source)
2. lando rebuild -y or docker compose build frontend (bakes it into the image layer)

Healthchecks

ollama has a healthcheck; django has one too. The frontend service uses depends_on: django: condition: service_healthy. If you change the Django port, update the healthcheck URL accordingly:

healthcheck:
  test: ["CMD-SHELL", "curl -sf http://localhost:8080/api/health/ || exit 1"]

Ports exposed to the host

When using Lando, host ports are assigned dynamically — use lando info to find them. The .lndo.site proxy URLs are stable.

Shell mapping (agent + user safety)

Do not run project runtime commands in the host shell. Use a service shell.

Use lando ssh -s <service> -c "<cmd>" (or docker exec -it <container> sh -lc "<cmd>") for one-off commands.