Running homie

1. Which door you are using
2. Watching movies & TV
3. Adding to the library
4. Syncing your files
5. Getting in from outside
6. Checking it is healthy
7. If the tunnel “works” but nothing connects
8. What does not work yet
9. Turning it off and on
10. Updating without breaking it
11. Quick reference

Everything makes more sense once you know there are two ways in, and that which one you are using decides what you can reach.

Roommates use the first door and never need to install anything. The second exists so the owner can reach the machine from outside the house without opening a single port on the router. Architecture §02 explains why it is built this way.

From the house

Sign in with the account you were given. Everyone gets their own login, so watch history, resume points and preferences stay yours.

On a TV, phone or tablet

The browser works, but the apps are better. Install one, then add the server manually when it asks:

• Android TV / Fire TV — the official Jellyfin app, the best of the lot
• iPhone / iPad — Swiftfin
• Desktop — Jellyfin Media Player, or just the browser

What to expect while watching

The server converts video on the fly when your device cannot play a file directly. That conversion runs on a dedicated video chip rather than the processor, which is roughly three times faster and leaves the machine responsive for everyone else.

It is not unlimited — this is a laptop. Two people converting at once is fine; four is pushing it. If playback stutters, lower the quality in the player’s gear menu; that often lets your device play the file directly instead, which uses almost no server power at all.

Jellyfin works out what a file is almost entirely from its name and folder. Get the name right and the poster, cast and synopsis appear on their own within a minute. Get it wrong and you get a bare filename with no artwork — and no amount of rescanning fixes it.

The naming rules

/mnt/t7/Movies/Title (Year)/Title (Year).mp4
/mnt/t7/TV/Title (Year)/Season 02/Title (Year) - S02E01 - Episode Name.mp4

Season and episode numbers are two digits. Gaps are fine — a missing episode 3 stays missing rather than renumbering everything after it.

The usual way — let it file itself

Add a torrent in qBittorrent, set its category to tv or movies, and that is the whole job. When it finishes, the file is renamed to the pattern above, moved into the library, and removed from the download list.

The category is the only field that matters. Everything else is already configured.

bin/qbt-why big buck bunny
bin/qbt-why --as movies sintel     # for a download added without a category

The manual way

For anything that did not arrive as a torrent — a file from a friend’s drive, or one copied over SFTP — a helper script does the naming so it cannot be got wrong by hand:

addmedia movie ~/inbox/somefilm.mp4 "Some Film" 1954
addmedia show  ~/inbox/ep1.mp4 "Some Show" 1961 2 1 "Episode Name"

It builds the folder structure, moves the file into place, and nudges Jellyfin to scan. It also refuses to run at all if the external drive is unplugged, rather than filing your video somewhere that will vanish when the drive comes back.

Getting files onto the server by hand

Any file transfer app works — Cyberduck, FileZilla, or the scp command.

Syncthing keeps a folder identical across your devices. Change a file on your laptop and the server has it moments later — no cloud service, no subscription, and the files never touch anyone else’s computer.

Adding another device

1. Install Syncthing on the new device and open its web page.

2. Find Actions → Show ID and copy the long device ID.

3. On homie’s Syncthing, choose Add Remote Device, paste that ID, then open the Sharing tab and tick school-work.

   Skipping that tick is the single most common mistake — the device pairs but nothing ever syncs.

4. Back on the new device, accept both prompts: one to trust homie, one to accept the folder. Choose where the folder should live locally.

Pairing is mutual — both sides must agree. That is why the sync port can sit open on the house network safely: an unknown device can knock, but nothing transfers until someone approves it by ID.

Tailscale builds a small private network between approved devices. They can talk to each other from anywhere — a café, campus, another country — as if they were on the same WiFi. Nothing is exposed to the public internet and no ports are forwarded on the router.

Once a device is on it, these work from anywhere:

Those carry genuine certificates issued to the machine’s name and renewed automatically, so browsers show a normal padlock with nothing to click past.

These documentation pages

The docs are the one exception — they are served on 127.0.0.1 only, so they need an SSH tunnel rather than a tailnet address:

ssh -L 8446:localhost:8446 homie-lan
# then open http://localhost:8446

Why it is bound that way. In a terminal, bin/homie-docs renders any page as text instead.

One command answers “is anything wrong?”. It only reads — it cannot change or break anything, so run it whenever you are curious.

~/homeserver/bin/homie-check

Thirty-nine assertions, grouped. What it covers:

The live-transcode row is the useful one: start something playing, run the check again, and it tells you whether the conversion actually landed on the video chip. A setting being switched on does not guarantee it is being used.

The automation stack has its own check

~/homeserver/bin/homie-automation-check

It checks n8n and ollama, then reads the workflow state database directly rather than asking n8n — so “n8n is dead” is not reported by a dead n8n. It emails on failure once SMTP is configured.

A workflow that has never run reports as information, not as a failure — an absence is not a fault when the thing was never built. Once a workflow has run, it gets a deadline: roughly 1.5× its interval, so one missed run is tolerated and two in a row are not.

