Self-Hosting — Run Synap on Your Own Server

Synap is designed for full data sovereignty. Self-hosting means running the exact same codebase as managed pods on infrastructure you control — your VPS, your home server, your rules.

What self-hosting means

A self-hosted Synap pod is identical to a managed one. The same backend, the same database schema, the same AI pipeline, the same API. The only difference is who operates the server. When you self-host, you handle provisioning, backups, and upgrades. When you use a managed pod, Synap handles that for you. Your data format, your features, and your access patterns are the same either way.

Requirements

• Linux VPS — Ubuntu 22.04+ or Debian 12+ recommended. 4GB RAM minimum, 8GB recommended for comfortable operation with AI workloads.
• Docker + Docker Compose — The entire stack runs in containers. Docker Compose v2 or later.
• Domain name — For TLS certificates and clean API URLs. Can be a subdomain (e.g., pod.yourdomain.com).
• Storage — At least 20GB for the base installation. Scale based on how much you store — files, documents, and vector embeddings grow over time.

The stack

A self-hosted Synap pod consists of these services, all orchestrated by Docker Compose:

• PostgreSQL + pgvector — The primary database. Stores entities, properties (JSONB), views, channels, events, and vector embeddings for semantic search.
• Typesense — Full-text search engine. Provides instant, typo-tolerant search across all your entities.
• MinIO — S3-compatible object storage for file uploads, document attachments, and any binary content.
• Synap Backend — The Hono + tRPC API server. Handles all data operations, authentication, job processing (via pg-boss), and real-time updates (via Socket.IO).
• Caddy — Reverse proxy with automatic TLS. Handles HTTPS certificates from Let's Encrypt, rate limiting, and request routing.

Getting started

The setup process is straightforward:

# Clone the repository
git clone https://github.com/synap-live/synap-backend.git
cd synap-backend

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your domain, database credentials, and API keys

# Start all services
docker compose up -d

The .env file controls everything: your domain name, database password, JWT secrets, AI model provider keys (OpenRouter, OpenAI, Anthropic), and optional integrations. Sensible defaults are provided for development, but you should customize secrets for production.

Data location and backups

All persistent data lives in Docker volumes mapped to your host filesystem:

• PostgreSQL — The database data directory. This is your most critical data. Back it up with pg_dump on a schedule (daily recommended).
• MinIO — Object storage bucket. Back it up with mc mirror (MinIO client) to a secondary location or S3-compatible remote.
• Typesense — Search index data. Can be rebuilt from PostgreSQL if lost, but backing it up avoids reindexing time.

A minimal backup strategy: daily pg_dump to a remote location, weekly mc mirror for files. The event chain ensures you can reconstruct the full history of your data from the database alone.

Upgrades

Upgrading a self-hosted pod is a pull-and-restart process:

# Pull latest images
docker compose pull

# Restart services (zero-downtime for most updates)
docker compose up -d

# Run database migrations if needed
docker compose exec backend pnpm drizzle-kit migrate

Synap uses Drizzle ORM for database migrations. New versions may include migration files that alter the schema. Always check the release notes before upgrading to understand what changed.

Self-host vs. managed

Self-host when you want full control over your infrastructure, need to comply with data residency regulations, want to run on air-gapped networks, or simply prefer owning your stack end-to-end.

Use managed when you want zero operational overhead. Managed pods are provisioned in EU (Falkenstein, Germany) and US (Ashburn, Virginia) Hetzner regions. Automatic backups, automatic upgrades, monitoring, and support are included. You get the same data sovereignty guarantees — your pod is an isolated instance — without managing servers.

Related guides