Start a community
Every community runs on its own node: a small server that holds that community's members, posts and ledger. Someone local runs it. If your town or valley doesn't have one yet, it could be you.
What running a community involves
About half an hour, if you can follow a recipe. Six things to know first:
- What it costs. The software is free. It runs on a spare computer that stays on at home (a Mini PC, a NAS, or a Raspberry Pi with a 64-bit system), or on a small rented server for a few dollars a month (about US$6).
- Who hosts it. You do, on your own machine or the one you rent. It never needs beanpool.org: your own web address works.
- What you take on. Reports from your members come to you. The data folder is yours to back up, with a recovery code. Keep two owners. Keep the server on and updated.
- What you never see. Your members' direct messages.
- Docker first. The machine needs Docker installed before the block below; a freshly rented server has none.
- An address phones can reach. Phones reach a community on the internet only over https. On a rented server with a public IP address and ports 80 and 443 open, that IP address is enough: your server gets its own certificate for it, with no Cloudflare account, and the same for a domain of your own. At home, or with no open ports, the claim gives you a free name ending in .beanpool.org, through a tunnel your server runs itself. A plain http:// address works only on a home network.
What you look after
You and the admins you appoint are your community's moderators: reports come to you. Your members' data lives on your machine, so you keep it backed up. You can read enterprise discussions and event chats; you can't read direct messages. You invite the first members, and they invite the rest.
The settings app
Your node comes with its own settings app in the browser. From it you name your community, appoint an owner and admins who sign in with their own keys, print QR invites, watch disk health, choose a public web address or a tunnel, and help a member who has lost both their phone and their 12 words back into their own account on a new phone, with a one-time code you confirm in person.
Private from the first boot
A community's listings, map, messages and balances are for its members from the moment its node starts; there is nothing to switch on. Someone who opens its address without an account is pointed to the global community, where they can see what is near them and ask to join.
Linking with a neighbouring community
Two communities can agree to link so their members can trade with each other. Beans never leave home: each pair keeps a running tally of what one community owes the other, and each side sets its own limit. Linking is off unless both operators switch it on, and it is still early: it is built, with its screens in the web app, and has been tried only between two of our own test communities, never between live ones.
Your address
Choose it before you paste, and change the last line to match. If you already pasted, press Enter at its questions, then run the last line again: the claim code waits for a phone. A rented server with a public IP address and ports 80 and 443 open: add --ip and its IP address, as in beanpool claim --ip 203.0.113.7. Your server gets its own certificate for that address from Let's Encrypt, over port 80, and phones reach it at https://203.0.113.7. A computer at home, or no open ports: leave it as it is. It asks for the first part of a free name (type just yourtown for yourtown.beanpool.org; Enter skips), reached through a tunnel your server runs itself, and waits up to three minutes for it to go live. Your own domain: point an A record for it at the server's IP address, open ports 80 and 443, and add --address https://your.domain. A name survives a change of server; a number does not: you can add a name later in Settings, and members who use the IP address keep working. To choose later in Settings, add --no-name. A plain http:// address works only on a home network: phones refuse it on the internet, and the claim warns you. If the BeanPool project's address service is down, the claim still works.
Install it
Then, on that machine with Docker installed, paste this one block. It fetches the compose file, creates the network the node uses, pulls the published image (Intel/AMD or ARM64), starts it, waits until the server has made its one-time claim code (up to five minutes, for a slow first start on a Raspberry Pi), and claims it. There is nothing to configure before it starts.
git clone https://github.com/beanpool-org/beanpool.git && cd beanpool
docker network create beanpool-shared
docker compose pull
docker compose up -d
echo "Waiting for the server to make its claim code (up to 5 minutes)..."
for i in $(seq 60); do docker compose exec -T beanpool-node test -f /data/claim-code.txt </dev/null 2>/dev/null && break; sleep 5; done
docker compose exec -T beanpool-node test -f /data/claim-code.txt </dev/null 2>/dev/null || echo "No claim code after 5 minutes. The server's log says why: docker compose logs beanpool-node"
docker compose exec beanpool-node beanpool claim
The last line: beanpool claim
- The code and QR. It shows a one-time claim code, a QR code and, numbered, what to do next. First, on the phone that will own the community, install BeanPool from Google Play or the App Store. Then scan the QR code with your phone's camera, or open BeanPool and tap Installed BeanPool on a server? Claim it. The claim makes your BeanPool account on that phone, with no invite and nothing from the BeanPool project: type your name, tap Claim and become owner, and write down the 12 words it shows you. A phone that already has an account claims with it. That phone becomes the owner.
- Settings. Open your address (or the server's own address) followed by /settings. The setup wizard names your community, asks you to add a second owner, and makes three founding invites. Set your place on the map under Node Identity so people nearby can find you.
If the block says No claim code after 5 minutes, or beanpool claim says This community has no claim code waiting, the server has not finished starting: docker compose logs beanpool-node shows where it is. Once the log says the community has no owner yet and has a claim code, run the last line again. The full steps are in the operator manual's first-time setup.
Recommended: keep your community running when Docker updates
The step is on the Updates and health page of the operator manual. An AI assistant doing the install always does this step (Setting up your server with an AI assistant).
View on GitHub →