Docker Guide

kinetic-context is designed to run in Docker containers for easy deployment and isolation.

Quick Start with Docker

The easiest way to run kinetic-context is using the installation script, which sets up Docker Compose automatically.

Docker Compose Setup

The standard setup uses Docker Compose with two services:

opencode - The AI code analysis service
kinetic-context - The main application server

Standard Compose File

version: '3.8'

services:
  opencode:
    image: ghcr.io/anomalyco/opencode:latest
    ports:
      - "7168:4096"
    volumes:
      - ~/.kctx/config:/config
      - ~/.kctx/data:/data
    command: ["serve", "--hostname=0.0.0.0"]
    environment:
      - OPENCODE_CONFIG=/config/opencode.json
    restart: unless-stopped

  kinetic-context:
    image: christopherkapic/kinetic-context:latest
    ports:
      - "7167:3000"
    volumes:
      - ~/.kctx/data:/data
      - ~/.kctx/config:/config
    environment:
      - CORS_ORIGIN=http://localhost:7167
      - NODE_ENV=production
      - PACKAGES_DIR=/data/packages
      - PROJECTS_DIR=/data/projects
      - OPENCODE_CONFIG_PATH=/config/opencode.json
      - OPENCODE_URL=http://opencode:4096
    depends_on:
      - opencode
    restart: unless-stopped

GitHub Container Registry Authentication

Important: The opencode image is hosted on GitHub Container Registry (ghcr.io) and requires authentication.

Authenticating to ghcr.io

Before pulling the opencode image, you must authenticate:

docker login ghcr.io

When prompted:

Username: Your GitHub username
Password: A GitHub Personal Access Token (PAT) with read:packages permission

Creating a GitHub Personal Access Token

Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
Click "Generate new token (classic)"
Give it a descriptive name (e.g., "kinetic-context-docker")
Select the read:packages scope
Click "Generate token"
Copy the token immediately (you won't be able to see it again)
Use this token as the password when running docker login ghcr.io

Token Persistence

The authentication is stored in ~/.docker/config.json. The token will persist until you log out or it expires.

To log out:

docker logout ghcr.io

Volume Mounts

kinetic-context requires two volume mounts:

Data Volume (`/data`)

Contains package repositories and project configurations:

/data
├── packages/
│   ├── package-name/          # Cloned git repository
│   └── package-name.json      # Package configuration
└── projects/
    └── project-name.json      # Project configuration

Config Volume (`/config`)

Contains the OpenCode configuration:

/config
└── opencode.json              # OpenCode AI configuration

Port Mappings

Default port mappings:

7167 → kinetic-context web UI and API (container port 3000)
7168 → OpenCode service (container port 4096)

You can change these in your compose.yaml if needed:

services:
  kinetic-context:
    ports:
      - "8080:3000"  # Use port 8080 instead of 7167

Running with Docker Run

If you prefer docker run instead of Docker Compose:

# Start opencode
docker run -d \
  --name opencode \
  -p 7168:4096 \
  -v ~/.kctx/config:/config \
  -v ~/.kctx/data:/data \
  -e OPENCODE_CONFIG=/config/opencode.json \
  ghcr.io/anomalyco/opencode:latest \
  serve --hostname=0.0.0.0

# Start kinetic-context
docker run -d \
  --name kinetic-context \
  -p 7167:3000 \
  -v ~/.kctx/data:/data \
  -v ~/.kctx/config:/config \
  -e CORS_ORIGIN=http://localhost:7167 \
  -e NODE_ENV=production \
  -e PACKAGES_DIR=/data/packages \
  -e PROJECTS_DIR=/data/projects \
  -e OPENCODE_CONFIG_PATH=/config/opencode.json \
  -e OPENCODE_URL=http://localhost:7168 \
  --link opencode:opencode \
  christopherkapic/kinetic-context:latest

Building from Source

To build the Docker image from source:

# Clone the repository
git clone https://github.com/christopher-kapic/kinetic-context.git
cd kinetic-context

# Build the image
docker build -t christopherkapic/kinetic-context:latest .

# Or use docker compose
docker compose build

Image Tags

Available image tags on DockerHub:

christopherkapic/kinetic-context:latest - Latest stable release
christopherkapic/kinetic-context:0.1.0 - Specific version tag

Updating Images

To update to the latest version:

# Pull latest images
docker pull christopherkapic/kinetic-context:latest
docker pull ghcr.io/anomalyco/opencode:latest

# Restart services
docker compose -f ~/.kctx/compose.yaml restart

Or using the kctx command:

kctx restart

Troubleshooting

Image Pull Errors

If you get authentication errors when pulling the opencode image:

# Verify you're logged in
docker login ghcr.io

# Check your token has read:packages permission

Port Conflicts

If ports 7167 or 7168 are already in use:

Edit ~/.kctx/compose.yaml
Change the port mappings
Restart the services

Volume Permission Issues

If you encounter permission issues with volumes:

# On Linux, you may need to adjust permissions
sudo chown -R $USER:$USER ~/.kctx

Container Won't Start

Check the logs:

# Using kctx
kctx logs

# Or directly
docker compose -f ~/.kctx/compose.yaml logs

Production Considerations

For production deployments:

Use specific version tags instead of latest
Set up proper backups for your data volume
Configure resource limits in compose.yaml
Use secrets management for API keys
Set up monitoring and logging
Configure reverse proxy (nginx, traefik, etc.) for HTTPS

Example with resource limits:

services:
  kinetic-context:
    image: christopherkapic/kinetic-context:0.1.0
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G

Docker Guide

On this page