Docker Compose

Deploy Onlook using Docker Compose on VMs or local machines. This is a simple, single-container deployment designed for small teams and basic self-hosting needs. For enterprise-grade deployments requiring high availability and scalability, use the Cloud Deployment option.

Prerequisites

System Requirements:

4+ CPU cores
8GB+ RAM (16GB recommended)
50GB+ available disk space
Docker 20.10+ and Docker Compose 2.0+

Software Requirements:

Bun - Package manager and runtime
Node.js v20.16.0+ (avoid v20.11.0)
Git
Docker & Docker Compose

Basic Deployment

Note: This is a simple deployment suitable for small teams and testing. For development, use bun dev in the repository root.

1. Clone the Repository

git clone https://github.com/onlook-dev/onlook.git
cd onlook

# Install dependencies
bun install

2. Setup Environment Variables

For Docker Compose deployment, you need to create a environment file.

# Run interactive environment setup
bun run setup:env

Required variables:

Supabase: Production database URL and API keys
OpenRouter API Key: For AI chat features
CodeSandbox Token: For development containers

For detailed instructions on obtaining these API keys, see the development setup guide.

3. Start Backend Services

bun backend:start

This starts Supabase locally with PostgreSQL database, authentication, and storage. This will spin up a separate Docker compose service. For production supabase connection, change the Supabase API keys in the .env file.

4. Initialize Database

# Push database schema
bun db:push

5. Deploy with Docker Compose

Deploy the production container from the repository root:

docker-compose up -d

This builds and starts:

Web Application: Production-built Next.js application (port 3000)
Health checks: Automatic container health monitoring
Auto-restart: Container restarts automatically on failure

Note: The Docker container uses network_mode: "host" to access the local Supabase services running on your host machine. This allows the container to connect to http://127.0.0.1:54321 (Supabase API) and 127.0.0.1:54322 (PostgreSQL).

6. Verify Deployment

Main Application: http://localhost:3000
Supabase Dashboard: http://localhost:54323 (from backend:start)

Check the service is running:

docker-compose ps
curl http://localhost:3000

Troubleshooting

Common issues:

Port 3000 in use: Stop other services or change port
Docker build fails: Run docker system prune and retry
Database connection: Verify bun backend:start is running and Supabase is accessible at http://127.0.0.1:54321
Container can't connect to Supabase: Ensure network_mode: "host" is set in docker-compose.yml for localhost access

Limitations & Considerations

This deployment is designed for simplicity, not high reliability:

Limitations:

Single container (single point of failure)
No built-in load balancing or auto-scaling
Manual backup and disaster recovery
Limited to vertical scaling only
No high availability guarantees

Suitable for:

Small teams (< 10 users)
Development/testing environments
Proof of concept deployments
Basic self-hosting needs

Not suitable for:

Mission-critical production workloads
Large teams requiring high availability
Environments needing 99.9%+ uptime

For enterprise-grade deployments, use the Cloud Deployment option with proper redundancy and scaling.

On this page