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.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",
Expand Down
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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**.
Expand All @@ -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
Expand Down
6 changes: 3 additions & 3 deletions docs/demo/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
22 changes: 18 additions & 4 deletions docs/getting-started/with-claude-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand Down
7 changes: 5 additions & 2 deletions docs/getting-started/with-the-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:

```
Expand Down
4 changes: 2 additions & 2 deletions docs/upgrading.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
11 changes: 7 additions & 4 deletions skills/cli/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 '<commands>'`, 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
Expand All @@ -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'`):

Expand All @@ -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
Expand Down
19 changes: 12 additions & 7 deletions skills/setup/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion skills/setup/check-prerequisites.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down