Self-Hosting OpenPieces: A Complete Guide

Why Self-Host?

Self-hosting gives you full control over your data, workflows, and infrastructure. No data ever leaves your network. No third-party API calls. No usage limits.

Requirements

• A Linux server (Ubuntu 22.04+ or Debian 12+ recommended)
• Docker and Docker Compose
• A PostgreSQL database (14+)
• At least 4GB of RAM
• A domain name with SSL (optional but recommended)

Step 1: Clone the Repository

bash
git clone https://github.com/openpieces/openpieces.git
cd openpieces

Step 2: Configure Environment

Copy the example environment file and adjust the values:

bash
cp .env.example .env

The key variables to set are:

• DATABASE_URL — your PostgreSQL connection string
• JWT_SECRET — a random 64-character string
• STORAGE_BACKEND — local or S3-compatible

Step 3: Start the Services

bash
docker compose up -d

This starts three services:

1. The API server on port 3000
2. The worker process for executing pieces
3. A Postgres instance (if you didn't provide an external one)

Step 4: Verify

Visit http://your-server:3000 and complete the initial setup wizard. You should see the dashboard with zero pieces — ready for your first deployment.

Production Considerations

• Use a reverse proxy like Caddy or Nginx for TLS termination
• Set up regular database backups
• Monitor with Prometheus and Grafana using the built-in metrics endpoint
• Configure resource limits for piece execution to prevent noisy neighbours