Installs

A Burrow comes as one folder with everything it needs inside: the Burrow, its own Java runtime, and its own database. There is nothing else to install. Each system has two ways in: download the archive from the download page, or install it with one command that downloads, unpacks and starts it. On Linux, it also runs in Docker.

Linux#

With a command. Run this in the folder you want the Burrow in. It downloads the archive, unpacks it into a burrow folder and starts it.

curl -fsSL https://get.ratelkey.com/burrow/latest/burrow-linux-amd64.tar.gz | tar -xz && ./burrow/bin/burrow

On an ARM64 machine, such as an ARM server or a Raspberry Pi 4 or 5 running a 64-bit OS, use burrow-linux-arm64.tar.gz in its place.

From the download page. Choose Linux, pick x86-64 or ARM64, and download. Then unpack it and start it:

tar -xzf burrow-linux-amd64-*.tar.gz
./burrow/bin/burrow

Start it as your normal user. A Burrow won't start as root, because the database it runs for itself refuses to.

Run it at boot with systemd#

The folder comes with install-systemd.sh, which installs the Burrow as a service that starts at boot and restarts if it stops unexpectedly:

curl -fsSL https://get.ratelkey.com/burrow/latest/burrow-linux-amd64.tar.gz | tar -xz
sudo ./burrow/install-systemd.sh

It runs the Burrow as the user that owns the folder, and if you unpacked it as root, creates a burrow user to run it. Follow its output with journalctl -u burrow -f. Run the script again after moving the folder, and sudo ./burrow/install-systemd.sh --remove takes the service off again, leaving the folder and its data.

macOS#

With a command. Run this in Terminal, in the folder you want the Burrow in:

curl -fsSL https://get.ratelkey.com/burrow/latest/burrow-darwin-arm64.tar.gz | tar -xz && ./burrow/bin/burrow

That is the Apple silicon build, for any Mac with an M-series chip. On an Intel Mac, use burrow-darwin-amd64.tar.gz in its place. Apple menu, About This Mac shows which chip yours has.

From the download page. Choose macOS, pick Apple silicon or Intel, and download. Unpack it in Terminal and start it:

tar -xzf ~/Downloads/burrow-darwin-arm64-*.tar.gz
./burrow/bin/burrow

If you unpack it by double-clicking in Finder instead, macOS marks the unpacked files as downloaded from the internet and may stop the Burrow from starting. Run this once on the unpacked folder, then start it:

xattr -d -r com.apple.quarantine burrow

As on Linux, start it as your normal user.

Run it at boot with launchd#

The folder comes with com.ratelkey.burrow.plist, which has launchd start the Burrow at boot as your user and restart it if it stops unexpectedly. Keep the Burrow straight in your home folder, as ~/burrow: a program launchd starts can't read Desktop, Documents or Downloads. Open the plist, replace you with your macOS short user name everywhere it appears, then install it:

sudo cp ~/burrow/com.ratelkey.burrow.plist /Library/LaunchDaemons/
sudo chown root:wheel /Library/LaunchDaemons/com.ratelkey.burrow.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/com.ratelkey.burrow.plist

Its output goes to ~/burrow/burrow.log. To stop it and take it off boot, run sudo launchctl bootout system/com.ratelkey.burrow.

Windows#

With a command. Run this in PowerShell, in the folder you want the Burrow in:

curl.exe -fsSLo burrow.zip https://get.ratelkey.com/burrow/latest/burrow-windows-amd64.zip; Expand-Archive burrow.zip .; .\burrow\burrow.bat

From the download page. Choose Windows and download the zip. Extract it, open the burrow folder, and double-click burrow.bat. The Burrow runs in the console window that opens, and stops when you close it.

Run it as a service#

To have Windows start the Burrow at boot and keep it running without a window, install it as a service. Open a command prompt as administrator, go to the burrow folder, and run:

burrow-service.bat install
burrow-service.bat start

It appears in Windows Services as RatelKey Burrow and starts automatically from then on. burrow-service.bat stop stops it and burrow-service.bat remove uninstalls the service, leaving the folder and its data in place. The service writes its output to burrow\data\logs.

Docker#

The Burrow's image is ratelkey/burrow on Docker Hub, for Linux on x86-64 and ARM64. It needs Docker Compose for the first two ways in, which comes with Docker.

With a command. Run this in an empty folder. It downloads a Compose file for the current version and starts the Burrow:

curl -fsSLo compose.yaml https://get.ratelkey.com/burrow/latest/burrow-docker-compose.yaml && docker compose up -d

From the download page. Choose Docker to download compose.yaml. In the folder you saved it to, run:

docker compose up -d

Without Compose. The same settings as one command:

docker run -d --name burrow --network host --init --restart unless-stopped -v burrow:/var/lib/burrow ratelkey/burrow:latest

The Burrow runs on the machine's own network (host networking), because it reads the machine's addresses to show where it can be reached and to keep remote access to your local network until you open it. It listens on the machine's port 12010, so open that port in the machine's firewall to reach it from other devices. Follow its output with docker compose logs -f, or docker logs -f burrow without Compose.

Docker restarts it at boot and if it stops unexpectedly. Update it from the Burrow itself, as on any other system: the update installs into its volume, so it stays installed when the container is recreated.

Check the download#

Every archive on the download page has a Checksum link with its SHA-256. Work out the hash of the file you downloaded and compare the two:

After it starts#

Open https://localhost:12010 in a browser on the same machine. Your Burrow serves its own certificate until you give it one under Network, so the browser asks you to confirm the first time. A new Burrow then asks to be claimed: sign in with your RatelKey account and it becomes yours, with you as its owner.

The Burrow's folder#

Everything a Burrow is lives in its burrow folder, including its data: burrow/lib/app/data on Linux and macOS, and burrow\data on Windows. Keep the folder where it is, and back it up with the rest of the machine or with the Burrow's own backups.

In Docker, the same is in the burrow volume, at /var/lib/burrow in the container. Removing the container keeps it; removing the volume deletes the Burrow and everything in it.

Updates install into the same folder, so a Burrow is installed once. How updates reach it is covered in Burrow updates.