HydroBrim

Home server guide

HydroBrim works fully on its own. If you'd like a copy of your log on a computer you own, you can run the small HydroBrim server at home and the app will sync with it whenever your iPhone is on your home Wi-Fi. This guide is for people comfortable with a terminal.

What you need

  • A computer that stays on at home: a Linux box, a Raspberry Pi, a NAS that runs Docker, or a Mac.
  • Either Docker (easiest) or Python 3.9 or later.
  • The computer's address on your home network, for example 192.168.1.50. Your router's device list shows it, or run hostname -I on Linux. Give it a fixed (reserved) address in your router so it doesn't change.

Keep it on your home network. The server is designed for your LAN only. Never port-forward port 8088 on your router. To sync while you're out, use a VPN back into your home network, such as WireGuard or Tailscale.

1. Get the server and make a token

On the server computer, download and unpack the server into your home folder:

cd ~
curl -LO https://smftech.co.uk/downloads/hydrobrim-server-1.0.zip
unzip hydrobrim-server-1.0.zip
cd ~/hydrobrim/server
cp .env.example .env
chmod 600 .env

Make a random access token. The app uses it to prove it's yours:

openssl rand -hex 32

Open .env in a text editor and paste the token after HYDROBRIM_API_TOKEN=. Leave DATABASE_URL empty to keep your log in a simple SQLite file at data/hydrobrim.db. Keep a copy of the token; you'll paste it into the app.

2a. Run it with Docker

From ~/hydrobrim/server:

docker compose up -d --build

That builds the server, starts it on port 8088, and restarts it automatically after a reboot. Your data lives in the data folder next to it.

  • Logs: docker compose logs -f
  • Stop: docker compose down
  • Back up now: docker compose exec -T api python -m app.backup (copies go to data/backups)

2b. Or run it without Docker

Linux with systemd (most distributions, including Raspberry Pi OS). This installs a user service that starts at boot and a nightly backup at 03:15 that keeps 14 days:

sudo loginctl enable-linger $USER
~/hydrobrim/server/scripts/install-service.sh
  • Status: systemctl --user status hydrobrim
  • Logs: journalctl --user -u hydrobrim -f

Any other system, including a Mac, to try it out:

cd ~/hydrobrim/server
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
set -a; . ./.env; set +a
.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8088 --workers 1

On a Mac, allow incoming connections for Python if the firewall asks.

3. Check it's running

From another computer on the same network, replacing the address with your server's:

curl http://192.168.1.50:8088/health

The reply includes "app":"hydrobrim". If it times out, check the server is running and that its firewall allows port 8088 (for example sudo ufw allow from 192.168.0.0/16 to any port 8088).

4. Connect the app

  1. In HydroBrim, open Settings and turn on Sync with a home server.
  2. Enter the server URL, for example http://192.168.1.50:8088.
  3. Paste the token from step 1 and tap Save token.
  4. Tap Test connection. When iOS asks to find devices on your local network, tap Allow.

A status pill appears at the top of the Today screen. Synced means you're up to date, and Away just means your iPhone isn't on your home network. Drinks you log while away are kept on the phone and sync next time you're home. Drinks logged before you turned sync on are sent too.

Troubleshooting

The app always says Away

Check the iPhone is on the same Wi-Fi as the server and that /health works from another device. Then go to iOS Settings › Privacy & Security › Local Network and make sure HydroBrim is on.

"Server rejected the API token"

The token in the app doesn't match HYDROBRIM_API_TOKEN in .env. Paste it again. If you change the token in .env, restart the server.

Restoring a backup

Backups are in data/backups. For SQLite, stop the server, copy the newest .db backup over data/hydrobrim.db, then start it again. MariaDB backups are gzipped SQL dumps: zcat FILE.sql.gz | mariadb -u hydrobrim -p hydrobrim. In the app, use Sync details › Re-pull everything.

Using MariaDB or PostgreSQL

Set DATABASE_URL in .env, for example mysql+pymysql://hydrobrim:PASSWORD@127.0.0.1:3306/hydrobrim?charset=utf8mb4. The tables are created on first start. For PostgreSQL, also install requirements-postgres.txt.

Still stuck? Email hello@smftech.co.uk with what /health returns and the last few lines of the server log.