- TypeScript 52.6%
- Go 29.6%
- Vue 16.9%
- Shell 0.3%
- PLpgSQL 0.2%
- Other 0.2%
Taylor Anderson
55cde18496
All checks were successful
lint go / format (pull_request) Successful in 7s
test go / test (pull_request) Successful in 10s
lint frontend / lint (pull_request) Successful in 39s
test frontend / test (pull_request) Successful in 53s
type check frontend / type-check (pull_request) Successful in 54s
publish docker images / test-frontend (push) Successful in 33s
publish docker images / test-backend (push) Successful in 1m5s
publish docker images / publish (push) Successful in 30s
|
||
|---|---|---|
| .forgejo/workflows | ||
| .vscode | ||
| backend | ||
| frontend | ||
| .env.example | ||
| Caddyfile | ||
| Caddyfile.dev | ||
| cleanup_branches.sh | ||
| deploy.sh | ||
| dev.sh | ||
| docker-compose.deploy.yml | ||
| docker-compose.dev.yml | ||
| docker-compose.yml | ||
| down.sh | ||
| README.md | ||
Serpent Chat
Deployment
Prerequisites
- Docker with the Compose plugin
- Access to the Forgejo container registry at
git.serpentsoftheeast.com
First-time setup
1. Copy and fill in the environment file
cp .env.example .env
| Variable | Description |
|---|---|
REGISTRY |
Registry prefix, e.g. git.serpentsoftheeast.com/yourusername |
IMAGE_TAG |
Image tag to deploy (default: latest) |
POSTGRES_USER |
Database username |
POSTGRES_PASSWORD |
Database password |
POSTGRES_DB |
Database name (default: serpent_chat) |
JWT_SECRET |
Random secret — generate with openssl rand -hex 32 |
MINIO_ACCESS_KEY |
MinIO username |
MINIO_SECRET_KEY |
MinIO password |
MINIO_BUCKET |
MinIO bucket name (default: serpent-chat) |
MINIO_PUBLIC_URL |
Public-facing URL for file downloads, e.g. https://files.example.com |
LIVEKIT_PUBLIC_URL |
Public-facing LiveKit WebSocket URL the browser connects to, e.g. wss://yourhost:7880 |
LIVEKIT_API_KEY |
LiveKit API key |
LIVEKIT_API_SECRET |
LiveKit API secret |
VAPID_PUBLIC_KEY |
Web push public key — generate with npx web-push generate-vapid-keys |
VAPID_PRIVATE_KEY |
Web push private key |
LOKI_URL |
Loki base URL for log ingestion, e.g. https://loki.example.com |
2. Create a Forgejo personal access token
In your Forgejo account go to Settings → Applications → Generate Token and create a token with the read:package scope. You'll need it when deploy.sh prompts for your registry password.
Deploying
./deploy.sh
This will:
- Install the Loki Docker logging plugin if not already present
- Prompt for your Forgejo registry credentials
- Pull the latest images
- Start all services
Updating
Re-run ./deploy.sh at any time to pull new images and restart changed containers.
To deploy a specific image tag rather than latest, set IMAGE_TAG in .env before running.
Firewall / port forwarding
The following ports must be open and reachable from the internet:
| Port | Protocol | Purpose |
|---|---|---|
| 80 | TCP | Caddy — serves the frontend and backend API |
| 7880 | TCP | LiveKit — WebSocket signaling |
| 7881 | TCP | LiveKit — media (TCP fallback) |
| 7882 | UDP | LiveKit — RTC media (required for voice/video) |
UDP 7882 must be forwarded if the server is behind a router or firewall. Without it, voice and video will not work.
Services
| Service | Description |
|---|---|
caddy |
Reverse proxy, exposed on port 80 |
backend |
Go API server |
frontend |
Vue frontend (served by Caddy) |
livekit |
Voice/video media server, exposed on ports 7880, 7881, 7882/UDP |
db |
PostgreSQL database |
minio |
Object storage for file uploads |
valkey |
Redis-compatible cache and presence store |
API docs
Run the backend locally and visit http://localhost:8090, or see the latest main docs at:
https://serpentsoftheeast.pages.serpentsoftheeast.com/serpent-chat/