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	3.2 GB	All 440,000 articles, guides and answers, search by meaning, first aid, 23 games, a world map, and the 1,000 most-read books. No pictures.
standard (recommended)	8.6 GB	Everything in small, plus pictures for Wikipedia, the survival guides and Appropedia, AI answers, and 10,000 books.
everything	30 GB	Everything in standard, plus all the wikiHow and iFixit photos, all 54,000 books with illustrated editions of the classics, and compact indexes for phones that copy from the hub.

Then add street maps for the places you need (below): from a few MB for a small country to a few GB for a big one.

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 penpapertech/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 penpapertech/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.

Then choose an admin password: on the hub's page, open Manage. The first visit asks you to choose a password, which you'll need to add maps, books and more (see below). Do it straight away, because until it's set, whoever opens Manage first chooses it.

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.

Maps and more: the Manage page

Every hub has the world overview. Street-level maps, with place search, come country by country, cut along the borders. The biggest countries (the United States, Canada, Russia, China, Brazil, Germany and France) come in states or regions. There are about 500 to choose from, 150 GB for the whole world, so pick where you live and where you travel.

Choose them on the hub's Manage content page, which works like the app's Content tab: search or browse maps by continent, add or remove pictures, AI answers and games, and press Download. The hub keeps working while it downloads and switches over by itself when it's done. No restart needed.

Open the hub in a browser and choose Manage. The first time, it asks you to choose an admin password; after that it asks for it. Do this soon after starting the hub: until a password is set, the first person to open Manage sets it. Anyone on the Wi-Fi can still read, search, use the map and chat; only adding or removing content needs the password.

Forgot the password? docker exec bothy bothy-hub reset-password, then open Manage and choose a new one.

Or use commands

docker exec -it bothy bothy-hub maps germany
docker exec -it bothy bothy-hub maps add uk ireland
docker restart bothy

maps on its own lists everything; maps add us adds every US state, maps add california just one; maps remove ireland takes one off. To choose maps when you first start the hub, add -e BOTHY_ADD=map:uk,map:ireland to the docker run command.

Phones can then copy the maps from the hub in the app's Content tab.

Books

The hub holds Project Gutenberg's public-domain books with their covers: the 1,000 most read with any choice, 10,000 with standard, all 54,000 with everything. Anyone on the Wi-Fi can read them in the browser (Books on the hub's home page, which remembers the page you're on), or copy them to their phone in the app's Books tab. Add or remove book bundles, and illustrated editions of the classics, on the Manage page.

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 penpapertech/bothy
docker rm -f bothy
docker run -d --name bothy --restart unless-stopped -p 8080:8080 -p 8443:8443 -v bothy-data:/data penpapertech/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), `col:ifixit:images`…
`-e BOTHY_ADD=map:uk`	add things: maps (`map:uk`, `map:us`, `map:bavaria`) or pictures 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: penpapertech/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 penpapertech/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.