Skip to content
Open
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
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "urbex",
"version": "0.2.1",
"version": "0.2.3",
"description": "Set up Urbex on a Proxmox node, write and change urbex.yaml, and run every urbex command: bootstrap, apply, release, deploy, promote, secrets, status.",
"author": {
"name": "urbforge",
Expand Down
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,21 @@ workflow refuses a tag whose version has no entry here.

## [Unreleased]

### Plugin 0.2.3

Needs **urbex 0.1.0 or later, major 0**; works with urbex 0.2.0.

- **Changed**: the `cli` skill knows `urbex bootstrap`'s refusal on a
platform created by 0.1.0 (its forge is Gitea): it explains it and
points to the upgrading guide, and runs none of the destroying steps
unless asked (urbforge/urbex-cli#134).

### Docs

- **Added**: *From 0.1.0 to 0.2.0* in the upgrading guide - Forgejo in
place of Gitea, why a 0.1.0 platform is started again rather than
upgraded, the steps, and that 0.2.0 carries the Java4Shell mitigation.

### Plugin 0.2.1

Needs **urbex 0.1.0 or later, major 0**.
Expand Down
36 changes: 34 additions & 2 deletions docs/upgrading.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,37 @@ or the `CHANGELOG.md` of [urbex-cli](https://github.com/urbforge/urbex-cli/blob/
and of [this repository](../CHANGELOG.md): their *Breaking* and
*Upgrading* sections say when a command is needed after upgrading.

## From 0.1.0 to 0.2.0

0.2.0 brings the Java4Shell mitigation (CVE-2026-114938: Keycloak's JVM
and the `runtime: java` images run without the vulnerable Base64
intrinsic) and replaces the forge: **Forgejo 15 LTS instead of Gitea 1.24**
([ADR-0034](decisions/0034-forgejo-lts-forge.md)).

Forgejo can't open the database of Gitea 1.24, so a platform created by
0.1.0 can't be bootstrapped again in place: `urbex bootstrap` with 0.2.0
sees that its forge is Gitea and refuses, changing nothing. To get
0.2.0's platform, Java4Shell's mitigation included, start the platform
again:

1. Back up what you keep in the applications' named volumes ([back up
and restore an application's data](cookbook.md#back-up-and-restore-an-applications-data)):
they go with their LXCs.
2. `urbex destroy <env>` for each environment of each project.
3. `urbex teardown --yes`: the platform's LXCs go, Gitea's repositories
and images with them.
4. Upgrade the tools (below), then `urbex bootstrap`.
5. Push each project's repository again from your clone, and `urbex
apply` its environments; restore the volumes' data.

The workspace needs no change: the credentials and the platform config
that 0.1.0 wrote are read as they are (`giteaToken`, `git.giteaUrl`; the
new names `forgeToken`, `git.forgeUrl` win when both are set).

Staying on 0.1.0 is possible: keep its `urbex-op` and don't run 0.2.0
against that platform. Its Keycloak then keeps the Java4Shell exposure
on CPUs with AVX-512 VBMI (see the [known limitations](known-limitations.md#operations-and-security)).

## With urbex-op

Download the new release's `urbex-op` over the old one. Its next command
Expand Down Expand Up @@ -51,13 +82,14 @@ that Terraform, Ansible, sops and age are at the versions the release's

The plugin has its own version. It works with any `urbex` of the same
major version (0 today). While both are 0.x it also needs a minimum,
which its `cli` skill states: urbex 0.1.0 for plugin 0.2.1.
which its `cli` skill states: urbex 0.1.0 for plugin 0.2.3. urbex 0.2.0
needs no newer plugin.

### Plugin and CLI versions

| Plugin | urbex |
|---|---|
| 0.2.0, 0.2.1 | 0.1.0 or later, major 0 |
| 0.2.0 to 0.2.3 | 0.1.0 or later, major 0 |

The plugin checks `urbex version` once per session. When `urbex` is
older than it needs, it says so and points here. When the major versions
Expand Down
9 changes: 8 additions & 1 deletion skills/cli/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ Neither: use the `setup` skill.

## Versions

This plugin (0.2.1) needs **urbex 0.1.0 or later, with the same major
This plugin (0.2.3) needs **urbex 0.1.0 or later, with the same major
version (0)**. Once per session, run `urbex version` (`urbex-op
'urbex version'`):

Expand Down Expand Up @@ -119,6 +119,13 @@ When a command refuses ("has named volumes", "a replacement is never
allowed", "release it first"), tell the user what it said and what it
suggests. Don't add a flag that overrides the refusal on your own.

If `urbex bootstrap` refuses because "the platform's forge is Gitea", the
platform was created by urbex 0.1.0 and can't move to this urbex in
place. Moving means destroying every environment and the platform
(`docs/upgrading.md`, *From 0.1.0 to 0.2.0*): their data and Gitea's
repositories go. Tell the user, point to that page, and run none of
those commands unless they ask, one confirmation each.

## Secrets and credentials

- Never print, read or copy `credentials.yaml`, `age.key`, or a
Expand Down