Run a Bothy hub

A hub is a computer that stays on and shares Bothy with everyone on its Wi-Fi: the library, first aid, AI answers, maps, games and a local chat, in any phone's browser, with no app and no internet. Phones with the app can also fill up from it. If you can spare a few gigabytes and a computer that can stay switched on, you can run one for your household, your street or your village hall.

How long it takes: about 15 minutes of your time, plus the download (3 to 13 GB, so roughly 10 minutes to a few hours depending on your connection). After that the hub needs no internet at all.

What you need

A computer that can stay on. Any of these works:
- a Raspberry Pi 4 or 5 with at least 4 GB of memory, running 64-bit Raspberry Pi OS
- an old laptop or desktop (Windows 10 or 11, macOS, or Linux), 64-bit, with at least 4 GB of memory
- a mini PC (such as an Intel N100) or a home server or NAS that runs Docker (Synology, Unraid, TrueNAS, CasaOS)
Free space for the content you choose (below), plus a little room to spare.
A Wi-Fi network that people can join: your router, or a cheap travel router next to the hub.
Internet once, for the download.

Choose how much to keep

Choice	Size	What's in it
small	2.6 GB	All 440,000 articles, guides and answers, search by meaning, first aid, 23 games, a world map. No pictures.
standard (recommended)	7.6 GB	Everything in small, plus pictures for Wikipedia, the survival guides and Appropedia, AI answers, and the detailed UK map.
everything	13.2 GB	Everything in standard, plus all the wikiHow and iFixit photos, and compact indexes for phones that copy from the hub.

AI answers need about 3 GB of free memory and a reasonably fast processor. They work on a mini PC or laptop; on a Raspberry Pi they're slow, so you may want to leave them out (see options). Everything else runs well on a Pi.

Step 1: Install Docker

Docker runs the hub in a sealed box, the same way on every computer, and keeps it running. It's free for personal use.

Windows 10 or 11

Download Docker Desktop for Windows and run the installer. Keep the default "Use WSL 2" option.
Restart the computer when it asks, then open Docker Desktop and wait until it says the engine is running. You don't need to sign in.
In Docker Desktop's Settings → General, turn on Start Docker Desktop when you sign in to your computer.
Open PowerShell (Start menu → type PowerShell) for the next step.

Mac

Download Docker Desktop for Mac: choose Apple silicon (M1 and later) or Intel to match your Mac (Apple menu → About This Mac).
Open the downloaded file, drag Docker to Applications, open it and wait until it says the engine is running. You don't need to sign in.
In Docker Desktop's Settings → General, turn on Start Docker Desktop when you sign in to your computer.
Open Terminal (Applications → Utilities) for the next step.

Linux and Raspberry Pi

On a Raspberry Pi, make sure you're running the 64-bit Raspberry Pi OS (uname -m should print aarch64).

Install Docker with its official script, and let your user run it:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Log out and back in (or reboot), then check it works: docker run --rm hello-world

Docker starts by itself when the computer boots.

NAS or home server (Synology, Unraid, TrueNAS, CasaOS)

Use your system's container app (Synology: Container Manager) and create a container from the image andykcheng/bothy with:

ports 8080 → 8080 and 8443 → 8443
a volume or folder mounted at /data, on a disk with enough space
restart policy unless stopped (or "always")
optional environment variable BOTHY_PRESET = small, standard or everything

Then skip to step 3.

Step 2: Start the hub

Copy this into PowerShell or Terminal and press Enter. It's the same on every system:

docker run -d --name bothy --restart unless-stopped -p 8080:8080 -p 8443:8443 -v bothy-data:/data -e BOTHY_PRESET=standard andykcheng/bothy

Change standard to small or everything if you prefer. Docker picks the right version for your computer (Intel/AMD or ARM) by itself.

If the command fails, or you want to change something in it: remove the container first, then run the corrected command. Docker keeps a container called bothy even when it fails to start, and a second docker run with the same name stops with "The container name "/bothy" is already in use". Removing it is safe: the library stays in the bothy-data volume.

docker rm -f bothy

On the first start the hub downloads its library into the bothy-data volume. Watch it with:

docker logs -f bothy

You'll see the progress, and at the end "Bothy hub is running" with a list of what it holds. Press Ctrl+C to stop watching; the hub keeps running. If the download is interrupted, it carries on from where it stopped next time the hub starts.

Step 3: Open it

On the hub computer itself: http://localhost:8080
On a phone or another computer on the same Wi-Fi: http://the hub's address:8080

To find the hub's address:

Windows: in PowerShell, run ipconfig and look for "IPv4 Address" under your Wi-Fi or Ethernet adapter, e.g. 192.168.1.23.
Mac: System Settings → Wi-Fi (or Network) → Details → IP address.
Linux and Raspberry Pi: run hostname -I and take the first address.

So a phone would open something like http://192.168.1.23:8080. If the computer asks whether to allow Docker to accept incoming connections, allow it on private networks.

Tip: in your router's settings, give the hub a fixed (reserved) address, so the link never changes. Then print it on a card or turn it into a QR code and stick it on the wall.

Step 4: Make sure it's ready

A hub you've never tested is a hub you can't count on. Work through this once:

