arabica.social
Coffee journaling on ATProto (alpha)
alpha.arabica.social
coffee
pdewey.com
1# Arabica
2
3Coffee brew tracking application build on ATProto
4
5Development is on GitHub, and is mirrored to Tangled:
6
7- [Tangled](https://tangled.org/arabica.social/arabica)
8- [GitHub](https://github.com/arabica-social/arabica)
9
10GitHub is currently the primary repo, but that may change in the future.
11
12## Features
13
14- Track coffee brews with detailed parameters
15- Store data in your AT Protocol Personal Data Server
16- Community feed of recent brews from registered users (polling or real-time firehose)
17- Manage beans, roasters, grinders, and brewers
18- Export brew data as JSON
19- Mobile-friendly PWA design
20
21## Tech Stack
22
23- Backend: Go with stdlib HTTP router
24- Storage: AT Protocol Personal Data Servers + BoltDB for local cache
25- Templates: Templ (type-safe Go templates)
26- Frontend: HTMX + Alpine.js + Tailwind CSS
27
28## Quick Start
29
30```bash
31# Using Nix
32nix run
33
34# Or with Go
35go run cmd/server/main.go
36```
37
38Access at http://localhost:18910
39
40## Configuration
41
42### Command-Line Flags
43
44- `--known-dids <file>` - Path to file with DIDs to backfill on startup (one per line)
45
46### Environment Variables
47
48- `PORT` - Server port (default: 18910)
49- `SERVER_PUBLIC_URL` - Public URL for reverse proxy deployments (e.g., https://arabica.example.com)
50- `ARABICA_DB_PATH` - BoltDB path (default: ~/.local/share/arabica/arabica.db)
51- `ARABICA_FEED_INDEX_PATH` - Firehose index BoltDB path (default: ~/.local/share/arabica/feed-index.db)
52- `ARABICA_PROFILE_CACHE_TTL` - Profile cache duration (default: 1h)
53- `OAUTH_CLIENT_ID` - OAuth client ID (optional, uses localhost mode if not set)
54- `OAUTH_REDIRECT_URI` - OAuth redirect URI (optional)
55- `SECURE_COOKIES` - Set to true for HTTPS (default: false)
56- `LOG_LEVEL` - Logging level: debug, info, warn, error (default: info)
57- `LOG_FORMAT` - Log format: console, json (default: console)
58
59## Development
60
61With Nix:
62
63```bash
64# Enter development environment
65nix develop
66
67# Run server
68go run cmd/server/main.go
69
70# Run tests
71go test ./...
72
73# Build
74go build -o arabica cmd/server/main.go
75```
76
77Without Nix, you'll need to have Go, Templ, and tailwindcss installed (just is optional but recommended).
78
79```sh
80# Generate CSS files
81tailwindcss -i static/css/app.css -o static/css/output.css --minify
82# Compile Templ
83templ generate
84# Run the appview
85go run cmd/server/main.go
86
87# with just
88just run
89```
90
91---
92
93## Deployment
94
95### Reverse Proxy Setup
96
97When deploying behind a reverse proxy (nginx, Caddy, Cloudflare Tunnel, etc.), set the `SERVER_PUBLIC_URL` environment variable to your public-facing URL:
98
99```bash
100# Example with nginx reverse proxy
101SERVER_PUBLIC_URL=https://arabica.example.com
102SECURE_COOKIES=true
103PORT=18910
104
105# The server listens on localhost:18910
106# But OAuth callbacks use https://arabica.example.com/oauth/callback
107```
108
109The `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.
110
111### NixOS Deployment
112
113See docs/nix-install.md for NixOS deployment instructions.
114
115## License
116
117MIT