Getting Started

Get Octoprox up and running in minutes with Docker or set up a local development environment.

Quick Start with Docker (Recommended)

The fastest way to get Octoprox running is with the pre-built Docker image from GitHub Container Registry. You can run a single standalone instance or a multi-instance cluster behind HAProxy — pick whichever fits.

Standalone (single instance)

# Download the docker-compose file
curl -O https://raw.githubusercontent.com/octoprox/octoprox/main/docker-compose.ghcr.yml

# Start all services
docker compose -f docker-compose.ghcr.yml up -d

# View logs
docker compose -f docker-compose.ghcr.yml logs -f octoprox

Once started:

• Web UI: http://localhost:8000
• API: http://localhost:8000/api/v1
• Proxy Server: http://localhost:8080

Default credentials: admin / admin

Important: For production, update the environment variables in docker-compose.ghcr.yml:

• Set a strong OCTOPROX_AUTH_PASSWORD
• Set a secure random OCTOPROX_JWT_SECRET
• Change OCTOPROX_DB_PASSWORD and update POSTGRES_PASSWORD to match

To stop the services:

docker compose -f docker-compose.ghcr.yml down

Cluster (multi-instance, behind HAProxy)

For higher availability and throughput, run three Octoprox replicas behind an HAProxy load balancer, all sharing a single Postgres and Redis. The cluster compose file mounts its HAProxy config from haproxy/haproxy.cfg, so you need to download both files — keep the config in a haproxy/ directory next to the compose file:

# Download the cluster compose file and the HAProxy config it mounts
curl -O https://raw.githubusercontent.com/octoprox/octoprox/main/docker-compose.cluster.ghcr.yml
mkdir -p haproxy
curl -o haproxy/haproxy.cfg https://raw.githubusercontent.com/octoprox/octoprox/main/haproxy/haproxy.cfg

# Start the cluster (3 replicas + HAProxy + shared Postgres/Redis)
docker compose -f docker-compose.cluster.ghcr.yml up -d

# View aggregated logs
docker compose -f docker-compose.cluster.ghcr.yml logs -f

Once started, the cluster exposes the same endpoints as the standalone setup, plus the HAProxy stats UI:

• Web UI / API: http://localhost:8000
• Proxy Server: http://localhost:8080
• HAProxy stats: http://localhost:8404

Important: the compose file mounts ./haproxy/haproxy.cfg. If that file is missing when you run up, Docker silently creates an empty directory in its place and HAProxy crash-loops printing its usage banner — so make sure the config is downloaded first. Apply the same production hardening as the standalone setup: set a strong OCTOPROX_AUTH_PASSWORD, a secure random OCTOPROX_JWT_SECRET, and change OCTOPROX_DB_PASSWORD to match POSTGRES_PASSWORD.

To stop the cluster:

docker compose -f docker-compose.cluster.ghcr.yml down

For how the multi-instance machinery works — what’s shared, what’s elected, and how failover happens — see Deployment & Scaling.

Local Development Setup

Prerequisites

• Python 3.12+ (use pyenv for version management)
• Node.js 20+ (for frontend development, use nvm for version management)
• Docker and Docker Compose (for Redis and PostgreSQL)

Step 1: Clone and Setup Python Environment

# Clone the repository
git clone https://github.com/octoprox/octoprox.git
cd octoprox

# Install Python 3.12 using pyenv
pyenv install 3.12
pyenv local 3.12

# Verify Python version
python --version  # Should output: Python 3.12.x

# Create virtual environment and install dependencies
make setup-dev

# Activate the virtual environment (if needed manually)
source .venv/bin/activate

Step 2: Start Required Services

# Start Redis and PostgreSQL
docker-compose up -d redis
docker-compose up -d postgres

Step 3: Run the API Server

make run-dev

The API will be available at http://localhost:8000.

Step 4: Run the Frontend (Optional)

# Ensure you're using the correct Node.js version
nvm use 20  # or: nvm use --lts

# Install frontend dependencies
make web-install

# Start the development server
make web-dev

The web UI will be available at http://localhost:3000.

Note: If you see npm errors, ensure Node.js is properly installed:

node --version  # Should be v20.x.x or higher
npm --version   # Should be v10.x.x or higher

Docker Deployment

Octoprox ships with four ready-made Docker Compose flavours so you can match the deployment shape to what you actually need — a single instance for development, or a horizontally-scaled cluster fronted by HAProxy for HA / higher throughput. Two of those flavours use the pre-built image from GitHub Container Registry (no local build), and two build from your checkout.

Single-instance shortcuts:

# Local build
make docker-compose-up
make docker-compose-down

# Build the image manually
make docker-build
make docker-run

Multi-instance cluster shortcuts:

# Local build (3 replicas + HAProxy + shared Postgres/Redis)
make cluster-up
make cluster-logs
make cluster-down

# Pre-built GHCR image — production-ready starting point.
# Needs the compose file + haproxy/haproxy.cfg — see the cluster Quick Start above.
docker compose -f docker-compose.cluster.ghcr.yml up -d
docker compose -f docker-compose.cluster.ghcr.yml logs -f
docker compose -f docker-compose.cluster.ghcr.yml down

The cluster exposes the same :8000 (API/UI) and :8080 (proxy traffic) ports as the single-instance setup, plus :8404 for HAProxy stats. See Deployment & Scaling for how the multi-instance machinery works — what’s shared, what’s elected, how failover happens.

Makefile Commands

Here are the most commonly used commands:

Next Steps

• Configuration - Learn about configuration options
• Deployment & Scaling - Single vs multi-instance, HA, and how horizontal scaling works
• AWS Setup - Set up AWS cloud connector
• GCP Setup - Set up GCP cloud connector
• Azure Setup - Set up Azure cloud connector
• BrightData Setup - Set up BrightData proxy provider
• Oxylabs Setup - Set up Oxylabs proxy provider
• API Reference - Explore the REST API