Getting Started

Self-Hosting

Copy page

Deploy your own OpenCircle instance with Docker.

Prerequisites

• At least 2GB RAM available
• 10GB free disk space
• A terminal/command line interface

Quick Start

Step 1: Install Docker

Install Docker on your system:

macOS:

Code
 
brew install --cask docker

Ubuntu/Debian:

Code
 
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
# Log out and back in

Windows: Download from docker.com

Step 2: Create Environment Configuration (.env.prod)

In your deployment directory, create a .env.prod file with the following variables:

Code
 
# ============================ Cloudflare R2 Object Storage ============================== #
# You can generate a new access key from the Cloudflare dashboard
R2_ENDPOINT_URL=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET_NAME=
R2_PUBLIC_URL=

# ===================================== Platform URL ===================================== #
# This is the URL of the frontend application
# Make sure to use HTTPS for production
PLATFORM_URL=http://localhost:3000/
ADMIN_URL=http://localhost:4000/
VITE_API_URL=http://localhost:8000/api

# =============================== Database URI for Backend =============================== #
# Make sure it is aligned with Docker Database Configuration
# You need to call the service name instead of "localhost"
DB_URL="postgresql://opencircle:opencircle@postgres:5432/opencircle"

REDIS_URL=redis://redis:6379
CELERY_BROKER_URL=redis://redis:6379
CELERY_RESULT_BACKEND=redis://redis:6379

# =========================== Docker Database Configuration ============================== #
POSTGRES_USER=opencircle
POSTGRES_PASSWORD=opencircle
POSTGRES_DB=opencircle

# =============================== Resend API Key ======================================== #
# This is service key for sending emails
RESEND_API_KEY=

# ================================= OAUTH Keys ========================================== #
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_REDIRECT_URI=http://localhost:3000/github-callback/

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI=http://localhost:3000/google-callback/

Step 3: Download Docker Compose Configuration

Code
 
git clone https://github.com/devscalelabs/opencircle.git
cd opencircle

Step 4: Start All Services

Code
 
docker compose up -d

Step 5: Verify Access

Once all services are running, access your applications:

• Platform: http://localhost:3000
• Admin Dashboard: http://localhost:4000
• API: http://localhost:8000

Services

Service	Port	Description
Platform	3000	Main application
Admin	4000	Admin dashboard
API	8000	Backend server
PostgreSQL	-	Database (internal)
Redis	-	Cache (internal)
Celery	-	Background tasks (internal)

Docker Compose Configuration (Manual Alternative)

If you prefer to create the docker-compose.yml file manually instead of downloading it, here's the complete configuration:

Code
 
services:
  postgres:
    image: postgres:15-alpine
    container_name: opencircle-postgres
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-postgres}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB:-opencircle}
    volumes:
      - opencircle_pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres}"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - opencircle-network

  redis:
    image: redis:7-alpine
    container_name: opencircle-redis
    volumes:
      - opencircle_redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - opencircle-network

  migrate:
    image: ghcr.io/devscalelabs/opencircle-api:latest
    container_name: opencircle-migration
    command: >
      sh -c "
      echo 'Waiting for PostgreSQL to be available...' &&
      while ! pg_isready -h postgres -p 5432 -U ${POSTGRES_USER:-postgres};
      do sleep 2; done &&
      echo '[MIGRATION] Running Alembic upgrade head...' &&
      uv run alembic upgrade head &&
      echo '[SUCCESS] Schema migration completed.'
      "
    environment:
      - DATABASE_URL=postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-opencircle}
      - DB_URL=postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-opencircle}
      - ENVIRONMENT=production
      - POSTGRES_USER=${POSTGRES_USER:-postgres}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB:-opencircle}
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - opencircle-network
    restart: "no"

  api:
    image: ghcr.io/devscalelabs/opencircle-api:latest
    container_name: opencircle-api
    environment:
      - DATABASE_URL=postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-opencircle}
      - DB_URL=postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-opencircle}
      - REDIS_URL=redis://redis:6379
      - CELERY_BROKER_URL=redis://redis:6379
      - CELERY_RESULT_BACKEND=redis://redis:6379
      - ENVIRONMENT=production
      - R2_ENDPOINT_URL=${R2_ENDPOINT_URL}