Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 15 additions & 7 deletions .agents/skills/install-berth/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,9 @@ then registers the provisioners. Check with `berth run big status` and
The features never erase a disk. They make an Incus storage pool in a folder,
or use one the user names in `devbox_incus_pool`. A server with Incus or Docker
already keeps its pools, networks, trusted clients, containers and guests, and
a provisioner registered for it by hand becomes the node's.
a provisioner registered for it by hand becomes the node's when it names the
node's address. The apply names any it left alone, with the command that makes
it the node's: `berth provisioner run NAME adopt node=big`.

Virtual machines need KVM. On a rented virtual server without it, set
`devbox_incus_virtual_machines` to `false` in `ansible_vars`. For Sysbox beside
Expand All @@ -111,7 +113,8 @@ port 7777 on this machine only, Tailscale, `tailscale serve` with TLS and a

```bash
curl -fsSL https://github.com/helightdev/berth/archive/refs/heads/main.tar.gz \
| tar xz --strip-components=1 --wildcards '*/recipes'
| tar xz --strip-components=1 --wildcards '*/recipes' \
'*/provision/ansible/roles/devbox/files/berth-server-upgrade.py'
cd recipes/berth-server
sudo ./install.sh -e tailscale_auth_key=tskey-auth-EXAMPLE
```
Expand All @@ -123,11 +126,16 @@ socket. Add the
node from the server with `berth host add big node --user root --type node`,
then as in the node's section above.

A second run changes nothing in place. It leaves the container `berth` as it
is and starts it when it was stopped. On a node, the node's action
`upgrade-server` updates it to the version of the berth that asks. Elsewhere,
run `sudo docker pull ghcr.io/helightdev/berth`, `sudo docker rm -f berth`,
then `sudo ./install.sh`. The data in `/srv/berth` stays.
A second run changes nothing in place. The container `berth` keeps its image,
data and options. A stopped one is started. To update the
server, fetch the recipe of the new version and run
`sudo ./install.sh -e berth_server_update=true`. It makes the container again
from the new image with the options of the old one, and starts the old one
again if the new one fails. On a node, the node's action `upgrade-server` does
the same. Never update with `docker rm -f berth`: a new container loses the
options passed by hand, such as the name `incus-host` the provisioners of
berth 0.5 reach. A server of berth 0.5 is updated before its clients and hosts:
the page Upgrading from 0.5 in the docs has the order.

## Things that go wrong

