Docker Deployment

Overview

switchAILocal provides official Docker images and a Docker Compose setup for easy deployment and production use.

Quick Start with Docker Compose

Clone Repository

git clone https://github.com/traylinx/switchAILocal.git
cd switchAILocal

Create Configuration

cp config.example.yaml config.yaml

Edit config.yaml to add your provider credentials and settings.

Start with Docker Compose

docker-compose up -d

Or use the hub script:

./ail.sh start --docker

Verify Deployment

curl http://localhost:18080/health

Docker Compose Configuration

The included docker-compose.yml provides a complete production-ready setup:

docker-compose.yml

services:
  switchailocal:
    image: ${SWITCH_AI_IMAGE:-traylinx/switchailocal:latest}
    pull_policy: always
    container_name: switchailocal
    environment:
      TZ: ${TZ:-UTC}
      REMOTE_COMMAND_HOST: ${REMOTE_COMMAND_HOST:-http://host.docker.internal:18888}
    extra_hosts:
      - "host.docker.internal:host-gateway"
    ports:
      - "18080:18080"
    volumes:
      - ./config.yaml:/app/config.yaml
      - ${HOME}/.switchailocal:/home/appuser/.switchailocal
      - ./logs:/app/logs
      - ./plugins:/app/plugins
    restart: unless-stopped

Configuration Options

Environment Variables:

TZ: Timezone for logs and timestamps (default: UTC)
REMOTE_COMMAND_HOST: Host for remote command execution
SWITCH_AI_IMAGE: Docker image to use (default: traylinx/switchailocal:latest)

Volumes:

./config.yaml: Main configuration file
~/.switchailocal: OAuth tokens and authentication data
./logs: Application logs (when file logging is enabled)
./plugins: Custom LUA plugins and Cortex Router skills

Building from Source

Build your own Docker image from source:

Build with Docker Compose

docker-compose build

Or with version metadata:

VERSION=1.0.0 COMMIT=$(git rev-parse HEAD) BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  docker-compose build

Run Custom Build

docker-compose up -d

Build Arguments

The Dockerfile supports these build arguments:

Dockerfile

ARG VERSION=dev
ARG COMMIT=none
ARG BUILD_DATE=unknown

RUN CGO_ENABLED=0 GOOS=linux go build \
  -ldflags="-s -w \
    -X 'main.Version=${VERSION}' \
    -X 'main.Commit=${COMMIT}' \
    -X 'main.BuildDate=${BUILD_DATE}'" \
  -o ./switchAILocal ./cmd/server/

Dockerfile Architecture

The official Dockerfile uses a multi-stage build for optimal image size:

# Build stage
FROM golang:1.25-alpine AS builder

WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY . .

ARG VERSION=dev
ARG COMMIT=none
ARG BUILD_DATE=unknown

RUN CGO_ENABLED=0 GOOS=linux go build \
  -ldflags="-s -w \
    -X 'main.Version=${VERSION}' \
    -X 'main.Commit=${COMMIT}' \
    -X 'main.BuildDate=${BUILD_DATE}'" \
  -o ./switchAILocal ./cmd/server/

# Runtime stage
FROM alpine:3.23.3

RUN apk add --no-cache tzdata ca-certificates nodejs npm

# Install Gemini CLI in the container
RUN npm install -g @google/gemini-cli

# Create a non-root user
RUN addgroup -S appgroup && adduser -S appuser -G appgroup

WORKDIR /app

COPY --from=builder /app/switchAILocal /app/switchAILocal
COPY config.example.yaml /app/config.example.yaml
COPY static /app/static

RUN chown -R appuser:appgroup /app

EXPOSE 18080

ENV TZ=UTC

USER appuser

CMD ["./switchAILocal"]

The image includes Node.js and npm to support the Gemini CLI tool for CLI-based authentication.

Using Pre-built Images

Docker Hub

Pull the latest official image:

docker pull traylinx/switchailocal:latest

Run directly:

docker run -d \
  -p 18080:18080 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  -v ~/.switchailocal:/home/appuser/.switchailocal \
  --name switchailocal \
  traylinx/switchailocal:latest

Version Tags

Available image tags:

latest: Most recent stable release
vX.Y.Z: Specific version (e.g., v1.0.0)
dev: Development builds from main branch

Volume Management

Configuration Volume

Mount your config.yaml into the container:

-v $(pwd)/config.yaml:/app/config.yaml

Authentication Data

Persist OAuth tokens and session data:

-v ~/.switchailocal:/home/appuser/.switchailocal

Logs

When file logging is enabled, mount a logs directory:

config.yaml

logging-to-file: true
logs-max-total-size-mb: 500

-v $(pwd)/logs:/app/logs

Plugins

Mount custom plugins and skills:

-v $(pwd)/plugins:/app/plugins

Environment Variables

Timezone

Set the container timezone:

docker-compose.yml

environment:
  TZ: America/New_York

Remote Command Host

For distributed deployments with remote command execution:

docker-compose.yml

environment:
  REMOTE_COMMAND_HOST: http://command-service:18888

Networking

Host Network Access

The Docker Compose configuration includes host.docker.internal mapping for accessing services on the host machine:

docker-compose.yml

extra_hosts:
  - "host.docker.internal:host-gateway"

This allows the container to connect to:

Ollama running on host: http://host.docker.internal:11434
LM Studio on host: http://host.docker.internal:1234
Other local services

Custom Networks

For advanced deployments, create a custom network:

docker-compose.yml

networks:
  switchai:
    driver: bridge

services:
  switchailocal:
    networks:
      - switchai

Health Checks

Add a Docker health check:

docker-compose.yml

services:
  switchailocal:
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:18080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Resource Limits

Set resource constraints for production:

docker-compose.yml

services:
  switchailocal:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M

Updating

Pull Latest Image

docker-compose pull

Restart Services

docker-compose up -d

Verify Update

docker logs switchailocal

Troubleshooting

View Logs

docker-compose logs -f switchailocal

Check Container Status

docker-compose ps

Restart Container

docker-compose restart switchailocal

Execute Commands Inside Container

docker exec -it switchailocal sh

Permission Issues

If you encounter permission errors with mounted volumes:

# Fix ownership
sudo chown -R 1000:1000 ~/.switchailocal
sudo chown -R 1000:1000 ./logs

Production Considerations

Security

Always use TLS in production (tls.enable: true in config.yaml)
Store API keys securely (use Docker secrets or environment variables)
Restrict management API access (remote-management.allow-remote: false)
Use strong api-keys and secret-key values

Performance

Enable usage statistics for monitoring (usage-statistics-enabled: true)
Configure appropriate request-retry values
Use streaming.keepalive-seconds for long-running connections
Set logs-max-total-size-mb to prevent disk exhaustion

Monitoring

Monitor container health with docker-compose ps
Check logs regularly with docker-compose logs
Use the Management Dashboard at http://localhost:18080/management
Set up alerts for provider failures using hooks

Next Steps

Management Dashboard

Configure providers and monitor performance through the web UI

Troubleshooting

Resolve common deployment and runtime issues

Get Started

Core Concepts

Configuration

Intelligent Systems

Advanced Features

Guides

Overview

Quick Start with Docker Compose

Docker Compose Configuration

Building from Source

Build Arguments

Dockerfile Architecture

Using Pre-built Images

Docker Hub

Version Tags

Volume Management

Configuration Volume

Authentication Data

Logs

Plugins

Environment Variables

Timezone

Remote Command Host

Networking

Host Network Access

Custom Networks

Health Checks

Resource Limits

Updating

Troubleshooting

View Logs

Check Container Status

Restart Container

Execute Commands Inside Container

Permission Issues

Production Considerations

Next Steps

Management Dashboard

Troubleshooting

​Overview

​Quick Start with Docker Compose

​Docker Compose Configuration

​Building from Source

​Build Arguments

​Dockerfile Architecture

​Using Pre-built Images

​Docker Hub

​Version Tags

​Volume Management

​Configuration Volume

​Authentication Data

​Logs

​Plugins

​Environment Variables

​Timezone

​Remote Command Host

​Networking

​Host Network Access

​Custom Networks

​Health Checks

​Resource Limits

​Updating

​Troubleshooting

​View Logs

​Check Container Status

​Restart Container

​Execute Commands Inside Container

​Permission Issues

​Production Considerations

​Next Steps

Management Dashboard

Troubleshooting

Overview

Quick Start with Docker Compose

Docker Compose Configuration

Building from Source

Build Arguments

Dockerfile Architecture

Using Pre-built Images

Docker Hub

Version Tags

Volume Management

Configuration Volume

Authentication Data

Logs

Plugins

Environment Variables

Timezone

Remote Command Host

Networking

Host Network Access

Custom Networks

Health Checks

Resource Limits

Updating

Troubleshooting

View Logs

Check Container Status

Restart Container

Execute Commands Inside Container

Permission Issues

Production Considerations

Next Steps