Docker Deployment

This guide explains how to deploy Oxy using Docker containers, providing an alternative to the traditional server-based deployment approach.

​

Prerequisites

Before you start, ensure you have:

• Docker installed on your host system
• An Oxy workspace with your configuration files, agents, and workflows
• Required API keys and environment variables for your deployment

​

Quick Start

The fastest way to get started with Oxy on Docker is to use the pre-built image from GitHub Packages:

# Pull the latest Oxy Docker image
docker pull ghcr.io/oxy-hq/oxy:0.2.3

# Run Oxy with a mounted workspace
docker run -d \
  --name oxy-instance \
  -p 3000:3000 \
  -v /path/to/your/workspace:/app \
  -e OPENAI_API_KEY=your-api-key \
  -e OXY_STATE_DIR=/app \
  ghcr.io/oxy-hq/oxy:0.2.3

​

Why Use Docker Compose?

Docker Compose lets you define and manage multi-container applications with a single YAML file. For Oxy, Compose makes it easy to:

• Start Oxy and related services (like databases or proxies) with one command
• Configure environment variables, volumes, and ports in one place
• Ensure all containers are networked and started in the right order
• Reproduce your deployment setup easily across machines or teams

In short: Docker Compose simplifies running Oxy in production or development, especially when you need more than one container.

​

Reference Architecture Diagram

​

Detailed Deployment Steps

# Example workspace structure
workspace/
├── config.yml
├── my-agent.agent.yml
├── my-workflow.workflow.yml
└── resources/
    └── data.json

version: '3'
services:
  oxy:
    image: ghcr.io/oxy-hq/oxy:0.2.3
    container_name: oxy-instance
    ports:
      - "3000:3000"
    working_dir: /workspace
    volumes:
      - ./workspace:/workspace
      - ./oxy-data:/data
    environment:
      - OPENAI_API_KEY=your-openai-api-key
      - OXY_STATE_DIR=/data
    restart: unless-stopped
    command: ["oxy", "serve", "--host", "0.0.0.0", "--port", "3000"]

docker-compose up -d

​

Volume Mounting Explained

When running Oxy in Docker, you’ll typically need to mount two types of directories:

1. Workspace Mount: Maps your local Oxy workspace to the container

   Copy

   Ask AI

   -v /path/to/your/workspace:/workspace
   

   This allows Oxy to access your configuration, agents, and workflows.

2. Data Mount: Provides persistent storage for Oxy’s state

   Copy

   Ask AI

   -v /path/to/persistent/data:/data
   

   This ensures your data is preserved even if the container is restarted.

​

Data Persistence

Oxy uses SQLite for data storage by default, which means proper volume mounting is essential for maintaining your data across container restarts or updates.

​

Storage Location

• By default, Oxy stores its data in ~/.local/share/oxy/ on the host system
• When using Docker, you should explicitly set the OXY_STATE_DIR environment variable (typically to /data) and mount a volume to that location

​

What Data Is Stored

Oxy stores several types of data that need to be persisted:

• SQLite database files containing state information
• Semantic information from synchronized databases
• Cached query results and intermediate data
• Workflow execution history and checkpoints

​

Example Docker Setup with Proper Data Persistence

version: '3'
services:
  oxy:
    image: ghcr.io/oxy-hq/oxy:0.2.3
    container_name: oxy-instance
    ports:
      - "3000:3000"
    working_dir: /workspace
    volumes:
      - ./workspace:/workspace
      - ./oxy-data:/data  # Essential for data persistence
    environment:
      - OPENAI_API_KEY=your-openai-api-key
      - OXY_STATE_DIR=/data  # Points to the mounted volume
    restart: unless-stopped
    command: ["oxy", "serve", "--host", "0.0.0.0", "--port", "3000"]

​

Environment Variables

Common environment variables to configure in your Oxy container:

​

Advanced Configuration

​

Custom Docker Images

If you need to extend the official Oxy image with additional dependencies or configuration, you can create your own Dockerfile:

FROM ghcr.io/oxy-hq/oxy:0.2.3

# Add custom dependencies
RUN apt-get update && apt-get install -y your-package

# Add custom files
COPY ./custom-config.yml /default-config.yml

# Override the default command if needed
CMD ["oxy", "serve", "--config", "/default-config.yml"]

​

Health Checks

Add health checks to ensure your container is running properly:

services:
  oxy:
    # ...existing configuration...
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

​

Troubleshooting

​

Next Steps

Once your Docker deployment is up and running, you can:

• Set up CI/CD pipelines to automatically update your Oxy instance
• Implement monitoring and logging solutions
• Configure backups for your persistent data
• Scale horizontally for higher availability

For more information on using Oxy, refer to the main documentation.