hasMore comes from the extra one; total stays only on search, the one place it's shown. Files: /api/files read the whole upload (up to 50 MB) for every range request a player makes while seeking; api/lib/serve-file.ts streams the requested bytes from disk, with an ETag and 304s, and serves avatars, attachments, covers and thumbnails too. File and thumbnail URLs carry the file's version (size and last change), so the current one is cached for a year and anything else revalidates — a same-size replacement used to stay stale, and a video's still was cached immutable forever under a URL that never changed. Feeds showed image dumps at full size: /api/thumbnails now makes a 960px preview with ffmpeg (GIFs and unreadable images go out as they are), one run per output however many cards ask at once, and ffmpeg is probed once per process instead of spawned per request. Uploads stream to disk; replacing a file writes beside it and renames over, a hard link keeping the old one for rollback instead of holding both in memory; generated stills and previews go when the file is replaced or the dump deleted, and a custom thumbnail with its dump. Outbound: fetchWithTimeout's deadline now covers the body — a server that answered at once and then dripped could hold a create open indefinitely — and pages are read to 4 MB at most; metadata is cached five minutes so the create form's preview and the post that follows share one fetch (refresh-metadata still goes to the page); proxied images sit in a 32 MB LRU. Broadcasts serialize once rather than per socket, and index.html is kept in memory until the file changes. Frontend: currentTime lived in PlayerContext, so every card re-rendered — and re-parsed its Markdown — four times a second while anything played; the playhead has its own PlayerTimeContext now. The socket context is split three ways (feed, chat via useWSChat, presence via useWSPresence), so typing, presence and chat messages leave the feeds alone. DumpCard, JournalCard and Markdown are memoized; card images use the server preview and load lazily; the feed cache is written when the page is left rather than after every pause in scrolling; the theme context value is memoized.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
gerbeur
A small invite-only social platform for sharing links and files. Users can post URLs and media (YouTube, SoundCloud, Bandcamp, images, audio, video, …), vote, comment, follow each other, build playlists, and search content. A real-time WebSocket layer handles live presence, vote counts, and notifications. The UI is localized (English and French) and ships multiple visual themes.
Stack
| Layer | Technology |
|---|---|
| Runtime | Deno 2.x |
| API | Oak (HTTP + WebSocket) |
| Database | SQLite via node:sqlite |
| Frontend | React 19 + Vite 8 |
Development
Prerequisites
- Deno 2.x
Setup
cp .env.example .env
# Edit .env: set GERBEUR_JWT_SECRET to the output of: openssl rand -hex 32
Run
deno task dev
This starts both the API server (port 8000, with file watching) and the Vite dev server (port 3000) concurrently.
Open http://localhost:3000. On first run a default admin / admin account is created — change the password immediately.
Environment variables
See .env.example for the full list with descriptions. Key variables:
| Variable | Description | Default |
|---|---|---|
GERBEUR_JWT_SECRET |
JWT signing secret — required, generate with openssl rand -hex 32 |
— |
GERBEUR_PUBLIC_URL |
Public-facing URL of the server (no trailing slash) — used for CORS, WebSocket origin, email links, OG URLs | http://localhost:GERBEUR_PORT |
GERBEUR_PORT |
Internal port Oak listens on | 8000 |
GERBEUR_LISTEN_HOST |
Network interface Oak binds to; use 127.0.0.1 to restrict to loopback |
0.0.0.0 |
GERBEUR_FRONTEND_URL |
Frontend base URL for email links and CORS; auto-added to allowed origins — the only variable needed when the frontend runs on a separate host | GERBEUR_PUBLIC_URL |
GERBEUR_ALLOWED_ORIGINS |
Comma-separated extra origins for CORS/WebSocket; PUBLIC_URL and FRONTEND_URL are always included — typically only needed in dev for the Vite server |
"" (empty) |
GERBEUR_SITE_NAME |
Site name used in the browser tab, app header, OG meta tags, and emails | gerbeur |
GERBEUR_SMTPS_URL |
SMTPS connection URL for outgoing email (smtps://user:pass@host:465) |
unset |
GERBEUR_FROM_EMAIL |
Sender address for outgoing emails — required when GERBEUR_SMTPS_URL is set |
unset |
GERBEUR_WELCOME_EMAIL_BODY |
Markdown body for the account-creation welcome email; supports {{username}} and {{site_name}} |
built-in template |
VITE_API_PROTOCOL |
API protocol baked into the frontend bundle (see Production) | http |
VITE_API_HOSTNAME |
API hostname baked into the frontend bundle | localhost |
VITE_API_PORT |
API port baked into the frontend bundle | 8000 |
Production
Docker (recommended)
The standard deployment runs API and frontend in a single container. The API server (Oak) serves the compiled frontend as static files, so both share the same origin — no VITE_API_* build args needed. Set GERBEUR_PUBLIC_URL to the externally-visible URL; it is automatically allowed for HTTP/WebSocket requests.
docker build -t gerbeur .
docker build -t gerbeur .
docker run -d \
-p 8000:8000 \
-v gerbeur-db:/app/api/sql \
-v gerbeur-uploads:/app/api/uploads \
-e GERBEUR_JWT_SECRET=$(openssl rand -hex 32) \
-e GERBEUR_PUBLIC_URL=https://example.com \
-e GERBEUR_SITE_NAME=mysite \
--name gerbeur \
gerbeur
The two volumes are required for persistence:
gerbeur-db— SQLite database (api/sql/gerbeur.db), initialized automatically on first rungerbeur-uploads— user-uploaded files (api/uploads/)
Separate API and frontend (optional)
If you need to run the API on a different host than the frontend, pass the API location as build args so it gets baked into the frontend bundle. In that setup, add the frontend origin to GERBEUR_ALLOWED_ORIGINS so cross-origin HTTP/WebSocket requests are accepted:
docker build \
--build-arg VITE_API_PROTOCOL=https \
--build-arg VITE_API_HOSTNAME=api.example.com \
--build-arg VITE_API_PORT=443 \
-t gerbeur .
Reverse proxy
Put a reverse proxy (nginx, Caddy, …) in front of the container to handle TLS. Forward everything to port 8000. Example Caddyfile:
example.com {
reverse_proxy localhost:8000
}
Project structure
api/
main.ts # Entry point — Oak application, middleware, routes
config.ts # Environment variables
middleware/ # errorMiddleware, authMiddleware
routes/ # HTTP routes + WebSocket
services/ # Business logic
providers/ # Link metadata providers (YouTube, SoundCloud, Bandcamp, …)
model/ # Row types, type guards
lib/ # JWT, pagination, slugify, upload, static helpers, …
db/
schema.sql # Database schema
init.ts # First-run database initialisation
migrate.ts # Migration runner
migrations/ # Versioned schema migrations
sql/
gerbeur.db # SQLite database (not committed)
uploads/ # User-uploaded files — avatars, dumps, thumbnails, … (not committed)
src/ # React frontend (Vite)
config/ # API base URL, validation constants, feed tabs, upload limits
pages/ # Route-level components
index/ # Feed views (hot, new, followed, journal)
components/ # Shared UI components
form/ # Reusable form controls
contexts/ # Auth, WebSocket, player, follows, theme
hooks/ # Data fetching and UI hooks
utils/ # Formatting, URL, hot-score, waveform, … helpers
locales/ # Lingui message catalogues (en, fr)
themes/ # Per-theme CSS files
model.ts # Shared frontend types
i18n.ts # Lingui runtime setup
public/ # Static assets (favicon, manifest, service worker)