Self-Hosting

The Flock server is a single Node.js process. You can run it with npx, Docker, or embed it in an existing Node server. This guide covers the recommended Docker Compose setup for production.

Quickstart: npx

For local development or quick experiments:

npx @xevrion/flock-server

The server starts on port 8787 with no Redis (in-memory only, no TTL eviction). Fine for a single dev machine.

Production: Docker Compose

For production you'll want Redis alongside the server. Redis enables presence TTL eviction (users are cleaned up when they close the tab without a clean disconnect) and horizontal scaling across multiple server instances.

Create a docker-compose.yml:

version: "3.9"
 
services:
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: redis-server --notify-keyspace-events Ex
    volumes:
      - redis_data:/data
 
  flock:
    image: ghcr.io/xevrion/flock-server:latest
    restart: unless-stopped
    ports:
      - "8787:8787"
    environment:
      FLOCK_PORT: "8787"
      FLOCK_REDIS_URL: "redis://redis:6379"
      FLOCK_PRESENCE_TTL_SECONDS: "30"
      FLOCK_LOG_LEVEL: "info"
    depends_on:
      - redis
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:8787/health"]
      interval: 10s
      timeout: 5s
      retries: 3
 
volumes:
  redis_data:

Start it:

docker compose up -d

Check it's running:

curl http://localhost:8787/health
# {"status":"ok"}

Building the image yourself

If you want to build from source rather than using the published image:

git clone https://github.com/xevrion/flock
docker build -f packages/server/Dockerfile -t flock-server .
docker run -p 8787:8787 flock-server

Environment variable reference

API key authentication

If you set FLOCK_API_KEYS, the server rejects any client that doesn't send a matching key. Add the key to your client:

<FlockProvider
  serverUrl="wss://your-server.com"
  apiKey="your-secret-key"
  ...
>

Keep the key out of version control. In Vercel or similar platforms, add it as an environment variable and reference it in your Next.js app:

<FlockProvider
  apiKey={process.env.NEXT_PUBLIC_FLOCK_API_KEY}
  ...
>

Redis keyspace notifications

The --notify-keyspace-events Ex flag is required for presence TTL eviction to work. Without it, Redis won't publish expired-key events and the server won't know when a user's heartbeat has expired.

If you're using a managed Redis service (Upstash, Redis Cloud, etc.), enable keyspace notifications in the provider's dashboard. Upstash exposes this as a toggle. Redis Cloud has it in the database config.

Reverse proxy / TLS

For production, put the server behind nginx or Caddy to handle TLS termination. The server speaks plain WebSocket and HTTP; your reverse proxy upgrades ws:// to wss:// for the client.

Minimal nginx snippet for a WebSocket upstream:

location /flock/ {
    proxy_pass http://localhost:8787/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400;
}

Next steps

• Scaling guide — how to run multiple instances behind a load balancer
• Configuration reference — full env var docs