Prerequisites

• Docker & Docker Compose
• Node.js 20+ (for development)
• pnpm 8+ (for development)

Production deploy

The whole platform runs from a single docker-compose stack. Copy the env file, edit it, then bring the services up.

# 1. Configure environment
cp docker/.env.example docker/.env
# edit docker/.env with your settings

# 2. Start all services
cd docker
docker-compose up -d

Portainer

Deploying through Portainer instead of the CLI? Add a new stack, paste the contents of docker/docker-compose.yml, and fill in the env file values on the stack form. The livekit service uses network_mode: host — on Portainer this works as-is on Docker Desktop and Linux, but if you're deploying to a remote endpoint make sure the UDP ports (50000–60000 by default) are open on that machine for WebRTC.

Backups

Two volumes hold your community's actual data:

• postgres — all messages, users, roles & server config
• minio — attachments, emoji packs, stickers, profile media, archived messages

A nightly docker exec pg_dump plus a sync of the MinIO data volume covers both. Message export (JSON/CSV) in the app is a good second net for individual servers.

Docker services

The stack brings up these containers. This is what you'll see in Portainer once deployed.

Only the api port (3040) needs to be exposed to your users — put a reverse proxy (Caddy/Nginx/Traefik) with TLS in front of it. Everything else stays on the internal Docker network.

Relay networking (AuraBranch)

When deploying relay servers on the same LAN as the master, the relay must report a reachable IP address — not localhost. The master's API container proxies LiveKit WebSocket signaling through its own SSL, so the relay's livekit_url must be reachable from inside the Docker container.

# Example: relay on the same LAN as the master
LIVEKIT_PUBLIC_URL=ws://192.168.1.50:7880

Development

# Install dependencies
pnpm install

pnpm dev        # API dev server (port 3000)
pnpm dev:web    # web client dev server (port 5174)
pnpm dev:all    # both at once

pnpm build      # build all packages (shared -> web -> api)
pnpm typecheck  # type check
pnpm lint       # lint

Project structure

sgChat-Server/
├── packages/
│   ├── shared/   # types, validators, permissions, constants
│   ├── api/      # Fastify backend + Socket.IO
│   │   └── src/  # routes, socket, services, lib, middleware,
│   │             # migrations, plugins
│   ├── web/      # React 19 frontend (served by API container)
│   └── relay/    # standalone relay server CLI (AuraBranch)
│       └── src/  # auto-pairing, crypto, ws proxy, heartbeat,
│                 # voice auth, event relay
└── docker/
    ├── docker-compose.yml
    ├── Dockerfile.api
    ├── Dockerfile.postgres
    ├── init.sql
    └── livekit.yaml

AuraLeaf client

The desktop client lives in its own repo: DemonFiend/sgChat-Client. It's a separate codebase (Electron + React + Mantine + Vite) that talks to any AuraTree.

What the client adds over the web client

• Per-app audio capture on Windows (stream one app's audio, not the whole system)
• System tray, global shortcuts (push-to-talk, mute, deafen), auto-launch with Windows
• Multi-server switching, native notifications with mention badges
• AI noise suppression in the client: RNNoise, NSNet2, DeepFilterNet

Current status

• Windows alpha — public alpha releases coming
• Ubuntu (LTS) .AppImage and Android APK — not yet published
• Auto-update is wired (electron-updater) but not connected to a release feed yet
• Per-app audio capture is Windows-only; other platforms fall back to system audio

Bug reports and feature requests go to the client's issue tracker.

Licensing

AuraLeaf uses a dual-license model:

• PolyForm Noncommercial 1.0.0 — free for personal, hobby, educational, research, and other non-commercial use. Read the source, fork it, modify it, contribute back.
• Commercial license — required to sell it, offer it as a paid service/hosting, bundle it into a product you sell, or otherwise use it in a for-profit business. Open a GitHub issue tagged commercial-license to discuss.

Known limitations

Screen-share audio capture (browser)

The getDisplayMedia() API has inherent limits on audio capture:

Browsers don't expose per-application audio routing for privacy/security. The Electron desktop client (AuraLeaf) provides better audio capture.