Expand Down
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,10 @@ same screens. `install.sh` installs it on macOS too, and on Windows:
irm https://raw.githubusercontent.com/helightdev/berth/main/install.ps1 | iex
```

Coming from berth 0.5? Update the server first, then the clients and the
hosts, as [Upgrading from 0.5](docs/content/docs/%28guide%29/use/upgrading.mdx)
says.

## Quick start

```bash
Expand All @@ -65,6 +69,7 @@ The documentation site is built from [`docs/`](docs) (`cd docs && npm install &&
- [Getting started](docs/content/docs/%28guide%29/start/install.mdx): installing berth and a first host.
- [Deploying](docs/content/docs/%28guide%29/deploy/index.mdx): the install methods, and testing in QEMU.
- [Using berth](docs/content/docs/%28guide%29/use/index.mdx): the terminal UI and commands, sign-ins, secrets and updates.
- [Upgrading from 0.5](docs/content/docs/%28guide%29/use/upgrading.mdx): the order, what is converted, and going back.
- [Extending](docs/content/docs/%28guide%29/extend/index.mdx): plugins, services and `berth serve`.
- [Reference](docs/content/docs/%28guide%29/reference/index.mdx): tools, `box`, profile fields, building and releasing.
- The API reference of berthd and `berth serve`, generated from [`docs/openapi/`](docs/openapi).
Expand Down
119 changes: 119 additions & 0 deletions crates/berth-api/src/compat.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
//! What berth says when two of its programs are of different versions: a
//! client and its server, or the server and a host's controller. Each is one
//! sentence that names both versions and what to update, the same for the
//! command line and the screens.

use crate::{API, HostType, VERSION};

/// The lowest `api` of a host's controller this berth can work with.
pub const NEEDS_HOST_API: u32 = 2;

/// Where updating from an older berth is explained.
pub const UPGRADE_DOCS: &str =
"https://github.com/helightdev/berth/blob/main/docs/content/docs/(guide)/use/upgrading.mdx";

/// The operations of berth 0.5 that this server does not have, which only a
/// client of that version still calls.
pub const OLDER_OPS: &[&str] = &["tasks.list", "tasks.run", "tasks.choices", "actions.act"];

/// Why a client refuses to work with the server at `url`, which says it is
/// berth `version` of `api`; `None` when the server is new enough.
pub fn older_server(url: &str, version: &str, api: u32) -> Option<String> {
(api < API).then(|| {
format!(
"The berth server at {url} is berth {version} (API {api}), older than this berth {VERSION} (API {API}), and would not understand what it is sent. Update the server first, then the clients and the hosts: {UPGRADE_DOCS}"
)
})
}

/// What updates the controller on a host of this type.
pub fn controller_update(host: &str, host_type: HostType) -> String {
match host_type {
HostType::Workstation | HostType::Node => format!("berth apply {host}"),
HostType::Managed | HostType::Ssh => format!("berth run {host} install-controller"),
}
}

/// What a host says when its controller is berth `version` of `api`, too
/// old for this berth; `None` when it is new enough.
pub fn older_controller(
host: &str,
version: &str,
api: u32,
host_type: HostType,
) -> Option<String> {
(api < NEEDS_HOST_API).then(|| controller_is_older(host, version, host_type))
}

/// That the controller on `host`, berth `version`, is too old for this berth,
/// and what updates it.
pub fn controller_is_older(host: &str, version: &str, host_type: HostType) -> String {
format!(
"The controller on {host} is berth {version}, older than this berth {VERSION}. Update it with {}",
controller_update(host, host_type)
)
}

/// What the server answers a client that calls an operation it does not
/// have: for one of an older berth, that the client is older.
pub fn no_operation(name: &str) -> String {
match OLDER_OPS.contains(&name) {
true => format!(
"No operation {name}: it is a call of berth 0.5, and this server is berth {VERSION}. Update berth where this call comes from: {UPGRADE_DOCS}"
),
false => format!("No operation {name}"),
}
}

#[cfg(test)]
mod tests {
use super::*;

#[test]
fn an_older_server_is_named_with_both_versions() {
assert_eq!(older_server("https://pier.example", VERSION, API), None);
let said = older_server("https://pier.example", "0.5.2", 1).unwrap();
assert!(said.contains("is berth 0.5.2 (API 1)"), "{said}");
assert!(
said.contains(&format!("this berth {VERSION} (API {API})")),
"{said}"
);
assert!(said.contains("Update the server first"), "{said}");
assert!(said.ends_with(UPGRADE_DOCS), "{said}");
}

#[test]
fn an_older_controller_says_what_updates_it() {
assert_eq!(
older_controller("studio", VERSION, NEEDS_HOST_API, HostType::Workstation),
None
);
let said = older_controller("studio", "0.5.2", 1, HostType::Workstation).unwrap();
assert!(said.starts_with("The controller on studio is berth 0.5.2, older than this berth"));
assert!(
said.ends_with("Update it with berth apply studio"),
"{said}"
);
let said = older_controller("big", "0.5.2", 1, HostType::Node).unwrap();
assert!(said.ends_with("berth apply big"), "{said}");
let said = older_controller("pier", "0.5.2", 1, HostType::Managed).unwrap();
assert!(
said.ends_with("berth run pier install-controller"),
"{said}"
);
}

#[test]
fn a_call_of_an_older_client_says_so() {
assert_eq!(no_operation("hosts.nothing"), "No operation hosts.nothing");
assert!(no_operation("tasks.list").contains("a call of berth 0.5"));
// None of them is an operation now.
for name in OLDER_OPS {
assert!(
crate::ops::find(crate::ops::SERVE, name).is_none(),
"{name}"
);
assert!(crate::ops::find(crate::ops::HOST, name).is_none(), "{name}");
}
}
}
1 change: 1 addition & 0 deletions crates/berth-api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@

#[cfg(feature = "client")]
pub mod client;
pub mod compat;
pub mod escape;
pub mod ops;
#[cfg(feature = "client")]
Expand Down
Loading
Loading