moby/brewlog
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: rewrite README with docker quick start and new defaults

Browse source 
Restructure the quick start to lead with Docker, add install-from-git
as a secondary option, update the config table to reflect the new
localhost defaults and auto-enabled insecure cookies, and consolidate
the Docker section into the quick start.
This commit is contained in:
Jon Seager 2026-02-09 17:24:15 +00:00
parent 8e72961f1a
commit 36540a3b90
No known key found for this signature in database
1 changed files with 56 additions and 74 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

120
README.md
View file

@ -1,46 +1,45 @@
# B{rew}log # B{rew}log
**B{rew}log** is a self-hosted coffee logging platform for tracking roasters, roasts, brews, **B{rew}log** is a self-hosted specialty coffee logging platform optimised for filter brewing
cafes and brewing gear. It ships as a single Rust binary that serves a web UI, a REST API, and a enthusiasts. B{rew}log can be used for tracking roasters, roasts, brews, cafes and brewing gear.
CLI client.
- **Web UI** with reactive updates via [Datastar](https://data-star.dev/) and [Tailwind CSS v4](https://tailwindcss.com/) B{rew}log features an LLM-powered "Bag Scanning" feature, which enables it to automatically fill
- **REST API** for programmatic access (reads are public, writes require auth) roaster and coffee information using a photo of a bag. It also supports "check-ins" to log coffee
- **CLI client** for terminal-based workflows enjoyed in a cafe.
- **AI extraction** — scan a coffee bag label or type a description to auto-fill forms (via [OpenRouter](https://openrouter.ai/))
- **Nearby cafe search** powered by [Foursquare Places](https://docs.foursquare.com/developer/reference/place-search)
- **Cafe check-in** — log a cup of coffee at a cafe
- **Bag scanning** — photograph a coffee bag label to auto-create roaster, roast, and bag records
- **Shareable detail pages** for roasters, roasts, bags, brews, cups, cafes, and gear
- **Activity timeline** showing all logged events chronologically
- **Stats dashboard** with brewing, consumption, and geographic analytics
- **SQLite** database
- **Passkey authentication** — no passwords, WebAuthn only
## Quick Start B{rew}log ships as a single Rust binary that serves a web UI, a REST API, and a CLI client. The
application uses SQLite as a backend, and will automatically create and migrate the database on
start-up.
### Install ## Quick Start (Demo)
```bash Before you start, you'll need to sign up for [Openrouter](https://openrouter.ai) and
cargo install --git https://github.com/jnsgruk/brewlog.git [Foursquare Places](https://foursquare.com/products/places/) and get API keys for both.
Then create a `docker.env` file:
```env
# You'll need an API key from OpenRouter
BREWLOG_OPENROUTER_API_KEY=sk-or-...
# I've had good results with Gemini models, but you can try 'openrouter/free' to experiment
BREWLOG_OPENROUTER_MODEL=google/gemini-3-flash-preview
# FourSquare Places API key for location searching
BREWLOG_FOURSQUARE_API_KEY=fsq3...
``` ```
### Configure You can see the full list of configuration options [below](#configuration). Once your `.env` file
is complete, start the container using the environment file
Create a `.env` file (or export the variables). Four values are required:
```bash ```bash
BREWLOG_RP_ID="localhost" # Create a data directory to store the database
BREWLOG_RP_ORIGIN="http://localhost:3000" mkdir data
BREWLOG_OPENROUTER_API_KEY="sk-or-..." # Run the container
BREWLOG_FOURSQUARE_API_KEY="fsq3..." docker run \
``` --rm \
-p 3000 \
### Run --env-file docker.env \
-v $PWD/data:/data \
```bash ghcr.io/jnsgruk/brewlog:latest
brewlog serve
``` ```
On first start with an empty database the server prints a one-time registration URL: On first start with an empty database the server prints a one-time registration URL:
@ -54,9 +53,24 @@ This link expires in 1 hour.
Open that URL, choose a display name, and register a passkey. This creates an account and Open that URL, choose a display name, and register a passkey. This creates an account and
signs in automatically. signs in automatically.
### Install from Git
To build and install from source, you'll need a working Rust toolchain:
```bash
cargo install --locked --git https://github.com/jnsgruk/brewlog.git
```
Then create a `.env` file containing at least your OpenRouter and Foursquare API keys, and start
the server:
```bash
brewlog serve
```
### CLI Authentication ### CLI Authentication
To use the CLI or API for write operations, create a token via browser handoff: To use the CLI or API for write operations, create a token via browser hand-off:
```bash ```bash
brewlog token create --name "my-cli-token" brewlog token create --name "my-cli-token"
@ -79,12 +93,12 @@ directory is loaded automatically via [dotenvy](https://crates.io/crates/dotenvy
### Server (`brewlog serve`) ### Server (`brewlog serve`)
| Variable | Purpose | Default | | Variable | Purpose | Default |
| -------------------------- | --------------------------------------------------------------------- | --------------------- | | -------------------------- | ---------------------------------------------------------------------- | ----------------------- |
| `BREWLOG_RP_ID` | WebAuthn Relying Party ID (server domain) | **required** | | `BREWLOG_RP_ID` | WebAuthn Relying Party ID (server domain) | `localhost` |
| `BREWLOG_RP_ORIGIN` | WebAuthn Relying Party origin (full URL) | **required** | | `BREWLOG_RP_ORIGIN` | WebAuthn Relying Party origin (full URL) | `http://localhost:3000` |
| `BREWLOG_DATABASE_URL` | Database connection string | `sqlite://brewlog.db` | | `BREWLOG_DATABASE_URL` | Database connection string | `sqlite://brewlog.db` |
| `BREWLOG_BIND_ADDRESS` | Server bind address | `127.0.0.1:3000` | | `BREWLOG_BIND_ADDRESS` | Server bind address | `127.0.0.1:3000` |
| `BREWLOG_INSECURE_COOKIES` | Disable the `Secure` cookie flag (set `true` for local dev over HTTP) | `false` | | `BREWLOG_INSECURE_COOKIES` | Disable the `Secure` cookie flag (auto-enabled for localhost defaults) | `false` |
| `RUST_LOG` | Log level filter | `info` | | `RUST_LOG` | Log level filter | `info` |
| `RUST_LOG_FORMAT` | Set to `json` for structured log output | — | | `RUST_LOG_FORMAT` | Set to `json` for structured log output | — |
@ -103,38 +117,6 @@ directory is loaded automatically via [dotenvy](https://crates.io/crates/dotenvy
| `BREWLOG_OPENROUTER_MODEL` | LLM model for AI extraction | `openrouter/free` | | `BREWLOG_OPENROUTER_MODEL` | LLM model for AI extraction | `openrouter/free` |
| `BREWLOG_FOURSQUARE_API_KEY` | [Foursquare](https://foursquare.com/) Places API key for nearby cafe search | **required** | | `BREWLOG_FOURSQUARE_API_KEY` | [Foursquare](https://foursquare.com/) Places API key for nearby cafe search | **required** |
### Database
SQLite is used for storage. Migrations run automatically on server startup.
## Running with Docker
The Nix flake includes a Docker image built with `dockerTools`:
```bash
nix build .#brewlog-container
docker load < result
```
Create a `docker.env` file:
```env
BREWLOG_OPENROUTER_API_KEY=sk-or-...
BREWLOG_OPENROUTER_MODEL=google/gemini-3-flash-preview
BREWLOG_FOURSQUARE_API_KEY=fsq3...
BREWLOG_RP_ID=localhost
BREWLOG_BIND_ADDRESS=0.0.0.0:3000
BREWLOG_RP_ORIGIN=http://localhost:4000
BREWLOG_INSECURE_COOKIES=true
```
```bash
mkdir data
docker run --rm -p 4000:3000 --env-file docker.env -v $PWD/data:/data brewlog:0.1.0
```
The database is stored at `/data/brewlog.db` inside the container — mount a host directory to `/data` to persist it.
## Contributing ## Contributing
```bash ```bash