Introduction

Self-Hosting InstantDB

InstantDB can be self-hosted on your own infrastructure using Docker. You get full feature parity with InstantDB Cloud, complete data ownership, and control over your deployment.

Quick Start

Clone the repository and start all services:

git clone https://github.com/instantdb/instant.git
cd instant
docker compose up

Access your self-hosted instance:

Dashboard: http://localhost:3000
API: http://localhost:8888
MinIO Console: http://localhost:9001 (minioadmin/minioadmin)

Open your browser, set localStorage to use your local backend:

localStorage.setItem('devBackend', 'true');

Refresh the page and you're running on your own infrastructure!

What's Included

Your self-hosted setup includes:

PostgreSQL 16 - Your database with required extensions
MinIO - S3-compatible file storage
InstantDB Server - The backend API
Dashboard - The web interface

All services run in Docker with automatic configuration. MinIO buckets are created automatically on first start.

Production Deployment

For production, we recommend using Coolify - a self-hosted platform that makes deployment simple.

Using Coolify

Install Coolify on your VPS (requires Docker)
Push your code to a Git repository
In Coolify: Create New Resource → Docker Compose
Select docker-compose-coolify.yml from your repository
Configure environment variables in Coolify UI:

# IMPORTANT: These are REQUIRED for OAuth and CORS to work
SERVER_ORIGIN=https://api.yourdomain.com
DASHBOARD_ORIGIN=https://app.yourdomain.com
MINIO_PUBLIC_URL=https://s3.yourdomain.com
NEXT_PUBLIC_DEVHOST=https://api.yourdomain.com

# Optional: Database name (defaults to 'instant' if not set)
# POSTGRES_DB=instant

Configure domain ports in Coolify UI:

Coolify needs to know which internal port each service listens on. Set these domains in the Coolify UI:

Server: https://api.yourdomain.com:8888
Client: https://app.yourdomain.com:3000
MinIO: https://s3.yourdomain.com:9000

The port numbers (:8888, :3000, :9000) tell Coolify where to route traffic inside the container. Users still access your services via standard HTTPS (port 443).

Deploy! Coolify will:
- Build your Docker images
- Generate SSL certificates
- Handle reverse proxy with Traefik

After deployment, you'll have:

API: https://api.yourdomain.com
Dashboard: https://app.yourdomain.com
Storage: https://s3.yourdomain.com

OAuth Setup

To use Google, Apple, or LinkedIn authentication with your self-hosted instance:

Google OAuth

Go to Google Cloud Console
Create OAuth 2.0 Client ID
Add redirect URI: https://api.yourdomain.com/runtime/oauth/callback
In your dashboard, go to Auth → Google OAuth
Add your Client ID and Secret

The same process works for Apple and LinkedIn - just use your custom domain in the redirect URI.

File Storage

Self-hosted InstantDB uses MinIO for file storage. Files are stored locally on your server, and presigned URLs are automatically generated for browser access.

The storage API works the same as InstantDB Cloud - files are automatically stored in MinIO and accessible via your storage domain.

Environment Variables

Key environment variables you can configure:

Required for Coolify/Production

You must set these in Coolify UI:

SERVER_ORIGIN - Your API URL (e.g., https://api.yourdomain.com) - Required for OAuth and CORS
DASHBOARD_ORIGIN - Your dashboard URL (e.g., https://app.yourdomain.com) - Required for CORS
NEXT_PUBLIC_DEVHOST - Your API URL - Required for client to connect to server
MINIO_PUBLIC_URL - Your storage URL (e.g., https://s3.yourdomain.com) - Required for file URLs

Auto-Generated by Coolify

These are automatically generated - no manual configuration needed:

SERVICE_USER_POSTGRES - Database username
SERVICE_PASSWORD_POSTGRES - Database password
SERVICE_USER_MINIO - MinIO username
SERVICE_PASSWORD_MINIO - MinIO password

Optional

POSTGRES_DB - Database name (defaults to instant if not set)
OAUTH_DEFAULT_SCOPE - OAuth scope (default: "email openid")

Troubleshooting

Server won't start

Issue: PostgreSQL connection errors

Solution: Make sure PostgreSQL is healthy before server starts. The compose files include health checks that ensure proper startup order.

CORS errors (Coolify/Production only)

Issue: Browser console shows Access to fetch at 'https://api.yourdomain.com/...' has been blocked by CORS policy

Solution: You must set SERVER_ORIGIN and DASHBOARD_ORIGIN environment variables in Coolify UI:

SERVER_ORIGIN=https://api.yourdomain.com
DASHBOARD_ORIGIN=https://app.yourdomain.com

Without these, the server doesn't know which origins to allow, causing CORS errors. These variables are required for Coolify/production deployments.

Make sure the URLs exactly match your deployed domains (including https://) and have no trailing slashes.

File uploads fail

Issue: MinIO bucket not found

Solution: The minio-init service automatically creates the bucket. Check logs with docker compose logs minio-init to ensure it ran successfully.

OAuth redirect errors

Issue: redirect_uri_mismatch

Solution:

Ensure exact URL match in OAuth provider console
No trailing slashes
Use correct protocol (http for local, https for production)
For local: http://localhost:8888/runtime/oauth/callback
For production: https://api.yourdomain.com/runtime/oauth/callback

Reset everything

To start fresh and remove all data:

docker compose down -v
docker compose up

This removes all volumes including the database and uploaded files.

Architecture

Your self-hosted InstantDB runs these services:

┌─────────────┐
│   Browser   │
└──────┬──────┘
       │
┌──────▼──────────┐
│   Dashboard     │ (Next.js)
│  localhost:3000 │
└──────┬──────────┘
       │
┌──────▼──────────┐     ┌──────────────┐
│   API Server    │────▶│  PostgreSQL  │
│  localhost:8888 │     │     :5432    │
└──────┬──────────┘     └──────────────┘
       │
┌──────▼──────────┐
│     MinIO       │ (S3 Storage)
│  localhost:9000 │
└─────────────────┘

Differences from Cloud

Self-hosted InstantDB has full feature parity with the cloud version. The main differences are:

Infrastructure: You manage the servers and Docker containers
Updates: You control when to update to new versions
Scaling: You handle scaling and backups
Storage: Files are stored in MinIO on your infrastructure
OAuth: You configure OAuth apps with your custom domain

Everything else works identically to InstantDB Cloud.

Next Steps

Storage - Learn how file uploads work
Auth - Set up authentication
Permissions - Configure access control
CLI - Use the CLI with your self-hosted instance

For CLI usage with self-hosted, set the API URL:

INSTANT_CLI_API_URI=https://api.yourdomain.com npx instant-cli login

Previous: Using LLMs
Next: Init