diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 9be6881..7a644ab 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "urbex", - "version": "0.1.4", + "version": "0.2.0", "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", diff --git a/README.md b/README.md index 418f452..e568e1c 100644 --- a/README.md +++ b/README.md @@ -16,13 +16,16 @@ Write the app; Urbex gives it everything else - repositories, builds, deploys, l Every environment, from a homelab to the cloud, should give applications the same fundamental services, the same way. Urbex is that platform. -> **Status: working prototype, not released yet.** The whole flow - from an +> **Status: preview release ([v0.1.0](https://github.com/urbforge/urbex-cli/releases/tag/v0.1.0)).** The whole flow - from an > empty Proxmox node to an app in staging and production - runs end to end -> and has been validated on a real server. The CLI is open source -> ([Apache-2.0](LICENSE)) and public: -> [`urbforge/urbex-cli`](https://github.com/urbforge/urbex-cli). You build -> it from its repository - see [Get Urbex](docs/getting-started/with-the-cli.md#1-get-urbex). -> We are looking for testers: see +> and has been validated on a real server. Download `urbex`, or `urbex-op` +> and its image, from the release - see +> [Get Urbex](docs/getting-started/with-the-cli.md#1-get-urbex). A preview: +> no backups yet, Proxmox only, one operator - see the +> [known limitations](docs/known-limitations.md). The CLI is open source +> ([Apache-2.0](LICENSE)): +> [`urbforge/urbex-cli`](https://github.com/urbforge/urbex-cli). We are +> looking for testers: see > [Try it early, tell us what's missing](#try-it-early-tell-us-whats-missing). ## Who it's for - today @@ -221,8 +224,8 @@ trimmed once its base services are settled): **How to tell us**: open an [issue](https://github.com/urbforge/urbex/issues) - what you deployed, -where it stopped, what you expected, and the output of the command that -failed. A problem with the CLI itself can also go to +where it stopped, what you expected, the output of the command that +failed, and `urbex version` (or `urbex-op 'urbex version'`). A problem with the CLI itself can also go to [urbex-cli's issues](https://github.com/urbforge/urbex-cli/issues). If you help people take their apps to production and see what's missing, tell us too: it shapes the roadmap. @@ -244,6 +247,7 @@ Start here: [CLI](docs/getting-started/with-the-cli.md), [any AI agent](docs/getting-started/with-an-ai-agent.md) or [Claude Code](docs/getting-started/with-claude-code.md). +- [**Upgrading**](docs/upgrading.md) — moving to a new release. - [**Cookbook**](docs/cookbook.md) — recipes: releasing, rolling back, pinning staging, secrets, adding services, troubleshooting, driving Urbex from an LLM agent (the Claude Code plugin included). diff --git a/docs/cookbook.md b/docs/cookbook.md index e516cf2..1f32467 100644 --- a/docs/cookbook.md +++ b/docs/cookbook.md @@ -1047,20 +1047,25 @@ its resource metrics are still collected. ## Run urbex from a container Rather than installing `terraform`, `ansible-playbook`, `sops` and the -rest, run `urbex` with `tools/operator/urbex-op` from `urbforge/urbex-cli` -(podman or docker). It works on a **workspace**: one folder with the +rest, run `urbex` with `urbex-op` (podman or docker): one script, from +each [release](https://github.com/urbforge/urbex-cli/releases), that runs +the release's image `ghcr.io/urbforge/urbex-op:` and pulls it +the first time. It works on a **workspace**: one folder with the credentials, the SSH and age keys, the GitOps repo and your projects. ```sh -cd urbex-cli -tools/operator/urbex-op build # the image, with urbex built from the checkout -tools/operator/urbex-op -w ~/urbex-work init # SSH key, age key, folders -tools/operator/urbex-op -w ~/urbex-work set proxmoxToken # stored in the workspace (or export URBEX_PROXMOX_TOKEN) -tools/operator/urbex-op -w ~/urbex-work 'urbex bootstrap' -tools/operator/urbex-op -w ~/urbex-work 'cd /work/projects/acme-app && urbex apply staging' -tools/operator/urbex-op -w ~/urbex-work shell # an interactive shell +curl -fsSLo ~/bin/urbex-op https://github.com/urbforge/urbex-cli/releases/download/v0.1.0/urbex-op +chmod +x ~/bin/urbex-op +urbex-op -w ~/urbex-work init # SSH key, age key, folders +urbex-op -w ~/urbex-work set proxmoxToken # stored in the workspace (or export URBEX_PROXMOX_TOKEN) +urbex-op -w ~/urbex-work 'urbex bootstrap' +urbex-op -w ~/urbex-work 'cd /work/projects/acme-app && urbex apply staging' +urbex-op -w ~/urbex-work shell # an interactive shell ``` +From a checkout of `urbforge/urbex-cli`, `tools/operator/urbex-op build` +builds the image from the checkout instead, and that script runs it. + The workspace is `/work` in the container (`$HOME` is `/work/home`, the GitOps repo `/work/gitops`). Details in `tools/operator/README.md`. diff --git a/docs/getting-started.md b/docs/getting-started.md index b32fb1f..ebac534 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -6,8 +6,10 @@ prerequisites. Then pick a guide: Claude Code with the Urbex plugin, any other AI agent, or the commands typed by you. Allow an hour the first time, most of it spent waiting for downloads. -> ⚠️ Urbex is early-stage. Everything here has been run end to end on a -> real Proxmox VE 9.2 node - see [`status.md`](status.md) and +> ⚠️ Urbex is a preview release +> ([v0.1.0](https://github.com/urbforge/urbex-cli/releases/tag/v0.1.0)). +> Everything here has been run end to end on a real Proxmox VE 9.2 node - +> see [`status.md`](status.md) and > [`known-limitations.md`](known-limitations.md). > > The CLI is open source (Apache-2.0), in @@ -119,8 +121,8 @@ Linux or macOS, `git`, and one of the following: | | Install | Notes | |---|---|---| -| **Container** (recommended) | `podman` or `docker` | Nothing else: the image has `urbex`, Terraform, Ansible, sops and age at the versions the CLI is tested with. Go isn't needed. | -| **Native** | [mise](https://mise.jdx.dev), then `mise install` in the `urbex-cli` checkout | Installs the pinned versions of Go (only to build `urbex`), Terraform, Ansible, sops and age, listed in `urbex-cli`'s `mise.toml`. Without mise, install them yourself: Go 1.26, Terraform 1.13 (or OpenTofu), `ansible-core`, `sops`, `age`, plus `ssh`. | +| **Container** (recommended) | `podman` or `docker` | Nothing else: `urbex-op`, from the release, runs the release's image, which has `urbex`, Terraform, Ansible, sops and age at the versions the CLI is tested with. | +| **Native** | `urbex` from the release, plus Terraform, Ansible, sops and age | The versions `urbex-cli`'s `mise.toml` pins: with [mise](https://mise.jdx.dev), `mise use -g` each of them; without, install them yourself: Terraform 1.13 (or OpenTofu), `ansible-core`, `sops`, `age`, plus `ssh`. | Every guide below uses the container. With the native tools, run the same `urbex ...` commands directly, after the extra setup in diff --git a/docs/getting-started/with-an-ai-agent.md b/docs/getting-started/with-an-ai-agent.md index 092296e..fb6f9ad 100644 --- a/docs/getting-started/with-an-ai-agent.md +++ b/docs/getting-started/with-an-ai-agent.md @@ -18,10 +18,10 @@ your app: ```text Set up Urbex for me and deploy my app with it. -1. Clone https://github.com/urbforge/urbex and https://github.com/urbforge/urbex-cli - side by side, then read urbex/docs/getting-started.md and +1. Clone https://github.com/urbforge/urbex, read + urbex/docs/getting-started.md and urbex/docs/getting-started/with-the-cli.md, and follow the latter - with the container (urbex-op). + with the container: urbex-op, downloaded from the urbex-cli release. 2. Find every value yourself, don't ask me for what you can discover: from this machine the LAN's CIDR, gateway and DNS, the Proxmox node (port 8006 on the LAN) and a free block of addresses; once my tokens diff --git a/docs/getting-started/with-claude-code.md b/docs/getting-started/with-claude-code.md index ccf365f..00b68b9 100644 --- a/docs/getting-started/with-claude-code.md +++ b/docs/getting-started/with-claude-code.md @@ -23,8 +23,11 @@ From the `/plugin` menu instead, choose *Add Marketplace* and enter only `urbforge/urbex`; then install `urbex` from the marketplace's list. It also needs `python3`, 3.8 or later, on your machine, for the scripts -that find your settings. `urbex` itself is built from -[`urbforge/urbex-cli`](https://github.com/urbforge/urbex-cli). +that find your settings. `urbex` itself comes from the releases of +[`urbforge/urbex-cli`](https://github.com/urbforge/urbex-cli/releases): +the plugin downloads it. The plugin has its own version; it works with +any `urbex` of the same major version and says when yours is older than +it needs - see [Plugin and CLI versions](../upgrading.md#plugin-and-cli-versions). ## 2. Set up Urbex @@ -42,7 +45,8 @@ Or ask in plain words: "set up Urbex on my Proxmox node". What happens: pings each address of the LAN once. 2. **It asks one question**: whether you use Cloudflare. The choices are none, a Quick Tunnel, or your own zone. -3. **It builds `urbex-op`** and creates the workspace in `~/urbex-work`. +3. **It downloads `urbex-op`** from the newest release of urbex-cli, and + creates the workspace in `~/urbex-work` (which pulls the image). 4. **You prepare Proxmox**, choosing between two ways: a script, which it recommends, or the commands by hand. The script runs in your own terminal, not in the chat. It asks for the password of `root@pam` without showing it, diff --git a/docs/getting-started/with-the-cli.md b/docs/getting-started/with-the-cli.md index 1af1c80..b5bb6b7 100644 --- a/docs/getting-started/with-the-cli.md +++ b/docs/getting-started/with-the-cli.md @@ -7,13 +7,17 @@ docker. ## 1. Get Urbex +Download `urbex-op` from the [release](https://github.com/urbforge/urbex-cli/releases/tag/v0.1.0): +one script, which runs that release's image, +`ghcr.io/urbforge/urbex-op:0.1.0`, and pulls it the first time. + ```sh -git clone https://github.com/urbforge/urbex-cli.git ~/src/urbex-cli -cd ~/src/urbex-cli -tools/operator/urbex-op build # builds the image, with urbex compiled from this checkout -ln -s "$PWD/tools/operator/urbex-op" ~/bin/urbex-op +mkdir -p ~/bin +curl -fsSLo ~/bin/urbex-op https://github.com/urbforge/urbex-cli/releases/download/v0.1.0/urbex-op +chmod +x ~/bin/urbex-op # ~/bin must be on your PATH export URBEX_WORKSPACE=~/urbex-work # put this in your shell's profile -urbex-op init +urbex-op init # pulls the image the first time +urbex-op 'urbex version' # urbex 0.1.0 (commit ..., built ..., linux/amd64) ``` `init` creates the **workspace**: one folder with the SSH key Urbex @@ -136,12 +140,17 @@ That's it. For configuration and secrets see ## Native tools -Without the container, build `urbex` and set up what the container does -for you: +Without the container, download `urbex` from the +[release](https://github.com/urbforge/urbex-cli/releases/tag/v0.1.0) - the +archive for your system (Linux or macOS, amd64 or arm64), checked against +`checksums.txt` - and set up what the container does for you: ```sh -cd ~/src/urbex-cli -mise install && mise run build && mv urbex ~/bin/ # or: go build -o ~/bin/urbex ./cmd/urbex +v=0.1.0 os=linux arch=amd64 # or darwin, arm64 +curl -fsSLO https://github.com/urbforge/urbex-cli/releases/download/v$v/urbex_${v}_${os}_${arch}.tar.gz +curl -fsSL https://github.com/urbforge/urbex-cli/releases/download/v$v/checksums.txt | grep "_${os}_${arch}.tar.gz" | sha256sum -c # macOS: shasum -a 256 -c +tar xzf urbex_${v}_${os}_${arch}.tar.gz urbex && mv urbex ~/bin/ +urbex version ssh-keygen -t ed25519 -f ~/.ssh/urbex -C urbex && ssh-add ~/.ssh/urbex age-keygen -o ~/urbex.key # back it up export URBEX_PROXMOX_TOKEN='urbex@pve!cli=' @@ -152,8 +161,13 @@ urbex bootstrap Then run the commands of steps 3 to 6 without `urbex-op '...'`, from your app's folder, wherever it is. Terraform, Ansible and sops must be -on the `PATH` there: with mise, that is `mise use -g` for each tool, or a -`mise.toml` in that folder. +on the `PATH` there, at the versions urbex-cli's +[`mise.toml`](https://github.com/urbforge/urbex-cli/blob/v0.1.0/mise.toml) +pins: with mise, that is `mise use -g` for each tool, or a `mise.toml` in +that folder. `urbex doctor` checks them. + +To build `urbex` from source instead (to work on it), see *Build & test* +in [urbex-cli's README](https://github.com/urbforge/urbex-cli#build--test). ## Configuration and secrets diff --git a/docs/known-limitations.md b/docs/known-limitations.md index 0d6f3aa..9171625 100644 --- a/docs/known-limitations.md +++ b/docs/known-limitations.md @@ -16,6 +16,13 @@ validation on a real Proxmox VE 9.2 node and Cloudflare account, and of Cloudflare Quick Tunnel ([ADR-0025](decisions/0025-cloudflare-quick-tunnel.md)) on the same node. +**v0.1.0 is a preview release.** In short: no backups of the platform +yet ([below](#operations-and-security), planned in M3); Proxmox only +(VPS support is planned in M3, E3-bis); a single operator, from one +workspace; and while Urbex is 0.x, a +minor release may change how something works (see +[Upgrading](upgrading.md)). + - [Platform](#platform) - [Projects and deploys](#projects-and-deploys) - [Public endpoints (Cloudflare)](#public-endpoints-cloudflare) diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 20fb98e..c92d62b 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -19,6 +19,7 @@ the [cookbook](../cookbook.md). - [`urbex destroy`](#urbex-destroy) - [`urbex teardown`](#urbex-teardown) - [`urbex users`](#urbex-users) +- [`urbex version`](#urbex-version) - [Environment variables](#environment-variables) - [Exit status and output](#exit-status-and-output) @@ -85,10 +86,13 @@ fails for no clear reason. - **cloudflare**, with an account in the config: the token is active and sees the zone of `domain`. -Each check is `ok`, `warn`, `fail` or `skip`; a check that isn't `ok` -has its fix under it. On the lab: +It starts with urbex's own version, as [`urbex version`](#urbex-version) +prints it. Each check is `ok`, `warn`, `fail` or `skip`; a check that +isn't `ok` has its fix under it. On the lab: ``` +urbex 0.1.0 (commit 1a2b3c4, built 2026-11-20T10:00:00Z, linux/amd64) + tools: ok git git version 2.47.3 ok terraform Terraform v1.13.3 @@ -126,8 +130,8 @@ proxmox: ``` It exits non-zero when a check failed. `--output json` prints the report -as one JSON document, `{"checks": [{"group", "name", "status", "detail", -"fix"}], "ok": true}`, for the setup UI and the plugin +as one JSON document, `{"version", "checks": [{"group", "name", "status", +"detail", "fix"}], "ok": true}`, for the setup UI and the plugin ([ADR-0032](../decisions/0032-web-ui-console-ai-assistant.md)). ## `urbex discover` @@ -945,6 +949,39 @@ command is for: } ``` +## `urbex version` + +``` +urbex version [--output text|json] +urbex --version +``` + +Prints which build this is: say it in a bug report. A release says its +version; a build from source says `dev`, the commit and its date, and +`-dirty` if the tree had uncommitted changes: + +``` +$ urbex version +urbex 0.1.0 (commit 1a2b3c4, built 2026-11-20T10:00:00Z, linux/amd64) +$ urbex version # built from a checkout +urbex dev (commit 9df118e-dirty, committed 2026-11-16T17:38:34Z, linux/amd64) +``` + +`urbex --version` prints the same line. `--output json`: + +```json +{ + "version": "0.1.0", + "commit": "1a2b3c4d5e6f...", + "date": "2026-11-20T10:00:00Z", + "go": "go1.26.5", + "platform": "linux/amd64" +} +``` + +`date` is the build's, set by a release; a build from source has +`commit_date` instead, and `modified` when the tree had changes. + ## Progress events `urbex bootstrap`, `apply`, `destroy` and `teardown --yes` record their diff --git a/docs/status.md b/docs/status.md index 204e08b..c06ebea 100644 --- a/docs/status.md +++ b/docs/status.md @@ -22,6 +22,7 @@ Proxmox VE 9.2 node, see [What has been validated](#what-has-been-validated). | Area | State | |---|---| +| Distribution | Releases of `urbex-cli` ([v0.1.0](https://github.com/urbforge/urbex-cli/releases/tag/v0.1.0), a preview): `urbex` for Linux and macOS (amd64, arm64) with checksums and provenance, `urbex-op` and its image `ghcr.io/urbforge/urbex-op`; `urbex version`. Moving to a new release: [Upgrading](upgrading.md) | | App manifest (`urbex.yaml`) | Formal JSON Schema, typed Go decoding, `urbex init` scaffolds and validates | | Platform config (`urbex.platform.yaml`) | Scaffolded and validated by `urbex bootstrap` | | Credentials | Env vars, falling back to `~/.urbex/credentials.yaml`; never written to the GitOps repo | diff --git a/docs/upgrading.md b/docs/upgrading.md new file mode 100644 index 0000000..fc06d71 --- /dev/null +++ b/docs/upgrading.md @@ -0,0 +1,71 @@ +# Upgrading + +Urbex is released from [`urbforge/urbex-cli`](https://github.com/urbforge/urbex-cli/releases): +the `urbex` binaries, `urbex-op`, and its image +`ghcr.io/urbforge/urbex-op:`. Moving to a new release changes +the tools on your machine. The workspace, the GitOps repo, the platform +and your projects stay as they are. + +While Urbex is 0.x (a preview), a minor release may still change how +something works. **Read the release's notes first**: they say when a +command is needed after upgrading. + +## With urbex-op + +Download the new release's `urbex-op` over the old one. Its next command +pulls the new image: + +```sh +curl -fsSLo ~/bin/urbex-op https://github.com/urbforge/urbex-cli/releases/download/v0.2.0/urbex-op +urbex-op version # urbex-op 0.2.0, image ghcr.io/urbforge/urbex-op:0.2.0 +urbex-op 'urbex version' # pulls the image the first time +urbex-op 'urbex doctor' +``` + +Put the version you are moving to in the URL (`v0.2.0` above is an +example). The old image stays on your machine until you remove it, e.g. +`podman rmi ghcr.io/urbforge/urbex-op:0.1.0`. To go back, download the +old release's `urbex-op`. + +### From a checkout of urbex-cli + +If you ran Urbex before the first release, `urbex-op` is a link to a +checkout of `urbex-cli`, and its image is the one `urbex-op build` made. +Download the release's `urbex-op` in its place, as above. Unset +`URBEX_OPERATOR_IMAGE` if you set it: a release's `urbex-op` runs its own +image. The workspace stays the same. + +To keep working from the checkout instead (to work on urbex), pull it +and run `tools/operator/urbex-op build` again. + +## Native + +Download the new archive and replace `urbex`, as in +[Native tools](getting-started/with-the-cli.md#native-tools). Also check +that Terraform, Ansible, sops and age are at the versions the release's +`mise.toml` pins: `urbex doctor` lists them. + +## The Claude Code plugin + +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.0. + +### Plugin and CLI versions + +| Plugin | urbex | +|---|---| +| 0.2.0 | 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 +differ, update the plugin or use an `urbex` of the plugin's major. + +To update the plugin, refresh its marketplace in Claude Code: + +```text +/plugin marketplace update urbex +``` + +Then update `urbex` from the `/plugin` menu if it didn't update by +itself, and restart Claude Code. diff --git a/skills/cli/SKILL.md b/skills/cli/SKILL.md index 0614b63..f29c580 100644 --- a/skills/cli/SKILL.md +++ b/skills/cli/SKILL.md @@ -35,8 +35,9 @@ Find out once per session which way the user runs Urbex: urbex-op 'cd /work/projects/acme-app && urbex status staging' ``` The GitOps repo is `/work/gitops` there, `/gitops` on the - host. After updating the `urbex-cli` checkout, `urbex-op build` rebuilds - the image. + host. A release's `urbex-op` runs that release's image; to move to a + new release, see [Upgrading](${CLAUDE_PLUGIN_ROOT}/docs/upgrading.md). From a checkout of urbex-cli, + `urbex-op build` rebuilds the image after updating it. - **Native** (`command -v urbex`): run `urbex ...` in the project's folder, with `URBEX_GITOPS_REPO` set to the GitOps repo's working copy (or `--gitops-repo`). Credentials come from environment variables, then @@ -44,6 +45,24 @@ Find out once per session which way the user runs Urbex: Neither: use the `setup` skill. +## Versions + +This plugin (0.2.0) needs **urbex 0.1.0 or later, with the same major +version (0)**. Once per session, run `urbex version` (`urbex-op +'urbex version'`): + +- older than 0.1.0, or `urbex: unknown command "version"` (built before + versions existed): tell the user to upgrade, as + [Upgrading](${CLAUDE_PLUGIN_ROOT}/docs/upgrading.md) says, before going on; +- another major version (1.x): the plugin and the CLI don't match; + tell the user to update the plugin (`/plugin marketplace update urbex`) + or use a CLI of major 0; +- `dev` (built from source): fine, it is a checkout's `main`. + +The plugin and the CLI each have their own version: the plugin works +with any CLI of the same major. While both are 0.x a minor may still +break, hence the minimum. + ## Following a long command `bootstrap`, `apply`, `destroy` and `teardown --yes` take minutes, up to diff --git a/skills/setup/SKILL.md b/skills/setup/SKILL.md index 4db95a5..61be4be 100644 --- a/skills/setup/SKILL.md +++ b/skills/setup/SKILL.md @@ -61,11 +61,11 @@ before there is a token; from step 5, `urbex doctor` and `urbex discover` take over. - `check-prerequisites.sh`: git, ssh-keygen, python3 (3.8 or later), - podman or docker, an existing `urbex-op`, workspace or `urbex`, access - to `urbex-cli`. + podman or docker, an existing `urbex-op` (and its image), workspace or + `urbex`, urbex-cli's releases reachable. For a missing tool, say how to install it on the user's OS. podman or - docker is all Urbex needs; the native path (Go, Terraform, Ansible, - sops, age, through mise) is for users who can't run containers: see + docker is all Urbex needs; the native path (`urbex` from the + release, plus Terraform, Ansible, sops, age) is for users who can't run containers: see *Native tools* in `${CLAUDE_PLUGIN_ROOT}/docs/getting-started/with-the-cli.md`. - `discover-network.py` pings the LAN's addresses once (a /24 at most) and prints, as JSON, this machine's address, the LAN's CIDR, gateway and @@ -93,18 +93,25 @@ LAN, the free block you propose. Then ask only: ## 3. Get Urbex and the workspace -`urbex-cli` is private until the first release: the user needs access to -`github.com/urbforge/urbex-cli`. Clone it, by default in -`~/src/urbex-cli`, with the protocol that works (`gh repo clone -urbforge/urbex-cli`, or SSH). Then: +Download `urbex-op` from the newest release of `urbforge/urbex-cli` +(pre-releases included: while Urbex is 0.x every release is one, so +`releases/latest` finds none). It runs that release's image, +`ghcr.io/urbforge/urbex-op:`, and pulls it the first time: ```sh -cd ~/src/urbex-cli -tools/operator/urbex-op build # a few minutes the first time -mkdir -p ~/.local/bin && ln -sf "$PWD/tools/operator/urbex-op" ~/.local/bin/urbex-op -urbex-op -w ~/urbex-work init +tag=$(curl -fsSL 'https://api.github.com/repos/urbforge/urbex-cli/releases?per_page=1' \ + | python3 -c 'import json, sys; print(json.load(sys.stdin)[0]["tag_name"])') +mkdir -p ~/.local/bin +curl -fsSLo ~/.local/bin/urbex-op "https://github.com/urbforge/urbex-cli/releases/download/$tag/urbex-op" +chmod +x ~/.local/bin/urbex-op +urbex-op -w ~/urbex-work init # pulls the image the first time: a minute or two +urbex-op -w ~/urbex-work 'urbex version' ``` +Check the version as the `cli` skill's *Versions* says. If the user +already runs Urbex from a checkout of urbex-cli (`urbex-op` there, its +image built with `urbex-op build`), keep it: don't download over it. + - Check that `~/.local/bin` is on their `PATH`, and have them add `export URBEX_WORKSPACE=~/urbex-work` to their shell's profile. Your own shell doesn't keep variables between commands: use `urbex-op -w @@ -114,7 +121,7 @@ urbex-op -w ~/urbex-work init `~/urbex-work/home/age.key`** outside the workspace: every secret is encrypted to it, and it can't be recovered. -While the build runs, go on with step 4: the user can read it meanwhile. +While the image is pulled, go on with step 4: the user can read it meanwhile. ## 4. Prepare Proxmox and the tokens (the user) diff --git a/skills/setup/check-prerequisites.sh b/skills/setup/check-prerequisites.sh index 8d2935c..31526ba 100755 --- a/skills/setup/check-prerequisites.sh +++ b/skills/setup/check-prerequisites.sh @@ -40,7 +40,7 @@ else if [ "$native" = 1 ]; then warn "no podman or docker: the native tools are there, use the native path" else - miss "podman or docker (or the native tools: Go, terraform, ansible-core, sops, age)" + miss "podman or docker (or the native tools: urbex, terraform, ansible-core, sops, age)" fi fi @@ -48,12 +48,17 @@ if command -v urbex-op >/dev/null; then ok "urbex-op on the PATH: $(command -v urbex-op)" ws=${URBEX_WORKSPACE:-$HOME/urbex-workspace} if [ -d "$ws/home" ]; then ok "workspace: $ws"; else warn "no workspace at $ws yet (urbex-op init)"; fi - if [ -n "$engine" ] && "$engine" image exists "${URBEX_OPERATOR_IMAGE:-urbex-operator}" 2>/dev/null; then - ok "operator image ${URBEX_OPERATOR_IMAGE:-urbex-operator}" - elif [ "$engine" = docker ] && docker image inspect "${URBEX_OPERATOR_IMAGE:-urbex-operator}" >/dev/null 2>&1; then - ok "operator image ${URBEX_OPERATOR_IMAGE:-urbex-operator}" + # A release's urbex-op names its image ("urbex-op 0.1.0, image ghcr.io/..."); one from + # before releases has no version command and runs the image urbex-op build makes. + image=$(urbex-op version 2>/dev/null | sed -n 's/^urbex-op .*, image //p') + image=${image:-${URBEX_OPERATOR_IMAGE:-urbex-operator}} + if [ -n "$engine" ] && "$engine" image inspect "$image" >/dev/null 2>&1; then + ok "operator image $image" else - warn "no operator image yet (urbex-op build)" + case "$image" in + */*) warn "operator image $image not pulled yet (urbex-op init pulls it)" ;; + *) warn "no operator image $image yet (urbex-op build in the urbex-cli checkout)" ;; + esac fi elif command -v urbex >/dev/null; then ok "urbex on the PATH (native): $(command -v urbex)" @@ -61,11 +66,11 @@ else warn "urbex is not installed yet" fi -# urbex-cli is private until the first release: cloning it needs access. -if GIT_TERMINAL_PROMPT=0 git ls-remote https://github.com/urbforge/urbex-cli.git HEAD >/dev/null 2>&1; then - ok "access to github.com/urbforge/urbex-cli" +# urbex-op and urbex come from urbex-cli's releases. +if curl -fsS -o /dev/null --max-time 10 'https://api.github.com/repos/urbforge/urbex-cli/releases?per_page=1'; then + ok "urbex-cli's releases reachable on github.com" else - warn "can't read github.com/urbforge/urbex-cli over HTTPS without credentials: it is private until the first release (fine if you clone it with SSH or gh)" + warn "can't reach urbex-cli's releases (api.github.com): urbex-op is downloaded from there" fi if [ $# -ge 1 ] && [ -n "$1" ]; then