Skip to Content
Getting started

Install Rookery

Put the Rookery command on the machine you work from. It is one file.

Rookery sets hosts up from Linux. The program contains everything it puts on a host, so installing it means placing one file on your PATH. On macOS and Windows the same program is a client of a Rookery server on another machine.

Linux and macOS
curl -fsSL https://raw.githubusercontent.com/aiviarium/rookery/main/install.sh | sh

The script downloads the latest release for this machine from GitHub, checks it against its SHA-256 and installs it to ~/.local/bin/rookery. Releases have it for Linux on x86_64 and arm64, and for macOS on Apple silicon and Intel.

VariableEffect
ROOKERY_INSTALL_DIRInstall somewhere else than ~/.local/bin
ROOKERY_VERSIONInstall a release tag such as v0.2.0 instead of the latest

On other architectures, build it with cargo.

Check it:

rookery --version
rookery

What else Rookery uses

ForNeeds
Setting up a host over SSH or applying its configurationssh, python3, ansible-playbook (ansible-core 2.21, which needs Python 3.12 or newer)
Building a USB installerpython3, xorriso, curl
Hashing passwordsopenssl
Installing plugins from a registrynpm

The install script lists what is missing. A source checkout with a .venv gets its own ansible-playbook from there:

python3 -m venv .venv && .venv/bin/pip install -r provision/requirements.txt

Where Rookery keeps things

WhatWhere
Settings of this machine, listed below~/.config/rookery/config.json
The other settings, registries, secret values and registry passwordsRookery's store, by default ~/.local/share/rookery/rookery.db
One profile per host, its generated passwords and the record of a machine Rookery created for itRookery's store too. rookery host export HOST prints a profile and rookery host credentials HOST the passwords
Rookery's SSH keys, and the token and setup key of rookery serveRookery's store. A key is written to ~/.local/share/rookery/keys/NAME when ssh needs it, and the token to serve.token
The key file of an encrypted store~/.config/rookery/store.key (setting store_key)
Locks held while Rookery creates or changes a host's machine~/.local/share/rookery/locks/
Your own plugins~/.config/rookery/plugins/, and in Rookery's store what reinstalls them
Provisioning source, unpacked from the program~/.local/share/rookery/source/
Build output such as the release archive, seeds and installer images~/.local/share/rookery/build/
Downloaded Ubuntu installer ISOs~/.local/share/rookery/iso/ (setting iso_dir)

XDG_CONFIG_HOME and XDG_DATA_HOME are honoured. rookery config list prints the paths and settings, and rookery config set KEY VALUE changes one, in the file or in the store. The Settings tab of the home screen does the same. rookery server store status says where the store is and whether it is encrypted. See The store, which also says how to restore an installation from it.

These settings stay in config.json, as they belong to this machine or are needed to open the store:

SettingsWhat they are for
store, store_key, store_caWhere the store is and how it is opened
server, server_tokenThe Rookery server this machine uses, kept by rookery login
source, iso_dirFolders on this machine

Profiles hold Wi-Fi passwords, and the store holds generated passwords and the tailnet's API key. They are in clear text unless the store is encrypted, see The store. Keep the store and its key file private, and keep files that rookery host export writes out of version control.

The provisioning source

The provisioning source is what Rookery puts on a host. It holds the Ansible role with rookeryd and box, the bootstrap scripts and the built-in plugins. It is built into the program and unpacked into the data directory the first time it is needed, and again after an update. The program can be copied to another machine as it is.

Rookery looks for the source in this order:

  1. ROOKERY_SOURCE
  2. the source setting
  3. a checkout in the current directory, when Rookery is started inside one
  4. the built-in copy

To work on the role, point Rookery at your checkout, and clear the setting to go back:

rookery config set source ~/src/rookery
rookery config set source ""
Edit on GitHub

Last updated on

On this page