diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 93dd1fd..bb4a466 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "urbex", - "version": "0.2.1", + "version": "0.2.2", "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/CHANGELOG.md b/CHANGELOG.md index 4ea7579..6edc9e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,16 @@ workflow refuses a tag whose version has no entry here. ## [Unreleased] +### Plugin 0.2.2 + +Needs **urbex 0.1.0 or later, major 0**. + +- **Changed**: the `setup` skill goes on without Cloudflare and mentions + the options, asking only when the user wants public addresses; the + durations the skills give are the test node's (a first bootstrap about + 20 minutes, a first apply about 6); the default workspace is + `~/urbex-work`, as `urbex-op`'s (urbforge/urbex#57). + ### Plugin 0.2.1 Needs **urbex 0.1.0 or later, major 0**. @@ -30,6 +40,10 @@ Needs **urbex 0.1.0 or later, major 0**. ### Docs +- **Changed**: getting started installs the plugin from the terminal too + (`claude plugin ...`, then `/reload-plugins`), and gives the test + node's durations; the default workspace is `~/urbex-work` everywhere. + - **Added**: [ADR-0034](docs/decisions/0034-forgejo-lts-forge.md) - Forgejo LTS is the platform's forge, in place of Gitea; the known limitation for platforms installed with 0.1.0, which stay on Gitea diff --git a/docs/demo/README.md b/docs/demo/README.md index e8cea41..a4f3112 100644 --- a/docs/demo/README.md +++ b/docs/demo/README.md @@ -31,14 +31,14 @@ the operator image of `urbex-cli` (`mise run operator-image`). On the platform, the project `demo` must not exist yet. ```sh -URBEX_OPERATOR_IMAGE=urbex-operator docs/demo/record.sh ~/urbex-workspace +URBEX_OPERATOR_IMAGE=urbex-operator docs/demo/record.sh ~/urbex-work ``` It takes about 15 minutes, nearly all of it the first `apply` (the LXCs, Komodo, the build of `main`). Then remove the project: ```sh -cd ~/urbex-workspace/demo/app && urbex destroy staging && urbex destroy prod +cd ~/urbex-work/demo/app && urbex destroy staging && urbex destroy prod ``` `claude.gif` the same way, on a fresh project again, with your Claude @@ -47,7 +47,7 @@ Code login: ```sh claude setup-token # once: a token for scripts, then export CLAUDE_CODE_OAUTH_TOKEN=... # (or nothing: a copy of ~/.claude/.credentials.json is used) -URBEX_OPERATOR_IMAGE=urbex-operator docs/demo/record.sh ~/urbex-workspace claude +URBEX_OPERATOR_IMAGE=urbex-operator docs/demo/record.sh ~/urbex-work claude ``` The login goes into the workspace's `demo/claude-home` for the recording diff --git a/docs/getting-started/with-claude-code.md b/docs/getting-started/with-claude-code.md index 00b68b9..4cdedf6 100644 --- a/docs/getting-started/with-claude-code.md +++ b/docs/getting-started/with-claude-code.md @@ -20,7 +20,19 @@ In Claude Code, run these two commands one at a time: ``` From the `/plugin` menu instead, choose *Add Marketplace* and enter only -`urbforge/urbex`; then install `urbex` from the marketplace's list. +`urbforge/urbex`; then install `urbex` from the marketplace's list. Or, +from your terminal rather than inside Claude Code, one at a time: + +```sh +claude plugin marketplace add urbforge/urbex +``` + +```sh +claude plugin install urbex@urbex +``` + +Claude Code sees a new plugin's skills after `/reload-plugins`, or when +you start it again. It also needs `python3`, 3.8 or later, on your machine, for the scripts that find your settings. `urbex` itself comes from the releases of @@ -43,8 +55,9 @@ Or ask in plain words: "set up Urbex on my Proxmox node". What happens: machine, your LAN's CIDR, gateway and DNS, the Proxmox nodes on the LAN, and a block of free addresses. To find the free addresses, it 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. +2. **It goes on without Cloudflare** - everything on the LAN - and says + it can be added later: a Quick Tunnel, or your own zone. It asks only + if you've said you want your apps reachable from the internet. 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 @@ -71,7 +84,8 @@ Or ask in plain words: "set up Urbex on my Proxmox node". What happens: each value comes from. Check that the address block is outside your DHCP range: nothing else can check that. 6. **It asks before `urbex bootstrap`**, then follows it, for about - twenty minutes, and gives you the platform's addresses. + twenty minutes (1212 s on our test node), and gives you the + platform's addresses. 7. **Your first app**: give it the repository's URL or path. It writes `urbex.yaml` from the code, shows it to you, and deploys the app to staging. diff --git a/docs/getting-started/with-the-cli.md b/docs/getting-started/with-the-cli.md index 31e28e9..216727c 100644 --- a/docs/getting-started/with-the-cli.md +++ b/docs/getting-started/with-the-cli.md @@ -69,7 +69,8 @@ Then run it again: urbex-op 'urbex bootstrap' ``` -It takes about twenty minutes. It creates the platform's LXCs (Forgejo, +It takes about twenty minutes (1212 s on our test node, a quarter of it +for the LXC template). It creates the platform's LXCs (Forgejo, Komodo, Technitium, Keycloak, observability, and the tunnel when Cloudflare is configured), configures them and connects them. At the end it prints the address of each service. The `urbex-admin` passwords are in @@ -109,7 +110,9 @@ urbex-op 'cd /work/projects/acme-app && urbex apply staging' ``` It creates the LXC, the repository on Forgejo from your local `main`, the -build and the deploy, then builds `main` and deploys it. It prints the +build and the deploy, then builds `main` and deploys it: about six +minutes the first time (342 s on our test node, for two services), a +minute or two afterwards. It prints the address of each service: ``` diff --git a/docs/upgrading.md b/docs/upgrading.md index 37ce25e..e137d21 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -51,13 +51,13 @@ 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.2. ### Plugin and CLI versions | Plugin | urbex | |---|---| -| 0.2.0, 0.2.1 | 0.1.0 or later, major 0 | +| 0.2.0, 0.2.1, 0.2.2 | 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 diff --git a/skills/cli/SKILL.md b/skills/cli/SKILL.md index 0360f78..655c8ea 100644 --- a/skills/cli/SKILL.md +++ b/skills/cli/SKILL.md @@ -26,7 +26,7 @@ Find out once per session which way the user runs Urbex: - **Container** (`command -v urbex-op`): every command runs as `urbex-op ''`, against the workspace in `$URBEX_WORKSPACE` - (default `~/urbex-workspace`), mounted at `/work`. Your shell doesn't + (default `~/urbex-work`; `~/urbex-workspace` with an older `urbex-op`), mounted at `/work`. Your shell doesn't keep variables between commands, so pass it each time (`urbex-op -w ~/urbex-work '...'`) if it isn't in the user's profile. Project commands run in the project's folder, which must be inside the @@ -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.2) needs **urbex 0.1.0 or later, with the same major version (0)**. Once per session, run `urbex version` (`urbex-op 'urbex version'`): @@ -65,8 +65,11 @@ break, hence the minimum. ## Following a long command -`bootstrap`, `apply`, `destroy` and `teardown --yes` take minutes, up to -twenty. Run them with `--events json`, in the background (a background +`bootstrap`, `apply`, `destroy` and `teardown --yes` take minutes. On the +test node: a first `bootstrap` about 20 minutes (1212 s), a first `apply` +of an environment about 6 (342 s: its LXCs, the build, the deploy), a +later `apply` a minute or two, `promote` under 2, `destroy` about one, +`teardown` about two. Run them with `--events json`, in the background (a background task, or a watch whose events are the command's lines): ```sh diff --git a/skills/setup/SKILL.md b/skills/setup/SKILL.md index 7901fd9..864b46e 100644 --- a/skills/setup/SKILL.md +++ b/skills/setup/SKILL.md @@ -80,16 +80,19 @@ An existing workspace (`~/urbex-work`, `$URBEX_WORKSPACE`) with a `gitops/urbex.platform.yaml` means a platform may already exist: read that file and go on from where it is, instead of starting over. -## 2. One short question +## 2. What you found, and Cloudflare Tell the user, in a few lines, what you found: the Proxmox node (when there is one candidate; when several, list them and propose one), the -LAN, the free block you propose. Then ask only: +LAN, the free block you propose. -- **Cloudflare**: none (everything on the LAN, the default), a Quick - Tunnel (public `*.trycloudflare.com` addresses, no account), or their - own zone (public HTTPS on their domain, Forgejo and Komodo behind - Cloudflare Access). It can be added later. +**Cloudflare: none, unless the user asks for public addresses.** Go on +without it - everything on the LAN - and say in one line that it can be +added later, with the two options: a Quick Tunnel (public +`*.trycloudflare.com` addresses, no account) or their own zone (public +HTTPS on their domain, Forgejo and Komodo behind Cloudflare Access). +Ask which one only when the user has said they want their apps reachable +from the internet, or named a domain on Cloudflare. ## 3. Get Urbex and the workspace @@ -277,7 +280,9 @@ then: urbex-op -w ~/urbex-work 'urbex bootstrap --events json' ``` -It takes about twenty minutes: run it with `--events json` in the +It takes about twenty minutes the first time (1212 s on the test node, +233 s of them for the LXC template), a minute or two when it runs again: +run it with `--events json` in the background, as the `cli` skill says (*Following a long command*), telling the user each phase as it ends. Re-running it is safe, and is how a failed run resumes. When an error names a cause, fix it and run it again; the diff --git a/skills/setup/check-prerequisites.sh b/skills/setup/check-prerequisites.sh index 31526ba..d570948 100755 --- a/skills/setup/check-prerequisites.sh +++ b/skills/setup/check-prerequisites.sh @@ -46,7 +46,9 @@ fi if command -v urbex-op >/dev/null; then ok "urbex-op on the PATH: $(command -v urbex-op)" - ws=${URBEX_WORKSPACE:-$HOME/urbex-workspace} + # urbex-op's default: ~/urbex-work, or ~/urbex-workspace (urbex 0.1's) if only that exists. + ws=${URBEX_WORKSPACE:-$HOME/urbex-work} + if [ -z "${URBEX_WORKSPACE:-}" ] && [ ! -d "$ws" ] && [ -d "$HOME/urbex-workspace/home" ]; then ws=$HOME/urbex-workspace; fi if [ -d "$ws/home" ]; then ok "workspace: $ws"; else warn "no workspace at $ws yet (urbex-op init)"; fi # 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.