Quickstart: Docker Compose (TOML Configuration)

This guide provides a production-ready docker-compose.yml to deploy the DevLens stack (App, Agent, and AI services) on a single host. The services share a unified configuration file (devlens.toml) and a persistent data directory.

Prerequisites

• Container Engine: Docker Engine 20.10+ or Podman 3.4+
• Orchestration: Docker Compose 1.29+ or the Docker CLI compose plugin.
  • Note: Podman users can use podman-compose or the native podman compose command (available in newer versions).
• Environment: VERSION environment variable set to your target image tag (defaults to latest).

---

1. Directory Structure

Organize your deployment directory as follows:

/home/demo/devlens/
├── data/
│   ├── devlens.toml      ← Configuration file (create this first)
│   └── (Persistent DB & logs will be generated here)
└── docker-compose.yml

Initialize the data directory:

mkdir -p /home/demo/devlens/data

---

2. Compose Configuration

Create a docker-compose.yml in /home/demo/devlens/. This configuration mounts the host's data directory into each container and passes the configuration path via the entrypoint.

services:
  app:
    container_name: devlens-app
    image: source.rdctd.de/devlens/app:${VERSION:-latest}
    restart: always
    volumes:
      - /home/demo/devlens/data:/data
    entrypoint: /app/src/app -config=/data/devlens.toml

  agent:
    container_name: devlens-agent
    image: git.rdctd.de/devlens/agent:${VERSION:-latest}
    restart: always
    volumes:
      - /home/demo/devlens/data:/data
    entrypoint: /app/src/agent -config=/data/devlens.toml

  ai:
    container_name: devlens-ai
    image: git.rdctd.de/devlens/ai:${VERSION:-latest}
    restart: always
    volumes:
      - /home/demo/devlens/data:/data
    entrypoint: /app/src/ai -config=/data/devlens.toml

Image Versioning

By default, the configuration pulls the latest tag. To use a specific version, export the VERSION variable before deployment:

export VERSION=1.2.3

---

3. Deployment

Navigate to your deployment directory and start the services:

docker compose up -d

(If using Podman without the Docker alias, use podman-compose up -d or podman compose up -d.)

The engine will: 1. Pull the app, agent, and ai images. 2. Initialize containers with the host-mounted /data volume. 3. Execute each service using the shared devlens.toml.

Verification

Check the service status:

docker compose ps

Monitor logs:

docker compose logs -f

Access the DevLens UI at http://localhost:3000 (or your host's IP address).

---

4. Configuration Updates

Changes to devlens.toml require a service restart to take effect. You can restart specific services to minimize downtime:

docker compose restart app

---

5. Data Persistence

All stateful data (SQLite databases, telemetry logs, and retention data) is stored in /home/demo/devlens/data. Ensure this directory is included in your backup rotation to prevent data loss.

---

6. Cleanup

To stop and remove the containers:

docker compose down

To remove containers and wipe all persistent data:

docker compose down -v && rm -rf /home/demo/devlens/data/*