157 lines
10 KiB
Markdown
157 lines
10 KiB
Markdown
# Installation
|
|
|
|
## Requirements
|
|
|
|
- Linux with systemd (`systemd-nspawn`, `systemd-machined`, `systemd-networkd`), running as root. Containers run with user namespacing and ID-mapped mounts, so you need systemd 250 or newer and a kernel that supports ID-mapped mounts for the filesystems holding `/nix/store`, `state_dir` and the drives (btrfs, ext4 and xfs on any recent kernel).
|
|
- One or more **btrfs** folders for home folders. Quotas are switched on automatically.
|
|
- Nix with flakes, to build the bot and the container system. NixOS is easiest, but not required. It has to be a multi-user install with `nix-daemon` running: containers build through `/nix/var/nix/daemon-socket`, and won't start without it. The daemon sees containers as untrusted users (they run as unprivileged host uids), so `trusted-users` needs no changes, but `allowed-users` must still allow everyone (the default `*`). Their builds go into the host's store, so run `nix-collect-garbage` or `nix.gc` now and then.
|
|
- An API key for the model goose should use (e.g. Anthropic).
|
|
|
|
## 1. Slack app
|
|
|
|
1. Go to <https://api.slack.com/apps> → **Create New App** → **From a manifest**, and paste `slack-manifest.yaml`.
|
|
2. Install it to your workspace and copy the **bot token** (`xoxb-…`).
|
|
3. Under **Basic Information → App-Level Tokens**, create a token with the `connections:write` scope (`xapp-…`).
|
|
|
|
The app uses Socket Mode, so the bot needs no public URL.
|
|
|
|
Updating an existing app: paste the new `slack-manifest.yaml` under **App Manifest**, then reinstall the app so new scopes and events (such as the assistant pane or thread replies) take effect. The bot token stays the same.
|
|
|
|
## 2. Container system
|
|
|
|
Build the NixOS system each container boots:
|
|
|
|
```
|
|
nix build git+https://gitea.skyg.ca/ari/slacker-bot.git#agent -o /var/lib/slackerbot/agent-system
|
|
# or, from a checkout:
|
|
nix build .#agent -o /var/lib/slackerbot/agent-system
|
|
```
|
|
|
|
Rebuild the same way after changing `nix/container.nix`, and after upgrading the bot: the container includes `slackerbot-tools` (the agent's `send_file` tool) from the same checkout. Each container picks up the new build on its next start. `nix/container.nix` runs `goose serve`, which needs a recent goose. If nixpkgs' `goose-cli` is too old, override it there.
|
|
|
|
## 3. Config
|
|
|
|
Copy `config.example.toml` and edit it. The important parts:
|
|
|
|
| Setting | What |
|
|
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
|
|
| `system` | The build from step 2, e.g. `/var/lib/slackerbot/agent-system` |
|
|
| `state_dir` | Where `state.json`, in-flight replies, env files and cluster certificates live |
|
|
| `[agent_env]` | Environment for goose (provider, model, API key). `$VARS` are expanded from the bot's environment |
|
|
| `[container]`, `[max_container]` | Default and largest container size |
|
|
| `[host_reserve]` | RAM/CPU kept free for the host |
|
|
| `idle_timeout`, `max_idle_timeout`, `allow_indefinite` | Idle shutdown rules |
|
|
| `max_send_file_mb` | Largest file the agent may send, and the largest attachment copied in (default 100, at most 1024) |
|
|
| `[storage]` | Default guaranteed (`min`) and cap (`max`) home size, and the largest cap anyone may set (`limit`) |
|
|
| `[[drives]]` | btrfs folders for home folders, each with a `reserve` kept free |
|
|
| `[permissions]` | Starting permissions, copied in on first start only (see USERGUIDE.md) |
|
|
| `[cluster]` | Only for more than one node (see step 6) |
|
|
|
|
## 4. Secrets
|
|
|
|
The Slack tokens from step 1 and the model API key are read from the bot's **environment**. Put them in a root-only env file, kept out of git and the Nix store:
|
|
|
|
```
|
|
sudo install -d -m 700 /etc/slackerbot
|
|
sudo install -m 600 /dev/null /etc/slackerbot/secrets
|
|
sudoedit /etc/slackerbot/secrets
|
|
```
|
|
|
|
```sh
|
|
SLACK_APP_TOKEN=xapp-…
|
|
SLACK_BOT_TOKEN=xoxb-…
|
|
ANTHROPIC_API_KEY=sk-ant-…
|
|
CLUSTER_SECRET=…
|
|
```
|
|
|
|
One `NAME=value` per line, with no quotes needed and no comments after a value (systemd would read the comment as part of the value). `CLUSTER_SECRET` is only needed with more than one node.
|
|
|
|
| Variable | Overrides | Needed on |
|
|
| ----------------------------------------------------------- | --------------------------------- | ------------------------ |
|
|
| `SLACK_APP_TOKEN` | `[slack] app_token` | master |
|
|
| `SLACK_BOT_TOKEN` | `[slack] bot_token` | master |
|
|
| `CLUSTER_SECRET` | `[cluster] secret` | every node, if clustered |
|
|
| anything named in `[agent_env]` (e.g. `$ANTHROPIC_API_KEY`) | expanded into the container's env | master |
|
|
|
|
The master refuses to start without both Slack tokens. You _can_ write them into `[slack]` in the config instead, but then the config holds secrets. With NixOS, the config file is copied into the world-readable Nix store, so use the env file there.
|
|
|
|
The bot writes the `[agent_env]` values, with `$VARS` expanded, to a root-only file under `state_dir/env/`, and bind-mounts it read-only into the container at `/var/lib/slackerbot/agent.env`, where goose reads it at start. To give goose another key, add it to the secrets file and reference it in `[agent_env]`:
|
|
|
|
```toml
|
|
[agent_env]
|
|
GOOSE_PROVIDER = "anthropic"
|
|
ANTHROPIC_API_KEY = "$ANTHROPIC_API_KEY"
|
|
```
|
|
|
|
## 5. Run the bot
|
|
|
|
### NixOS
|
|
|
|
Add the flake to your system flake and import the host module:
|
|
|
|
```nix
|
|
inputs.slackerbot.url = "git+https://gitea.skyg.ca/ari/slacker-bot.git";
|
|
|
|
# in your host's modules:
|
|
imports = [ inputs.slackerbot.nixosModules.host ];
|
|
services.slackerbot = {
|
|
enable = true;
|
|
configFile = ./slackerbot.toml;
|
|
environmentFile = "/etc/slackerbot/secrets"; # from step 4; a string path, so it stays out of the Nix store
|
|
};
|
|
```
|
|
|
|
The module runs the bot as a systemd service with `/var/lib/slackerbot` as its state directory. It also sets up `systemd-networkd` to give each container's `ve-*` link an address over DHCP with NAT, and trusts those links in the firewall.
|
|
|
|
### Other Linux
|
|
|
|
```
|
|
sudo nix build git+https://gitea.skyg.ca/ari/slacker-bot.git#slackerbot -o /opt/slackerbot # or: cd slackerbot && go build
|
|
```
|
|
|
|
Or build a static binary with Bazel from a checkout: `bazel build --config=release //slackerbot:slackerbot_tar` produces `bazel-bin/slackerbot/slackerbot_tar.tar.gz`, which holds `usr/bin/slackerbot`.
|
|
|
|
Run it as a systemd service so the secrets file from step 4 is loaded. Save this as `/etc/systemd/system/slackerbot.service`:
|
|
|
|
```ini
|
|
[Unit]
|
|
Description=slackerbot
|
|
After=network-online.target systemd-machined.service
|
|
Wants=network-online.target
|
|
|
|
[Service]
|
|
ExecStart=/opt/slackerbot/bin/slackerbot -mode master -config /etc/slackerbot/config.toml
|
|
EnvironmentFile=/etc/slackerbot/secrets
|
|
StateDirectory=slackerbot
|
|
Restart=on-failure
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
```
|
|
|
|
```
|
|
sudo systemctl daemon-reload && sudo systemctl enable --now slackerbot
|
|
journalctl -u slackerbot -f
|
|
```
|
|
|
|
Make sure `systemd-networkd` manages `ve-*` links. systemd ships `80-container-ve.network` for this. `btrfs-progs` must be on the bot's `PATH`.
|
|
|
|
Check the log for the node's capacity line and "connected to Slack", then DM the bot `help`.
|
|
|
|
## 6. More nodes (optional)
|
|
|
|
1. On every node, set the same `[cluster] secret` (16+ characters), plus its own `system`, `[[drives]]` and `host_reserve`, and build the container system there. Slaves don't need Slack tokens or `agent_env`, because the master sends those, but each needs `CLUSTER_SECRET` in its own secrets file (step 4).
|
|
2. **Master:** set `cluster.listen = ":7946"` and open the port. On NixOS: `services.slackerbot.clusterPort = 7946`.
|
|
3. **Slaves:** set `cluster.master = "wss://<master>:7946"` and a unique `cluster.name` (default: the hostname). Run with `-mode slave`. On NixOS: `services.slackerbot.mode = "slave"`.
|
|
4. The master logs its certificate fingerprint at startup. Put it in each slave's `cluster.master_fingerprint`. If you leave it empty, a slave trusts the first certificate it sees, saves it in `state_dir/master.fingerprint`, and refuses any other from then on.
|
|
|
|
`nodes` in Slack should now list every node.
|
|
|
|
## Maintenance
|
|
|
|
- **Permissions** live in the master's `state.json` after the first start, and editing the config doesn't change them. To start over from the config, stop the master and delete the `permissions` entry from `state.json`.
|
|
- **Deleting a home folder for good:** stop its container, run `btrfs subvolume delete <drive path>/<u-… or c-…>`, then, with the bot stopped, remove its owner from `state.json`. Nothing deletes homes automatically, so their guaranteed space stays taken. This includes homes left on a dead slave after **Create new container**.
|
|
- **In-flight replies** are in `state_dir/in-flight-<channel>.json`, one file per channel while it has a reply in progress. The bot picks them back up when it starts. To stop a reply from being resumed, stop the bot and delete its entry (or the file).
|
|
- **Upgrading** the bot doesn't stop running containers, because each runs in its own `slackerbot-<machine>.service` unit.
|
|
- Find user and channel IDs in Slack with **Copy member ID** on a profile, or at the bottom of a channel's **About** tab.
|