Tea journaling on ATProto (alpha) forked from arabica.social/arabica
Files
README.md

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/oolong or ~/.local/share/oolong; SQLite state is stored in oolong.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 #

  1. Create roles.json with moderator roles. Env var: OOLONG_MODERATORS_CONFIG=roles.json
  2. (Optional) Create known-dids.txt with 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