Check every file. Run docker exec bothy bothy-hub check. It checks the download is complete and ends with "Ready." Add --full to re-check every file's fingerprint (slower).
Test without the internet. Unplug the internet cable from your router (or switch off its mobile data), keep the Wi-Fi on, and on a phone open the hub, search for "how to purify water", open a first aid card, and send a message in the chat. Everything should work.
Test a restart. Restart the hub computer and check the hub comes back by itself. On Windows and Mac, Docker Desktop must start when you sign in (step 1), and the computer must sign in by itself or stay signed in.
Stop it sleeping. Set the computer never to sleep when plugged in (Windows: Settings → System → Power; Mac: System Settings → Energy; a laptop can keep running with its lid closed if you set "When I close the lid: Do nothing").
Plan for a power cut. The hub and the Wi-Fi router both need power. A laptop has its own battery; a Raspberry Pi or a small router runs for hours from a USB power bank; a small UPS keeps a router and mini PC going. Test it: unplug the mains and see how long it lasts.
Tell people. Put the address (or a QR code) where people will find it: the fridge, the noticeboard, the family group chat. In an emergency nobody will remember a number.

Keeping it up to date

Content changes now and then. To fetch whatever's new or changed (only the differences are downloaded):

docker exec -it bothy bothy-hub get

To switch to a bigger or smaller choice later: docker exec -it bothy bothy-hub get --preset everything

To update the hub program itself (your downloaded library is kept):

docker pull andykcheng/bothy
docker rm -f bothy
docker run -d --name bothy --restart unless-stopped -p 8080:8080 -p 8443:8443 -v bothy-data:/data andykcheng/bothy

Options

Add any of these to the docker run command, before the image name. To change the options of a hub that already exists, run docker rm -f bothy first, then the new docker run command (the downloaded library is kept).

Option	What it does
`-e BOTHY_PRESET=small`	small, standard or everything (used on the first start)
`-e BOTHY_SKIP=llm`	leave things out, separated by commas: `llm` (AI answers), `map:uk`, `col:ifixit:images`…
`-e BOTHY_ADD=map:uk`	add things to a smaller choice
`-p 8090:8080`	use another port if 8080 is taken (then open `:8090`)
`-p 8444:8444 -e BOTHY_HTTPS_PORT=8444`	use another secure port (instead of `-p 8443:8443`) if 8443 is taken; keep the three numbers the same
`-v /path/on/disk:/data`	keep the library in a folder you choose, e.g. on a bigger disk, instead of the `bothy-data` volume

With Docker Compose, save this as compose.yaml and run docker compose up -d:

services:
  bothy:
    image: andykcheng/bothy
    restart: unless-stopped
    ports: ["8080:8080", "8443:8443"]
    volumes: ["bothy-data:/data"]
    environment:
      BOTHY_PRESET: standard
volumes:
  bothy-data:

If something goes wrong

Phones can't open the hub

Check the phone is on the same Wi-Fi as the hub, not a guest network (guest networks usually stop devices seeing each other) and not mobile data. Check the address with the steps above. On Windows, open "Allow an app through Windows Firewall" and make sure Docker Desktop is allowed on private networks. On Linux with a firewall: sudo ufw allow 8080,8443/tcp.

"Port is already allocated" or "address already in use"

Something else on the computer already uses port 8080 (or 8443). Docker has still created the bothy container, so remove it first, then start again on other ports:

docker rm -f bothy
docker run -d --name bothy --restart unless-stopped -p 8090:8080 -p 8444:8444 -e BOTHY_HTTPS_PORT=8444 -v bothy-data:/data -e BOTHY_PRESET=standard andykcheng/bothy

Then open the hub at :8090 instead of :8080. For the main port, only the number on the left of -p changes. The secure port (used for chat voice messages and locations) must be the same number on both sides and in BOTHY_HTTPS_PORT, because the chat sends people straight to it.

"The container name "/bothy" is already in use"

A container from an earlier attempt is still there. Remove it with docker rm -f bothy, then run your docker run command again. The downloaded library is kept.

"Not enough free space"

The hub checks before downloading. Free some space, choose a smaller preset, or keep the library on another disk with -v /path/on/disk:/data. On Docker Desktop you can also move its disk image in Settings → Resources.

The download stopped

Restart the hub (docker restart bothy) or run docker exec -it bothy bothy-hub get. It resumes where it stopped and checks every file.

AI answers are very slow

They need a fast processor; a Raspberry Pi takes a long time. Search, first aid and everything else don't use them. To remove them, start the hub with -e BOTHY_SKIP=llm and run docker exec -it bothy bothy-hub get --skip llm.

Voice messages or "My location" don't work in the chat

Browsers only allow the microphone and GPS on secure pages, so the chat sends people to the hub's https address on port 8443 for those. The browser warns once about the hub's own certificate; that's expected on a local network, and the chat explains how to continue.

Without Docker

The hub is one program, bothy-hub, with three commands: get (download or update), check (is it ready?) and start. Ready-made downloads for Windows, Mac and Linux are planned. Until then you can build it from the source code (GNU AGPL-3.0): install Rust, CMake and Clang, then run cargo build --release -p sp-server --bin bothy-hub in the core folder.