Self-hosting Skycord: a complete guide

Skycord's server software is open source and designed to be self-hosted. This guide covers everything from a single-server Docker deployment to a production Kubernetes cluster. We assume basic Linux and Docker familiarity.

Prerequisites

Before you start, you'll need:

• A server with at least 2 CPU cores and 4 GB RAM (4 cores / 8 GB recommended for 1,000+ concurrent users)
• Docker 24+ and Docker Compose v2
• A domain name with DNS control
• An SMTP provider for transactional email (we recommend Resend)
• An S3-compatible storage bucket for file uploads (Cloudflare R2 works well and has zero egress fees)

Quick start with Docker Compose

Clone the repository and copy the example environment file. The compose file includes the Skycord server, a Postgres database, Redis for session storage and pub/sub, and a Caddy reverse proxy that handles TLS automatically.

Set your domain, SMTP credentials, and S3 config in the .env file. Run `docker compose up -d`. Caddy will request a Let's Encrypt certificate on first startup. Your instance will be available at your domain within a minute or two.

The first user to register on a fresh instance is automatically granted admin privileges. Use this account to configure your server name, branding, and federation settings.

Kubernetes deployment

For production deployments expecting significant load, we provide Helm charts. The chart deploys the Skycord server as a Deployment with a HorizontalPodAutoscaler, a separate WebSocket server Deployment (which has different scaling characteristics), Postgres via CloudNativePG, and Redis via the Bitnami chart.

The WebSocket server maintains persistent connections with clients. Scaling it requires sticky sessions at the load balancer level. We provide an example ingress configuration for nginx-ingress with session affinity enabled.

We recommend starting with 2 replicas of each component and monitoring with the built-in Prometheus metrics endpoint before scaling further.

Federation

Skycord supports optional federation between instances. A member on your instance can join public servers on other federated Skycord instances without creating a second account. Federation uses a signed HTTP protocol similar in spirit to ActivityPub but optimized for the real-time message delivery requirements of chat.

Federation is opt-in and disabled by default. You can enable it in the admin panel and choose whether to federate with all instances, a whitelist, or only specific instances you've manually peered with.

E2E encryption works across federated instances. Messages between users on different instances are encrypted end-to-end using the same Signal Protocol implementation. The remote server sees the same encrypted blobs as the local server.

Keeping up to date

We release updates on a roughly monthly cadence. Breaking changes are announced in the Changelog with at least two weeks' notice. We maintain a migration guide for each major version bump.

The Docker image supports zero-downtime rolling updates when deployed with multiple replicas. Database migrations run automatically on startup and are designed to be backward-compatible with the previous version so you can roll back if needed.