Docker Setup

Docker provides the easiest way to run A1KnowHow and all its dependencies. This guide will help you set up A1KnowHow using Docker and docker-compose. You’ll need Docker Engine 20.10+ and Docker Compose 2.0+ installed on your system.

Quick Start

Download the docker-compose.yaml file
Configure config.yaml and secrets (see Configuration)
Start the stack: docker-compose up -d

Docker Compose Setup

Basic docker-compose.yaml

Create a docker-compose.yaml file with the following structure:

version: '3.8'

services:
  a1knowhow:
    image: a1knowhow:latest
    container_name: a1knowhow
    restart: unless-stopped
    ports:
      - "8383:8383"
    volumes:
      - ./pb_data:/app/pb_data
      - ./config.yaml:/app/config/config.yaml:ro
      - ./secrets:/run/secrets/pocketrag:ro
    networks:
      - a1knowhow-network
    depends_on:
      - qdrant
      - docling
      - ollama

  qdrant:
    image: qdrant/qdrant:latest
    container_name: qdrant
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - ./qdrant_data:/qdrant/storage
    restart: unless-stopped
    networks:
      - a1knowhow-network

  docling:
    image: docling/docling-serve:latest
    container_name: docling
    ports:
      - "8000:8000"
    restart: unless-stopped
    networks:
      - a1knowhow-network

  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ./ollama_data:/root/.ollama
    restart: unless-stopped
    networks:
      - a1knowhow-network

networks:
  a1knowhow-network:
    driver: bridge

volumes:
  qdrant_data:
  ollama_data:

Configuration and secrets

Mount YAML config and secret files (do not pass secrets via container environment:):

# config.yaml (excerpt)
server:
  listen_address: "0.0.0.0:8383"
  encryption_key: "file:/run/secrets/pocketrag/encryption_key"
llm:
  url: "http://ollama:11434"
importer:
  url: "http://docling:8000"

mkdir -p secrets
openssl rand -base64 32 | tr -dc 'a-zA-Z0-9' | head -c 32 > secrets/encryption_key
chmod 600 secrets/encryption_key

Optional: encrypt secrets/ or config.overlay.yaml with SOPS and decrypt to the mount path before starting the container.

Running the Stack

Start Services

docker-compose up -d

This will:

Pull required images (if not already present)
Create the network
Start all services in the background

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f a1knowhow

Stop Services

docker-compose stop

Stop and Remove Containers

docker-compose down

Stop and Remove Everything (including volumes)

docker-compose down -v

Warning: This will delete all data stored in volumes.

Accessing the Application

Once the stack is running:

Web UI: Open http://localhost:8383 in your browser
API: Available at http://localhost:8383/api
Health Check: http://localhost:8383/health

Initial Setup

Create Admin User

After starting the stack, create your first admin user:

docker-compose exec a1knowhow /app/pocketrag   --encryptionEnv=your-encryption-key   superuser create [email protected] your-password

Verify Services

Check that all services are running:

docker-compose ps

All services should show “Up” status.

Using Pre-built Images

Official Images

If official Docker images are available:

services:
  a1knowhow:
    image: a1knowhow/a1knowhow:latest

Building from Source

To build your own image:

docker build -t a1knowhow:latest .

Then update docker-compose.yaml to use the local image:

services:
  a1knowhow:
    image: a1knowhow:latest
    build:
      context: .
      dockerfile: Dockerfile

Data Persistence

Data is stored in Docker volumes:

A1KnowHow Data: ./pb_data (or volume rg_pb_data)
Qdrant Data: ./qdrant_data (or volume rg_qdrant_data)
Ollama Models: ./ollama_data (or volume ollama_data)

Backup

To backup your data:

# Backup A1KnowHow data
docker-compose exec a1knowhow tar -czf /tmp/backup.tar.gz /app/pb_data

# Copy backup from container
docker cp a1knowhow:/tmp/backup.tar.gz ./backup.tar.gz

Restore

To restore from backup:

# Copy backup to container
docker cp ./backup.tar.gz a1knowhow:/tmp/backup.tar.gz

# Extract backup
docker-compose exec a1knowhow tar -xzf /tmp/backup.tar.gz -C /

Ollama Models

After starting Ollama, download required models:

# Download chat model
docker-compose exec ollama ollama pull qwen3

# Download embedding model
docker-compose exec ollama ollama pull embeddinggemma

Verify models are installed:

docker-compose exec ollama ollama list

Troubleshooting

Port Conflicts

If ports are already in use, modify the port mappings in docker-compose.yaml:

ports:
  - "8384:8383"  # Use different host port

Service Not Starting

Check logs for errors:

docker-compose logs a1knowhow

Common issues:

Missing or unreadable secret files referenced by file: in config.yaml
Incorrect service URLs
Insufficient disk space
Port conflicts

Network Issues

Services communicate via the a1knowhow-network. If services can’t connect:

Verify network exists: docker network ls
Check service connectivity: docker-compose exec a1knowhow ping qdrant
Recreate network: docker-compose down && docker-compose up -d

Volume Permissions

If you encounter permission issues:

# Fix permissions (Linux)
sudo chown -R $USER:$USER ./pb_data ./qdrant_data ./ollama_data

Production Considerations

For production deployments:

Use specific image tags instead of latest
Set up proper secrets management for sensitive data
Configure resource limits for containers
Set up monitoring and logging
Use reverse proxy (nginx, Traefik) for HTTPS
Regular backups of volumes
Health checks and auto-restart policies

Resource Limits Example

services:
  a1knowhow:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G

Next Steps

Configure Configuration for your setup
Review Dependencies documentation
Learn about Features to use A1KnowHow

Documentation