What runs on a schedule

Both are Persistent=true, so a run missed while the machine was off happens on the next boot rather than being silently skipped. Confirm with systemctl list-timers 'homie-*'.

When something is broken — where the logs are

Health checks tell you that something is wrong. Logs tell you why.

This cost three wrong diagnoses across three sessions, so the test that actually settles it is written down here.

tailscale ping is not ping. A tailscale ping is answered by the Tailscale daemon itself, in userspace, before the packet ever reaches the operating system or the tailnet’s own packet filter. It proves the two machines have negotiated a WireGuard session — and nothing more. Ordinary ping has to survive the whole path, so it is the honest test:

tailscale ping stevens-macbook-air   # succeeds even when everything real is broken
ping -c3 100.64.0.20              # this is the one that tells you the truth

Stated plainly, so nobody wastes an afternoon on a known gap. This is the one place in the documentation where these are listed; the other pages link here.

homie is a laptop that runs all the time. Mostly you never touch this — services restart themselves after a power cut, and the whole stack comes back when the machine boots. You need this section for three situations: the machine has to move, one service is misbehaving, or you changed something and need it to take effect.

Restarting one service

Almost always the right move — it leaves everything else running. From ~/homeserver:

docker compose restart jellyfin     # or syncthing, caddy, n8n, ollama
sleep 10 && bin/homie-check

docker compose up -d --force-recreate gluetun
docker compose up -d --force-recreate qbittorrent

Restarting everything

1. cd ~/homeserver

2. docker compose down — stops all seven containers. Data, settings and library are untouched; only the running containers go away.

3. docker compose up -d — brings them back, in dependency order.

4. bin/homie-check — expect every check to pass.

Because down removes the containers and up creates fresh ones, the VPN two-step is handled automatically here. That is why a full cycle is sometimes simpler than fixing one service.

Shutting the machine down

1. If anything is downloading, pause it in qBittorrent and let the current pieces finish writing.

2. cd ~/homeserver && docker compose down — stops services cleanly rather than having them killed mid-write by the shutdown.

3. sudo shutdown -h now — needs your password.

4. Wait until the power light is off before moving or unplugging it. If the T7 is coming too, unplug it only after the machine is fully off.

Starting it back up

1. Plug the T7 in first, then power on the laptop. This order matters: the media containers deliberately refuse to start if the drive is missing, so a missing drive is a loud failure instead of an empty library.

2. Everything starts by itself — Docker restores all seven containers. Nothing to type.

3. bin/homie-check to confirm, once you can reach it.

Every service is pinned to an exact version on purpose. Nothing updates itself and nothing changes underneath you, which means an update is always something you chose, on a day you chose it, and can undo.

Updating one service

1. Check it is healthy first. Never start an update from a broken state — you will not know afterwards which problem you were looking at.

   bin/homie-check

2. Pick a real version. Look up the image’s releases and read what changed. A version number, never latest.

3. Edit one line. In docker-compose.yml, change that service’s image: tag. Leave the comment recording the old digest — that is your way back.

4. Apply it to that service only.

   docker compose up -d jellyfin

5. Verify twice. Run the health check, then actually use the thing — play a video, open the page. A passing check is not the same as a working app.

   bin/homie-check

6. Commit it, saying what moved from what to what. This is what makes rolling back possible.

   git add -A && git commit

Undoing an update

Because the version lives in a committed file, rolling back is editing that line back and re-running docker compose up -d. Or, if the commit contained nothing else, git revert it and apply. Config and data are separate from the container, so downgrading does not lose anything — with one caveat.

Updating the VPN container

Same as above, plus the two-step from §08 — a rebuilt gluetun always needs qBittorrent rebuilt after it:

docker compose up -d --force-recreate gluetun
docker compose up -d --force-recreate qbittorrent
bin/homie-check

The line to look for reads qBittorrent egress is the VPN. If it names the home address instead, stop and fix it before downloading anything.

Updating n8n

Same procedure, with one thing to check first: never change N8N_ENCRYPTION_KEY. Every stored credential is encrypted with it, and a new key turns them into unrecoverable ciphertext rather than a re-login. n8n also occasionally changes defaults between versions and warns at startup; the compose file pins those explicitly, so read its startup log after an upgrade.

Updating Ubuntu itself

sudo apt update && sudo apt upgrade

Separate from the services, which carry their own dependencies inside their containers. If it installs a new kernel it will want a reboot — use the shutdown steps in §08, and remember everything comes back on its own afterwards.

Addresses

The full reachability table, including what the public internet can reach (nothing).

Where things live

Commands

Run these from ~/homeserver. Anything taking arguments shows them; the rest take none.

Secrets, and what git never sees

There is no password manager here — there is a placement rule. Anything secret lives in a file git is told to ignore, and the repo carries a template naming what is needed without containing it.

Passwords are stored by each service rather than by us: Jellyfin keeps its own in its database, qBittorrent keeps a hash, Syncthing hashes its web login. Nothing here stores a plaintext password except .env, which holds the qBittorrent login because the filing script has to log in as you.