- Go 50%
- TypeScript 38%
- CSS 11%
- Nix <1%
- Shell <1%
- 2 more languages <1%
Oolong #
Tea tracking application built on AT Protocol.
Oolong is a standalone app forked from Arabica.
Development is on Tangled, and is mirrored to GitHub:
Quick Start #
# Using Nix
nix run
# Or from source
pnpm install
pnpm run build:web
go run ./cmd/oolong
Access at http://127.0.0.1:18920.
Configuration #
Command-Line Flags #
--known-dids <file>- Path to file with DIDs to backfill on startup (one per line)
Environment Variables #
Where aliases are listed, the first non-empty value wins.
OOLONG_PORT/PORT- Server port (default: 18920)OOLONG_METRICS_PORT/METRICS_PORT- Metrics port (default: 9102)OOLONG_PUBLIC_URL/PUBLIC_URL/SERVER_PUBLIC_URL- Public URL for reverse proxy deployments (e.g., https://oolong.example.com)OOLONG_DATA_DIR- Local state directory. Defaults to$XDG_DATA_HOME/oolongor~/.local/share/oolong; SQLite state is stored inoolong.db.OOLONG_PROFILE_CACHE_TTL- Profile cache duration (default: 1h)OOLONG_OAUTH_CLIENT_ID/OAUTH_CLIENT_ID- OAuth client ID (optional, uses loopback mode if not set)OOLONG_OAUTH_REDIRECT_URI/OAUTH_REDIRECT_URI- OAuth redirect URI (optional)SECURE_COOKIES- Set to true for HTTPS (default: false)LOG_LEVEL- Logging level: debug, info, warn, error (default: info)LOG_FORMAT- Log format: console, json (default: console)
Development #
Prerequisites #
- Go 1.26+
- pnpm and Node for the
web/frontend - just (optional but recommended); run helpers
in
justfile
Setup #
- Create
roles.jsonwith moderator roles. Env var:OOLONG_MODERATORS_CONFIG=roles.json - (Optional) Create
known-dids.txtwith one DID per line. Flag:-known-dids known-dids.txt
Running #
With Nix:
nix develop
just run-oolong
Without Nix, there are run helpers in justfile:
just run # dev server: debug logging, hot reload, moderator config
just test # run the Go test suite
just e2e # lightweight Playwright tests against an isolated fixture
The Solid frontend lives in web/; pnpm run build:web embeds its production
bundle in the Go binary. just run-oolong builds it before starting the server.
With OOLONG_DEV=1, rebuilding web/dist updates the served frontend without
restarting Go. Shared CSS is still bundled by Go. See
frontend development for unit and E2E commands.
Deployment #
Reverse Proxy Setup #
When deploying behind a reverse proxy (nginx, Caddy, Cloudflare Tunnel, etc.),
set the SERVER_PUBLIC_URL environment variable to your public-facing URL:
# Example with nginx reverse proxy
SERVER_PUBLIC_URL=https://oolong.example.com
SECURE_COOKIES=true
PORT=18920
# The server listens on 127.0.0.1:18920
# But OAuth callbacks use https://oolong.example.com/oauth/callback
The SERVER_PUBLIC_URL is used for OAuth client metadata and callback URLs,
ensuring the AT Protocol OAuth flow works correctly when the server is accessed
via a different URL than it's running on.
License #
MIT