From f8975a1421a21531313668b982efa7455fd5258c Mon Sep 17 00:00:00 2001 From: Teg79 Date: Tue, 17 Nov 2026 17:12:10 +0100 Subject: [PATCH 1/2] docs: Forgejo LTS is the platform's forge (ADR-0034) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0182yxsfwRowwnxCfgrQwjnA --- .claude-plugin/plugin.json | 2 +- README.md | 14 +-- docs/architecture.md | 34 +++---- docs/cookbook.md | 24 ++--- docs/decisions/0004-gitops-gitea-komodo.md | 2 +- .../0018-image-build-komodo-gitea-registry.md | 2 +- docs/decisions/0034-forgejo-lts-forge.md | 96 +++++++++++++++++++ docs/getting-started.md | 8 +- docs/getting-started/with-the-cli.md | 8 +- docs/known-limitations.md | 17 ++-- docs/reference/README.md | 2 +- docs/reference/cli.md | 58 +++++------ docs/reference/credentials.md | 25 +++-- docs/reference/gitops-repo.md | 6 +- docs/reference/manifest.md | 2 +- docs/reference/platform-config.md | 12 +-- docs/reference/platform-resources.md | 18 ++-- docs/reference/startup.md | 10 +- docs/roadmap.md | 14 +-- docs/status.md | 28 +++--- docs/upgrading.md | 4 +- skills/cli/SKILL.md | 12 +-- skills/setup/SKILL.md | 12 +-- 23 files changed, 257 insertions(+), 153 deletions(-) create mode 100644 docs/decisions/0034-forgejo-lts-forge.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 7a644ab..93dd1fd 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "urbex", - "version": "0.2.0", + "version": "0.2.1", "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 e568e1c..c3f2176 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ You don't need a Cloudflare account: `cloudflare.quickTunnel: true` gives every public service a `*.trycloudflare.com` address ([ADR-0025](docs/decisions/0025-cloudflare-quick-tunnel.md)); it is for trying Urbex, not for production. `domain` in `urbex.platform.yaml` is -still required (the Gitea admin's e-mail, the default of `dns.zone`). A +still required (the Forgejo admin's e-mail, the default of `dns.zone`). A domain on Cloudflare gives you stable public names and Access in front of the admin tools. @@ -108,7 +108,7 @@ like Claude Code or Codex can use ## How it works Urbex runs on a server you already have - a Proxmox node today - and -installs the platform's services there: Gitea for the repositories, +installs the platform's services there: Forgejo for the repositories, Komodo for builds and deploys, Technitium for internal DNS, Keycloak for identity, Prometheus, Loki and Grafana for monitoring, and Cloudflare for public access. A project - web frontends deployed to Cloudflare Workers, @@ -119,13 +119,13 @@ creates and keeps what it needs in every environment. ## What works today The `urbex` CLI implements it: bootstrap -sets up Gitea and Komodo; projects are developed trunk-based, and every +sets up Forgejo and Komodo; projects are developed trunk-based, and every push to `main` is built by Komodo and deployed to staging; releases are tags, promoted to production; and each environment runs what its folder in the GitOps repo says - version, configuration, SOPS-encrypted secrets - deployed by Komodo on every change. With Cloudflare, public APIs go out through a Cloudflare Tunnel, web frontends are deployed to -Cloudflare Workers, Keycloak is public, and Gitea and Komodo sit behind +Cloudflare Workers, Keycloak is public, and Forgejo and Komodo sit behind Cloudflare Access; every service also gets an internal DNS name in Technitium, independently of Cloudflare. Without a Cloudflare account, `cloudflare.quickTunnel: true` exposes every public service on a @@ -156,7 +156,7 @@ supported/not-supported breakdown and implementation priorities, and - Every project service runs in a dedicated **LXC** (Debian 13), as a container Komodo builds from the project's Git repo and rolls out. - Platform services (created on-demand if missing): - - **Gitea** — self-hosted Git server (app repos + GitOps repo). + - **Forgejo** — self-hosted Git server (app repos + GitOps repo). - **Komodo** — build/update pipeline and LXC management. - **Technitium DNS** — internal name resolution between services. - **Keycloak** — identity provider (SSO for admin tools and OIDC for @@ -175,7 +175,7 @@ supported/not-supported breakdown and implementation priorities, and ## Future evolutions (v2+) - Cloud providers beyond Proxmox: Azure, GCP, AWS. -- Git servers beyond Gitea: GitHub, GitLab. +- Git servers beyond Forgejo: GitHub, GitLab. - Secrets management: optional HashiCorp Vault support alongside SOPS+age. ## Use Urbex from Claude Code @@ -264,7 +264,7 @@ Reference ([index](docs/reference/)): - [Credentials](docs/reference/credentials.md) — every credential and how to get it. - [Platform resources](docs/reference/platform-resources.md) — what Urbex - creates on Proxmox, Gitea, and Komodo. + creates on Proxmox, Forgejo, and Komodo. Design and planning: diff --git a/docs/architecture.md b/docs/architecture.md index 2687d1c..8edba02 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -8,12 +8,12 @@ flowchart TB CLI[urbex CLI] end - subgraph AppRepo["App repo (on Gitea)"] + subgraph AppRepo["App repo (on Forgejo)"] Manifest[urbex.yaml] Code[App code] end - subgraph GitOpsRepo["GitOps repo (on Gitea)"] + subgraph GitOpsRepo["GitOps repo (on Forgejo)"] TF[Terraform/OpenTofu] ANS[Ansible] ENVS[environments/: versions, config, SOPS secrets] @@ -21,7 +21,7 @@ flowchart TB subgraph Proxmox["Proxmox server"] subgraph Base["Base services LXCs"] - Gitea + Forgejo Komodo Technitium[Technitium DNS] Keycloak @@ -57,7 +57,7 @@ flowchart TB ANS -->|configures| Base ANS -->|configures| Staging ANS -->|configures| Prod - Gitea -->|GitOps repo + app repo| GitOpsRepo + Forgejo -->|GitOps repo + app repo| GitOpsRepo Komodo -->|deploys environments/staging| SvcS Komodo -->|deploys environments/prod| SvcP Technitium -->|resolves internal names| Base @@ -85,7 +85,7 @@ command and flag is in the [CLI reference](reference/cli.md). | Command | Purpose | |---|---| -| `urbex bootstrap` | Provisions the base services on a fresh Proxmox (Gitea, Komodo, Technitium, Keycloak, Prometheus/Grafana/Loki) and initializes the GitOps repo. See [ADR-0006](decisions/0006-bootstrap-command.md). | +| `urbex bootstrap` | Provisions the base services on a fresh Proxmox (Forgejo, Komodo, Technitium, Keycloak, Prometheus/Grafana/Loki) and initializes the GitOps repo. See [ADR-0006](decisions/0006-bootstrap-command.md). | | `urbex init` | Generates/validates `urbex.yaml` in the app repo, typically run by the LLM after analyzing the project code. | | `urbex plan ` | Computes the infrastructure changes needed (Terraform diff + Ansible config) for an environment, without applying them. | | `urbex apply ` | Applies the planned changes: creates/updates LXCs, connects them to Komodo, declares the project's builds and the environment's folder and stacks, registers each service's internal DNS name in Technitium and, with Cloudflare, its public route; a new staging starts following `main`. | @@ -111,23 +111,23 @@ storage) with tracked state; Ansible configures the inside of the LXCs Technitium/Keycloak). LXCs run Debian 13. See [ADR-0003](decisions/0003-terraform-ansible-provisioning.md). -### GitOps: repo on Gitea + Komodo +### GitOps: repo on Forgejo + Komodo Everything that defines the platform and what runs on it is versioned -in a GitOps repo hosted on a self-hosted Gitea instance on the same +in a GitOps repo hosted on a self-hosted Forgejo instance on the same Proxmox: the infrastructure (Terraform definitions and state, Ansible playbooks) and, under `environments/`, one folder per environment with each service's compose file, configuration, encrypted secrets, and the -version to deploy. App repos live on the same Gitea. +version to deploy. App repos live on the same Forgejo. Komodo is the build and rollout engine. It builds each service's image -from the app repo on every push to `main`, pushes it to Gitea's +from the app repo on every push to `main`, pushes it to Forgejo's container registry, and deploys each environment folder of the GitOps repo on the service's LXC, through the Periphery agent installed there, whenever the folder changes. An application that uses others waits, in its own Stack, until what it uses is healthy, and a Komodo Action, the reconciler, deploys it again when it could not start -([ADR-0031](decisions/0031-readiness-between-stacks.md)). What Urbex creates in Gitea and Komodo is +([ADR-0031](decisions/0031-readiness-between-stacks.md)). What Urbex creates in Forgejo and Komodo is listed in [platform resources](reference/platform-resources.md); the repo's layout and files in the [GitOps repo reference](reference/gitops-repo.md). See [ADR-0004](decisions/0004-gitops-gitea-komodo.md), @@ -197,7 +197,7 @@ Registration doesn't depend on Cloudflare being configured. See A single Keycloak, three uses: -1. SSO for admin UIs (Komodo, Grafana, Gitea, Technitium). +1. SSO for admin UIs (Komodo, Grafana, Forgejo, Technitium). 2. OIDC provider for dev apps (apps register as clients). 3. Service APIs are protected by roles defined in Keycloak. @@ -237,10 +237,10 @@ very image staging ran. ```mermaid sequenceDiagram participant Dev as Dev / agent - participant Repo as acme-app (Gitea) + participant Repo as acme-app (Forgejo) participant K as Komodo - participant Reg as Registry (Gitea) - participant G as gitops (Gitea) + participant Reg as Registry (Forgejo) + participant G as gitops (Forgejo) participant S as staging LXC participant P as prod LXC Dev->>Repo: git push main @@ -299,12 +299,12 @@ secrets. See ## Bootstrap vs steady-state Urbex operates in two distinct modes, to solve the chicken-and-egg problem -(the GitOps repo that is supposed to manage Gitea cannot exist before -Gitea exists): +(the GitOps repo that is supposed to manage Forgejo cannot exist before +Forgejo exists): 1. **Bootstrap** (`urbex bootstrap`): runs Terraform+Ansible directly against the Proxmox API to create the base services and the first - Gitea repo, then pushes the initial state to it as the GitOps repo. + Forgejo repo, then pushes the initial state to it as the GitOps repo. 2. **Steady-state**: from that point on, every change (new project, new environment, base service update) goes through a commit to the GitOps repo + reconciliation via Komodo/CLI. diff --git a/docs/cookbook.md b/docs/cookbook.md index 1f32467..f6389fc 100644 --- a/docs/cookbook.md +++ b/docs/cookbook.md @@ -5,7 +5,7 @@ Each one says what to run and what happens; details of every command are in the [CLI reference](reference/cli.md), of every file in [the GitOps repo reference](reference/gitops-repo.md). -The examples use project `acme-app` with a service `api`, Gitea at +The examples use project `acme-app` with a service `api`, Forgejo at `192.168.1.200:3000`, and `URBEX_GITOPS_REPO` pointing at your working copy of the GitOps repo. @@ -26,7 +26,7 @@ copy of the GitOps repo. - [Put the platform on the internet](#put-the-platform-on-the-internet) - [Publish a service](#publish-a-service) - [Deploy a web frontend](#deploy-a-web-frontend) -- [Let someone else into Gitea and Komodo](#let-someone-else-into-gitea-and-komodo) +- [Let someone else into Forgejo and Komodo](#let-someone-else-into-forgejo-and-komodo) - [Protect an endpoint with a role](#protect-an-endpoint-with-a-role) **Configuration and secrets** @@ -198,7 +198,7 @@ prod --version ` works, but skips the release - avoid it. `urbex promote` and `urbex deploy prod` commit straight to the GitOps repo. To have production changes reviewed instead: -1. In Gitea, add a branch protection rule on `main` of `urbex/gitops` +1. In Forgejo, add a branch protection rule on `main` of `urbex/gitops` with **protected file patterns** `environments/prod/**`: direct pushes touching prod are refused, pull requests are not. Staging, which Komodo and `urbex` update directly, keeps working. @@ -232,7 +232,7 @@ urbex bootstrap ``` Published on Cloudflare: Keycloak https://auth-urbex.example.com (its admin console behind Access), webhooks https://hooks-urbex.example.com; -behind Access: Gitea https://git-urbex.example.com, Komodo https://komodo-urbex.example.com, Technitium https://dns-urbex.example.com, Grafana https://grafana-urbex.example.com, Prometheus https://prometheus-urbex.example.com, Loki https://loki-urbex.example.com. +behind Access: Forgejo https://git-urbex.example.com, Komodo https://komodo-urbex.example.com, Technitium https://dns-urbex.example.com, Grafana https://grafana-urbex.example.com, Prometheus https://prometheus-urbex.example.com, Loki https://loki-urbex.example.com. ``` Bootstrap adds a small LXC running `cloudflared`, sets up Access first @@ -286,11 +286,11 @@ staging serves it at `https://staging-acme-app-urbex.example.com`. rolls it back. Each environment is a Cloudflare Worker with static assets, `urbex-acme-app-web-`; unknown paths serve `index.html`. -## Let someone else into Gitea and Komodo +## Let someone else into Forgejo and Komodo Add their e-mail to `cloudflare.access.emails` and run `urbex bootstrap`. They open `https://git-urbex.example.com`, enter the address, and get a -PIN by e-mail. That opens the door; Gitea and Komodo still ask for their +PIN by e-mail. That opens the door; Forgejo and Komodo still ask for their own login (`urbex-admin`, or accounts you create in them). ## Protect an endpoint with a role @@ -876,7 +876,7 @@ folders, destroys its LXCs, and frees their addresses. An environment with named volumes needs `--delete-data`, which deletes them with the LXCs. With the last environment gone, the project's Builds and webhook go too. The repo and -its images stay on Gitea - delete them there if you want them gone. +its images stay on Forgejo - delete them there if you want them gone. ## Remove the whole platform @@ -889,7 +889,7 @@ urbex teardown --yes # destroys the base-service LXCs and urbex's LXC templ ``` `teardown` refuses while any project environment exists. It destroys -Gitea's LXC, and with it every repository and image there: make sure +Forgejo's LXC, and with it every repository and image there: make sure project repos are pushed somewhere else first. urbex's LXC template (`vmIdBase+90` onwards) goes too. Afterwards the GitOps repo's working copy is the only copy left - keep it - and `~/.urbex/credentials.yaml` @@ -903,7 +903,7 @@ urbex status # the platform and every project environment urbex status staging # one project's environment, from its folder ``` -`urbex status` lists every address of the platform - Gitea, Komodo and +`urbex status` lists every address of the platform - Forgejo, Komodo and its webhooks, Keycloak, Technitium, Grafana, Prometheus, Loki - on the LAN and, with Cloudflare, on the internet, where the logins are, and then every project environment in the GitOps repo with each service's @@ -919,7 +919,7 @@ the default `flat` names under `example.com`, | | Address | |---|---| -| Keycloak / Gitea / Komodo | `https://auth-urbex.example.com`, `git-urbex`, `komodo-urbex` | +| Keycloak / Forgejo / Komodo | `https://auth-urbex.example.com`, `git-urbex`, `komodo-urbex` | | An API, staging / prod | `https://api-staging-acme-app-urbex.example.com`, `https://api-acme-app-urbex.example.com` | | The web frontend, staging / prod | `https://staging-acme-app-urbex.example.com`, `https://acme-app-urbex.example.com` | | A service on the LAN | `http://:` - `state/allocations.json` in the GitOps repo | @@ -928,7 +928,7 @@ the default `flat` names under `example.com`, Every service has an internal name in Technitium, whether or not Cloudflare is configured: `api.staging.acme-app.urbex.example.com` for -a project service, `git.urbex.example.com` for Gitea - `urbex status` +a project service, `git.urbex.example.com` for Forgejo - `urbex status` lists them ([ADR-0027](decisions/0027-service-conventions.md)). The LXCs resolve through Technitium already; from your own machine: @@ -1114,7 +1114,7 @@ Common causes: the build fails (the Dockerfile, or the conventions of a on `$PORT`; the healthcheck path is wrong, so the container stays unhealthy and `urbex` keeps waiting until it times out. -To redo a release whose Action run failed, delete the tag in Gitea and +To redo a release whose Action run failed, delete the tag in Forgejo and create it again (`urbex release --version --ref `). A tag pushed while `main` is still building that commit is fine: runs of the Action queue up. diff --git a/docs/decisions/0004-gitops-gitea-komodo.md b/docs/decisions/0004-gitops-gitea-komodo.md index 6d56fd4..a144432 100644 --- a/docs/decisions/0004-gitops-gitea-komodo.md +++ b/docs/decisions/0004-gitops-gitea-komodo.md @@ -2,7 +2,7 @@ ## Status -Accepted +Accepted. The forge is now Forgejo LTS ([ADR-0034](0034-forgejo-lts-forge.md)): where this ADR says Gitea, read Forgejo. ## Context diff --git a/docs/decisions/0018-image-build-komodo-gitea-registry.md b/docs/decisions/0018-image-build-komodo-gitea-registry.md index 8fecd96..c4699cf 100644 --- a/docs/decisions/0018-image-build-komodo-gitea-registry.md +++ b/docs/decisions/0018-image-build-komodo-gitea-registry.md @@ -6,7 +6,7 @@ Accepted - implemented in `urbforge/urbex-cli`. Registry, builder, Dockerfiles, and the HTTP/insecure-registry consequences stand. What triggers a build, how images are tagged, and how they are rolled out are decided by [ADR-0020](0020-trunk-releases-gitops-environments.md): one -image per release tag, deployed by Komodo from the GitOps repo. +image per release tag, deployed by Komodo from the GitOps repo. The forge is now Forgejo LTS ([ADR-0034](0034-forgejo-lts-forge.md)): where this ADR says Gitea, read Forgejo. ## Context diff --git a/docs/decisions/0034-forgejo-lts-forge.md b/docs/decisions/0034-forgejo-lts-forge.md new file mode 100644 index 0000000..52164d8 --- /dev/null +++ b/docs/decisions/0034-forgejo-lts-forge.md @@ -0,0 +1,96 @@ +# ADR-0034: Forgejo LTS is the platform's forge + +## Status + +Accepted. Changes [ADR-0004](0004-gitops-gitea-komodo.md) and +[ADR-0018](0018-image-build-komodo-gitea-registry.md): where they say +Gitea, the forge is now Forgejo; everything else they decide stands. + +## Context + +The platform's Git forge holds the GitOps repo, the projects' repos and +their container images (ADR-0004, ADR-0018). Until urbex 0.1.0 it was +`gitea/gitea:1.24`, not pinned by digest, and out of support: Gitea +supports its last two majors (28 and 27). It had to move before the +first testers install a platform. + +Two candidates, both Apache/MIT-licensed and close to each other +(Forgejo is a hard fork of Gitea): + +- **Gitea 28**: maintained, and adds bot accounts and an audit log, + useful for the operators' work of E7 (after M5). +- **Forgejo 15**: a long-term-support release, supported until + 15 July 2027, with a stable release every quarter besides. + +Homelab users update rarely: 47% by hand (selfh.st survey 2026). Among +self-hosters Forgejo grew to 27% (15% in 2025), Gitea fell to 17% (21%) +(urbforge/redemptor#49). + +Urbex uses little of the forge (`internal/forge` in urbex-cli): the REST +API `/api/v1` (version, tokens with basic auth, orgs, repos, branches, +commits, tags, webhooks, container packages), push webhooks to Komodo +(type `gitea`, signed with `X-Hub-Signature-256`, which Forgejo sends +too), and the container registry. Not Actions, OAuth or mirrors. + +A spike (urbforge/urbex-cli#112) swapped the image for +`codeberg.org/forgejo/forgejo:15.0.11`, pinned by digest, with the +settings as `FORGEJO__*`, and nothing else: + +- urbex-cli's end-to-end test passed whole (24 steps: bootstrap, apply + with webhook, build, registry and deploy, release, promote, status, + volumes, linked applications, the reconciler, destroy, teardown), as + it does with Gitea 1.24. The forge container's memory over the run: + median 106 MiB, peak 196 MiB with Forgejo; 101 and 181 MiB with Gitea. +- On the test Proxmox node, a platform bootstrapped from scratch with + Forgejo, then a project in staging and production. The forge LXC: + 150-160 MiB for the forge, about 300 MiB for the whole LXC (Gitea: + 124 and 316 MiB on a platform weeks old), 1.8 GB of disk (2.2 GB). + +## Decision + +- **Forgejo LTS is the platform's forge**: today + `codeberg.org/forgejo/forgejo:15.0.11`, pinned by digest, configured + with `FORGEJO__*` variables. +- **Following its releases**: each urbex release pins the newest patch + of the current LTS (15.0.x) by digest; an urbex release moves to the + next LTS before the current one reaches its end of support. Forgejo's + quarterly releases in between are not followed. +- **Names**: in the code, the messages and the docs, the generic word + is *forge* (*Forgejo* when the product is meant): urbex-cli's package + `internal/forge`; the credentials `forgeAdminPassword` and + `forgeToken` (`URBEX_FORGE_*`); the platform config's `git.forgeUrl`. + The old names - `giteaAdminPassword`, `giteaToken`, `URBEX_GITEA_*`, + `git.giteaUrl` - are still read, so a workspace written by 0.1.0 + works unchanged; urbex writes the new ones. +- **What keeps its name**: what a platform already has on Proxmox and + Komodo - the LXC `urbex-gitea`, the Stack `urbex-gitea`, its volume + `gitea-data`, the service `gitea` in the catalog and in Grafana's + labels, the webhook type `gitea`, and Komodo's variables + `URBEX_GITEA_URL`, `URBEX_GITEA_USER` and `URBEX_GITEA_TOKEN`, which + the Actions installed on a platform read. Renaming them would replace the LXC + of every existing platform; a migration may do it later. +- **Gitea 28 is the fallback**: the API Urbex uses is the same, so going + back is the image and the variables, as the spike was. + +## Rationale + +- A support window measured in years fits users who update twice a + year; Gitea's two-major window doesn't. +- Forgejo is what more self-hosters now run, and it is a community + project under Codeberg e.V. +- The spike changed no code: the risk of the switch is low, and so is + the cost of going back. +- Generic names in the code keep the next change of forge, if any, as + small as this one. + +## Consequences + +- We give up, for now, Gitea 28's bot accounts and audit log. E7 looks + at what Forgejo offers when it starts. +- **A platform installed with urbex 0.1.0 runs Gitea 1.24 and isn't + migrated in place**: Forgejo imports Gitea's database only up to Gitea + 1.22. Bootstrap the platform again, or push its repos to the new + forge (see the known limitations). +- The image comes from codeberg.org instead of Docker Hub. +- Upgrading the forge is an urbex release; between releases nothing + changes on a platform. diff --git a/docs/getting-started.md b/docs/getting-started.md index ebac534..f1b67ad 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -21,16 +21,16 @@ first time, most of it spent waiting for downloads. ``` your machine (or an agent) Proxmox ┌───────────────────────┐ ┌──────────────────────────────────────────┐ - │ acme-app working copy │ │ platform: Gitea, Komodo, Technitium, │ + │ acme-app working copy │ │ platform: Forgejo, Komodo, Technitium, │ │ urbex.yaml │──▶│ Keycloak, Prometheus/Grafana/Loki │ │ urbex CLI │ │ acme-app-api-staging acme-app-api-prod │ └───────────────────────┘ └──────────────────────────────────────────┘ ``` -- **The platform**: Gitea (Git and the container registry), Komodo +- **The platform**: Forgejo (Git and the container registry), Komodo (builds and deploys), Technitium (internal DNS), Keycloak (login), and an observability stack, each in its own LXC. -- **Your app** lives on Gitea, developed on `main`. Every push is built +- **Your app** lives on Forgejo, developed on `main`. Every push is built into one image per service and deployed to **staging**. - **A release is a Git tag** (`v1.4.2`) on a commit staging ran: it gives that image the version, without rebuilding it. **Production runs @@ -110,7 +110,7 @@ at their IP and port. Choose one: |---|---|---| | **Nothing** | Apps and admin tools on the LAN only | - | | **Quick Tunnel** | A public `https://*.trycloudflare.com` address per public service | No account ([ADR-0025](decisions/0025-cloudflare-quick-tunnel.md)) | -| **Your zone** | Public HTTPS on your domain; Gitea, Komodo and the consoles behind Cloudflare Access | A Cloudflare account, the domain's zone on it, an API token ([credentials](reference/credentials.md)) | +| **Your zone** | Public HTTPS on your domain; Forgejo, Komodo and the consoles behind Cloudflare Access | A Cloudflare account, the domain's zone on it, an API token ([credentials](reference/credentials.md)) | You can add Cloudflare later: see [Put the platform on the internet](cookbook.md#put-the-platform-on-the-internet). diff --git a/docs/getting-started/with-the-cli.md b/docs/getting-started/with-the-cli.md index b5bb6b7..31e28e9 100644 --- a/docs/getting-started/with-the-cli.md +++ b/docs/getting-started/with-the-cli.md @@ -47,7 +47,7 @@ Fill it in ([every field](../reference/platform-config.md)): ```yaml domain: acme.example git: - giteaUrl: https://git.acme.example + forgeUrl: https://git.acme.example org: urbex proxmox: apiUrl: https://192.168.1.10:8006/api2/json @@ -69,7 +69,7 @@ Then run it again: urbex-op 'urbex bootstrap' ``` -It takes about twenty minutes. It creates the platform's LXCs (Gitea, +It takes about twenty minutes. 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 @@ -108,7 +108,7 @@ cd ~/urbex-work/projects/acme-app && git add urbex.yaml && git commit -m "Add ur urbex-op 'cd /work/projects/acme-app && urbex apply staging' ``` -It creates the LXC, the repository on Gitea from your local `main`, the +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 address of each service: @@ -117,7 +117,7 @@ Deployed acme-app (staging): api http://192.168.1.210:8080 3f9c2e1 (...) ``` -Gitea is now your app's remote. Every push to `main` is built and +Forgejo is now your app's remote. Every push to `main` is built and deployed to staging within a few minutes: ```sh diff --git a/docs/known-limitations.md b/docs/known-limitations.md index 9171625..0561267 100644 --- a/docs/known-limitations.md +++ b/docs/known-limitations.md @@ -34,6 +34,7 @@ minor release may change how something works (see | Limitation | Workaround / consequence | |---|---| +| **A platform installed with urbex 0.1.0 stays on Gitea 1.24**, which is out of support: newer urbex bootstraps Forgejo 15 LTS ([ADR-0034](decisions/0034-forgejo-lts-forge.md)), and doesn't migrate a running forge - Forgejo imports Gitea's database only up to Gitea 1.22. Its workspace keeps working with newer urbex (the old credential and config names are still read). | Bootstrap the platform again (`urbex teardown`, then `urbex bootstrap`; push the project repos somewhere else first), or push the repos to the new forge yourself. | | **One Proxmox node.** Every LXC is created on `proxmox.node`; no clusters, no HA, no other providers (cloud providers are v2+). | - | | **Addresses aren't checked or reserved.** Urbex takes static IPs from `proxmox.network` (base services from `baseHostOffset`, projects 10 after) without checking they're free; a DHCP server can hand them out too. | Keep the block out of the DHCP range. | | **Every LXC resolves through Technitium**, then `proxmox.network.dnsServers` (the gateway when unset), which are also Technitium's forwarders: a gateway that doesn't answer DNS, or a resolver the LXCs can't reach (Tailscale's MagicDNS), breaks resolution ([ADR-0027](decisions/0027-service-conventions.md)). | Set `dnsServers` (or `dns.forwarders`) to a LAN resolver. | @@ -45,7 +46,7 @@ minor release may change how something works (see | **Per-project Proxmox isolation** (resource pool, user group, technical users per project) isn't implemented: every LXC goes in the platform's pool, managed with the operator's token. | Planned ([roadmap](roadmap.md)). | | **Keycloak's first start builds its image**, once per platform: about 7 minutes on a home lab node, which `urbex bootstrap` and `urbex apply` wait for (up to 15 minutes). Later starts take under a minute ([ADR-0029](decisions/0029-keycloak-production-postgresql.md)). | Wait. | | **Base-service images** of Technitium, Prometheus, Loki and Grafana use `latest`. | - | -| **`urbex teardown` destroys Gitea**, with every repository and image on it. | Keep project repos pushed elsewhere too. The GitOps repo survives as the local working copy: keep it. | +| **`urbex teardown` destroys Forgejo**, with every repository and image on it. | Keep project repos pushed elsewhere too. The GitOps repo survives as the local working copy: keep it. | | **Rotating generated credentials isn't supported**: bootstrap keeps every value in `~/.urbex/credentials.yaml`, and changing one by hand (the Komodo database password, say) can break the service. | Only by rebuilding the platform: `urbex teardown` then `urbex bootstrap`. | ## Projects and deploys @@ -53,9 +54,9 @@ minor release may change how something works (see | Limitation | Workaround / consequence | |---|---| | **Only `vX.Y.Z` tags are releases**: no pre-releases (`-rc.1`). | Staging runs every commit of `main`; release a patch version. | -| **`urbex promote` commits straight to the GitOps repo.** | [Gate production behind a pull request](cookbook.md#gate-production-behind-a-pull-request) with Gitea's protected file patterns. | +| **`urbex promote` commits straight to the GitOps repo.** | [Gate production behind a pull request](cookbook.md#gate-production-behind-a-pull-request) with Forgejo's protected file patterns. | | **Komodo can miss a push** made within ~5 seconds of the previous one (it caches the repo); the scheduled run catches up within 15 minutes. | The `urbex` commands handle it; by hand, run the `urbex-gitops` Procedure. | -| **Every push to `main` is built**, documentation-only ones included, and **images are never pruned.** | Delete old ones in Gitea, under the organization's *Packages*. | +| **Every push to `main` is built**, documentation-only ones included, and **images are never pruned.** | Delete old ones in Forgejo, under the organization's *Packages*. | | **Removing a service from `urbex.yaml`**: the next `urbex apply` deletes its LXC (the project's Terraform has one per declared service) but leaves its Stack, folder, routes and internal DNS record. With named volumes, `apply` refuses: Proxmox deletes an LXC's volumes with it. | Remove the leftovers by hand. For an application with named volumes, put it back, or run `urbex apply --delete-data` to delete it with its volumes. | | **Changing a port or healthcheck** needs `urbex deploy ` (it regenerates the compose files); configuration in `urbex.yaml`'s `env` only seeds `config.env` once. | Edit `config.env` in the GitOps repo afterwards. | | **No concurrency guard across machines** on the Terraform state and the address ledger. | Don't run `plan`, `apply`, `destroy` from two machines at once. | @@ -86,7 +87,7 @@ minor release may change how something works (see |---|---| | **`nested` hostnames need Advanced Certificate Manager**, which Urbex doesn't enable or order certificates for. | Use the default `flat` names, or enable ACM and order the wildcard certificates by hand. | | **Public names are derived** from the project's and services' names; `domain.subdomain` in the manifest isn't used. | - | -| **Gitea and Komodo behind Access are for browsers.** `git` and the CLI keep using the LAN addresses, and the links Gitea and Komodo generate use their internal names (Gitea's registry needs `ROOT_URL` reachable from every LXC). | Use the LAN, or a VPN, for git and the CLI. | +| **Forgejo and Komodo behind Access are for browsers.** `git` and the CLI keep using the LAN addresses, and the links Forgejo and Komodo generate use their internal names (Forgejo's registry needs `ROOT_URL` reachable from every LXC). | Use the LAN, or a VPN, for git and the CLI. | | **Prometheus' and Loki's APIs behind Access are for browsers.** A script or tool calling them from outside needs a Cloudflare Access service token, which Urbex doesn't create. | Create a service token in Zero Trust and add it to the `urbex-operators` policy, or use the LAN. | | **Access allows a list of e-mail addresses** with a one-time PIN; no identity provider, no groups. | Keycloak as Access's identity provider is a possible next step. | | **The Cloudflare token is broad and stored in Komodo** (secret variable) for the web deploys. | Use a token scoped to the one zone and account, as in [credentials](reference/credentials.md#cloudflare-api-token). | @@ -108,13 +109,13 @@ minor release may change how something works (see | Limitation | Workaround / consequence | |---|---| -| **Keycloak covers the projects' users only** ([ADR-0024](decisions/0024-keycloak-realm-per-environment.md)): no admin SSO for Gitea/Komodo/Grafana, no confidential clients for services calling each other, one client per frontend (and one frontend per project); destroying an environment deletes its realm's users. | Add what's missing in Keycloak's console: urbex keeps what it doesn't manage (extra redirect URIs, users, clients). | +| **Keycloak covers the projects' users only** ([ADR-0024](decisions/0024-keycloak-realm-per-environment.md)): no admin SSO for Forgejo/Komodo/Grafana, no confidential clients for services calling each other, one client per frontend (and one frontend per project); destroying an environment deletes its realm's users. | Add what's missing in Keycloak's console: urbex keeps what it doesn't manage (extra redirect URIs, users, clients). | | **A platform bootstrapped before internal DNS registration existed keeps Technitium's original admin password**: `DNS_SERVER_ADMIN_PASSWORD` only takes effect while Technitium has no configuration yet, so re-running `urbex bootstrap` on an already-configured instance doesn't rotate it, and minting the API token fails ([ADR-0026](decisions/0026-technitium-internal-dns-records.md)). | Seed the real password into `~/.urbex/credentials.yaml`'s `technitiumAdminPassword` before bootstrapping. | | Technitium does not validate DNSSEC: it leaves validation to its forwarders, since many LAN resolvers, and routers that intercept DNS traffic, do not return the records validation requires, and Technitium would then fail every public name. | Use forwarders that validate DNSSEC, if validation is required. | | **When Technitium is down, internal names don't resolve**: the LXCs fall back to the forwarders, which only know public names. | Re-run `urbex bootstrap` to reinstall it. | | **The internal zone (`urbex.`) shadows Cloudflare on the LAN**: Technitium answers for every name under it, so a record you created there on Cloudflare doesn't resolve from the LXCs; with `nested` public hostnames, neither do the web frontends' (they have no LXC, so no internal record) ([ADR-0027](decisions/0027-service-conventions.md)). | Keep your own records out of the platform's subdomain, or set `dns.zone`. | | **Without Cloudflare, the token issuer is Keycloak's LAN address** (`KEYCLOAK_ISSUER`): the address your users' browsers reach it at, which the tokens carry. The services fetch the signing keys by internal name. | Configure Cloudflare for a stable, public issuer. | -| **The internal names don't resolve on your machine** unless it asks Technitium: images (`git.:3000/...`), the links Gitea and Komodo generate, and the URLs services are configured with use the internal names ([ADR-0027](decisions/0027-service-conventions.md)). The CLI uses the LAN addresses, after checking them against Technitium. | Have your router forward the zone to Technitium ([cookbook](cookbook.md#resolve-a-service-by-name-on-the-lan)). | +| **The internal names don't resolve on your machine** unless it asks Technitium: images (`git.:3000/...`), the links Forgejo and Komodo generate, and the URLs services are configured with use the internal names ([ADR-0027](decisions/0027-service-conventions.md)). The CLI uses the LAN addresses, after checking them against Technitium. | Have your router forward the zone to Technitium ([cookbook](cookbook.md#resolve-a-service-by-name-on-the-lan)). | | **Logs and resource metrics only** ([ADR-0023](decisions/0023-service-logs-to-loki.md), [ADR-0027](decisions/0027-service-conventions.md)): the services' own metrics (`observability.metrics`) aren't scraped, per-container metrics are CPU and memory only, the only alerts are the reconciler's and those on the LXCs' disk and memory - not on the Proxmox node's own memory, CPU and storages, nor on a VM - and web frontends' runtime logs are on Cloudflare (their deploy container's are in Loki). | Cloudflare's Workers logs for frontends. | | **Loki keeps logs forever**: default single-node configuration, no retention set; the observability LXC's disk fills up over time. | Grow its disk (`terraform/base`), or clean Loki's volume. | | **Grafana's admin password** is the only login (no Keycloak SSO), after Cloudflare Access when reached from outside. | `admin` / `grafanaAdminPassword` from `~/.urbex/credentials.yaml`. | @@ -124,6 +125,6 @@ minor release may change how something works (see | Limitation | Workaround / consequence | |---|---| -| **Gitea and its registry are plain HTTP on the LAN**, trusted by the LXCs' Docker as an insecure registry. | Keep the LAN trusted. | -| **No backups** of Gitea, Komodo, Keycloak or the services' data. | Proxmox's own backups of the LXCs, which include the applications' named volumes (`backup=1`); a restore brings them back and `urbex apply` takes it as it is ([how](cookbook.md#back-up-and-restore-an-applications-data)). | +| **Forgejo and its registry are plain HTTP on the LAN**, trusted by the LXCs' Docker as an insecure registry. | Keep the LAN trusted. | +| **No backups** of Forgejo, Komodo, Keycloak or the services' data. | Proxmox's own backups of the LXCs, which include the applications' named volumes (`backup=1`); a restore brings them back and `urbex apply` takes it as it is ([how](cookbook.md#back-up-and-restore-an-applications-data)). | | **No fleet-wide status**: `urbex status ` is per project. | Komodo's UI; `grep -r '^VERSION' environments/` in the GitOps repo. | diff --git a/docs/reference/README.md b/docs/reference/README.md index 42fe5fc..cf0817b 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -12,7 +12,7 @@ and the [cookbook](../cookbook.md). | [GitOps repo](gitops-repo.md) | The repo's layout; `version.env`, `config.env`, `secrets.sops.env`, `compose.yaml`; how a commit becomes a deploy. | | [Credentials](credentials.md) | Every credential, where it's read from, and how to obtain it. | | [Startup sequence](startup.md) | What `urbex bootstrap` and `urbex apply` do, in order and in parallel, and how long each phase takes; followed live by `urbex status --progress`. | -| [Platform resources](platform-resources.md) | Everything created on Proxmox, Gitea, and Komodo, and what's safe to change by hand. | +| [Platform resources](platform-resources.md) | Everything created on Proxmox, Forgejo, and Komodo, and what's safe to change by hand. | The formal manifest schema is [`schemas/urbex.schema.json`](../../schemas/urbex.schema.json); the diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 96453f0..37609fc 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -48,7 +48,7 @@ the [cookbook](../cookbook.md). resolved to (`17.6@sha256:...`). - **Credentials** come from environment variables, falling back to `~/.urbex/credentials.yaml`; see [credentials](credentials.md). -- Commands that change the GitOps repo first pull it from Gitea +- Commands that change the GitOps repo first pull it from Forgejo (rebasing local commits), then commit and push. Its working copy may have uncommitted changes; they are kept. @@ -174,14 +174,14 @@ Proposed urbex.platform.yaml (save it with --write): domain: example.com # the Cloudflare zone git: - giteaUrl: https://git-urbex.example.com + forgeUrl: https://git-urbex.example.com org: urbex -cloudflare: # public HTTPS on example.com; Gitea and Komodo behind Cloudflare Access +cloudflare: # public HTTPS on example.com; Forgejo and Komodo behind Cloudflare Access accountId: 0123456789abcdef0123456789abcdef zoneId: fedcba9876543210fedcba9876543210 access: - emails: [you@example.com] # FILL IN: who may open Gitea and Komodo (a one-time PIN goes to the address) + emails: [you@example.com] # FILL IN: who may open Forgejo and Komodo (a one-time PIN goes to the address) proxmox: apiUrl: https://192.168.1.10:8006/api2/json @@ -234,7 +234,7 @@ urbex init # urbex.yaml is valid. urbex bootstrap [--gitops-repo ] [--dry-run] [--events json] ``` -Creates the platform: the base-service LXCs, and Gitea and Komodo wired +Creates the platform: the base-service LXCs, and Forgejo and Komodo wired together. Run it once per platform; running it again is safe and is how the base services are updated. Its phases, what runs at the same time and how long each takes are drawn in [startup sequence](startup.md); @@ -258,7 +258,7 @@ and how long each takes are drawn in [startup sequence](startup.md); LXCs come from the Debian template as before, with a warning. Then `terraform init` and `terraform apply` in `terraform/base/`, then `ansible-playbook` with `ansible/playbook.yml`: Docker on every LXC - (skipped on clones of the template), then Technitium, then Gitea, + (skipped on clones of the template), then Technitium, then Forgejo, Komodo (Core, database, Periphery) and the others in parallel - while they install, the LXCs of Keycloak, the observability stack and the tunnel pull, one at a time, the images of the Stacks Komodo deploys @@ -273,14 +273,14 @@ and how long each takes are drawn in [startup sequence](startup.md); `tunnel`). On a platform set up with a zone named after `domain`, it moves the project services' records to the new zone and deletes the old one - see [ADR-0027](../decisions/0027-service-conventions.md). -7. Platform setup: a Gitea token, the org and its `gitops` repo; a Komodo - API key, the onboarding key, Komodo's Gitea git and registry accounts, +7. Platform setup: a Forgejo token, the org and its `gitops` repo; a Komodo + API key, the onboarding key, Komodo's Forgejo git and registry accounts, the `URBEX_*` Komodo variables, the `urbex-release` Action, the `urbex-gitops` Procedure; `.sops.yaml`; commits and pushes the GitOps repo, and adds its webhook. Tokens and keys already in the credentials file are reused, not rotated. Then connects the other base LXCs to Komodo and has Komodo adopt - Technitium, Gitea and Komodo as Stacks (`urbex-technitium`, + Technitium, Forgejo and Komodo as Stacks (`urbex-technitium`, `urbex-gitea`, `urbex-komodo`) whose compose files stay on their servers, in `/opt/urbex`: Komodo takes over the running containers without redeploying them, and from then on can redeploy them; a copy @@ -301,8 +301,8 @@ and how long each takes are drawn in [startup sequence](startup.md); before Ansible, the tunnel `urbex-platform` and the token its connector on `urbex-tunnel` runs with; at the end, Access first - the one-time PIN login if missing, the policy for `cloudflare.access.emails`, - applications for Gitea and Komodo - then the routes and DNS records of - Keycloak, Gitea, Komodo and the webhook listener. If Access can't be set + applications for Forgejo and Komodo - then the routes and DNS records of + Keycloak, Forgejo, Komodo and the webhook listener. If Access can't be set up, nothing is published. 9. Waits for Keycloak to answer before reporting the platform ready: its first start takes a few minutes (it says so while waiting), and stops @@ -324,7 +324,7 @@ urbex plan [--file urbex.yaml] [--gitops-repo ] ``` Shows what `apply` would change in the infrastructure, without changing -it: updates the GitOps repo from Gitea, allocates (and records) a VMID and IP for each service's LXC in +it: updates the GitOps repo from Forgejo, allocates (and records) a VMID and IP for each service's LXC in `` if it has none, writes the project's Terraform files under `terraform/projects///`, and runs `terraform plan`. @@ -374,7 +374,7 @@ usual times: [startup sequence](startup.md#urbex-apply-env); volume, it removes the empty `lost+found` of a new one (ext4) so that Docker can fill the volume from the image, and stops if the folder is not a mount point. -3. **The project:** its repo on Gitea (if Gitea has no `main`, pushes +3. **The project:** its repo on Forgejo (if Forgejo has no `main`, pushes `--repo-dir`'s `HEAD` there), a Komodo Build per service, and the project repo's webhook to the `urbex-release` Action. Applications from published images have no Build; a project made only of such @@ -424,7 +424,7 @@ Fix it and run `apply` again. | Flag | Default | Meaning | |---|---|---| -| `--repo-dir ` | `.` | The project's local repo, used only if Gitea has no `main` yet. | +| `--repo-dir ` | `.` | The project's local repo, used only if Forgejo has no `main` yet. | | `--delete-data` | off | Let `apply` delete the LXC of an application removed from `urbex.yaml`, with its named volumes, and drop the PostgreSQL roles and schemas no application uses any more, with their data. `apply` names them first. Nothing is kept. A replacement of an LXC with volumes is refused with it as well. | Needs: `URBEX_PROXMOX_TOKEN`, `URBEX_AGE_KEY`, the platform credentials @@ -445,7 +445,7 @@ port or healthcheck only need [`deploy`](#urbex-deploy). urbex release [--version vX.Y.Z] [--ref ] [--file urbex.yaml] [--gitops-repo ] ``` -Makes a release: tags a commit of the project as `vX.Y.Z` on Gitea and +Makes a release: tags a commit of the project as `vX.Y.Z` on Forgejo and waits until every service has an image `X.Y.Z` in the registry. A release concerns the services built from source only. It is refused @@ -620,7 +620,7 @@ Base services: ... Endpoints: - Gitea (web, git, registry) http://git.urbex.example.com:3000 http://192.168.1.200:3000 https://git-urbex.example.com (public: behind Cloudflare Access) + Forgejo (web, git, registry) http://git.urbex.example.com:3000 http://192.168.1.200:3000 https://git-urbex.example.com (public: behind Cloudflare Access) Komodo http://komodo.urbex.example.com:9120 http://192.168.1.201:9120 https://komodo-urbex.example.com (public: behind Cloudflare Access) Komodo webhooks http://hooks.urbex.example.com:9120/listener/ http://192.168.1.201:9120/listener/ https://hooks-urbex.example.com/listener/ (signed calls only) Keycloak http://auth.urbex.example.com:8080 http://192.168.1.203:8080 https://auth-urbex.example.com (realms public; admin console behind Cloudflare Access) @@ -629,8 +629,8 @@ Endpoints: Prometheus http://prometheus.urbex.example.com:9090 http://192.168.1.204:9090 https://prometheus-urbex.example.com (public: behind Cloudflare Access; remote write internal only) Loki http://loki.urbex.example.com:3100 http://192.168.1.204:3100 https://loki-urbex.example.com (public: behind Cloudflare Access; push internal only) -Logins: Gitea and Komodo urbex-admin, Grafana admin, Keycloak admin, Technitium admin; passwords in ~/.urbex/credentials.yaml -(giteaAdminPassword, komodoAdminPassword, grafanaAdminPassword, keycloakAdminPassword, technitiumAdminPassword). +Logins: Forgejo and Komodo urbex-admin, Grafana admin, Keycloak admin, Technitium admin; passwords in ~/.urbex/credentials.yaml +(forgeAdminPassword, komodoAdminPassword, grafanaAdminPassword, keycloakAdminPassword, technitiumAdminPassword). Projects: acme-app (staging) @@ -640,7 +640,7 @@ Projects: api http://192.168.1.211:8080 https://api-acme-app-urbex.example.com version=1.4.0 stack=running dns=api.acme-app.urbex.example.com ``` -Both forms first update the GitOps repo from Gitea (the release Action +Both forms first update the GitOps repo from Forgejo (the release Action commits there too), and say so if they can't. Through `urbex-op`, the credentials file is shown at its path on your @@ -652,7 +652,7 @@ container's `/work/home/...`. `--output json` (`-o json`) prints the same as one JSON document on standard output, for a program to read - a web UI, an MCP server, the Claude Code plugin ([ADR-0032](../decisions/0032-web-ui-console-ai-assistant.md)). -What couldn't be checked or updated (Gitea, Komodo) is in `warnings` +What couldn't be checked or updated (Forgejo, Komodo) is in `warnings` instead of the text's bracketed lines; errors still go to standard error with a non-zero exit status. It holds no password: `logins` names each admin user and the key of its password in the credentials file. @@ -667,7 +667,7 @@ Without ``: "endpoints": [ { "service": "gitea", - "name": "Gitea (web, git, registry)", + "name": "Forgejo (web, git, registry)", "internal": "http://git.urbex.example.com:3000", "lan": "http://192.168.1.200:3000", "public": "https://git-urbex.example.com", @@ -677,7 +677,7 @@ Without ``: ], "logins": { "credentialsFile": "/home/me/urbex-work/home/.urbex/credentials.yaml", - "users": [ { "service": "gitea", "user": "urbex-admin", "passwordKey": "giteaAdminPassword" } ] + "users": [ { "service": "gitea", "user": "urbex-admin", "passwordKey": "forgeAdminPassword" } ] }, "projects": [ { @@ -753,7 +753,7 @@ urbex bootstrap: running for 7m12s, about 3m05s left (started 14:02) ✓ Create the LXCs (Terraform) 56s ✓ Configure every LXC (Ansible) 21s ✓ Install Technitium (DNS) 26s - ▶ Install Gitea and Komodo, pull the other images 4m29s so far, about 21s left + ▶ Install Forgejo and Komodo, pull the other images 4m29s so far, about 21s left · Prepare the telemetry agents about 5s ... ``` @@ -834,7 +834,7 @@ urbex destroy [--file urbex.yaml] [--gitops-repo ] [--delete-data] [- Removes an environment of the project, in this order: -1. Updates the GitOps repo from Gitea. +1. Updates the GitOps repo from Forgejo. 2. Takes its Komodo Stacks down (`docker compose down`) and deletes them: from here on nothing deploys the environment. With Cloudflare, removes its public services' routes and DNS records, and its web frontend's @@ -873,7 +873,7 @@ acme-vault (prod) has named volumes: vault/data. Destroying it deletes them with |---|---| | `--delete-data` | Delete the named volumes with their machines. Nothing is kept. Shares are never touched. | -The project's repo and images stay on Gitea. Services that were never +The project's repo and images stay on Forgejo. Services that were never applied are skipped; if none were, nothing happens. Base services are never touched. @@ -889,12 +889,12 @@ urbex teardown [--gitops-repo ] [--yes] [--events json] Destroys the platform `urbex bootstrap` created: the inverse of `bootstrap`. -1. Updates the GitOps repo from Gitea (if it still answers). +1. Updates the GitOps repo from Forgejo (if it still answers). 2. Refuses while any project environment exists - a folder under `environments/` or an LXC in the allocation ledger - naming them: run `urbex destroy ` in each project first. 3. Says what it destroys and what is lost: the base-service LXCs and - their disks, so **every repository and image on Gitea** (project repos + their disks, so **every repository and image on Forgejo** (project repos included - make sure they also live elsewhere), Komodo's, Keycloak's and Grafana's data, the generated credentials. Without `--yes` it stops here. @@ -908,7 +908,7 @@ Destroys the platform `urbex bootstrap` created: the inverse of key, Cloudflare token) stay. 6. Commits the GitOps repo locally. Its working copy is now the **only copy**: keep it. `urbex bootstrap` creates a new platform from it and - pushes it to the new Gitea. + pushes it to the new Forgejo. | Flag | Meaning | |---|---| @@ -1042,7 +1042,7 @@ as without `--events`. | `URBEX_GITOPS_REPO` | Every command but `init`: the GitOps repo working copy, if `--gitops-repo` isn't given. | | `URBEX_PROXMOX_TOKEN` | `bootstrap`, `plan`, `apply`, `destroy`, `teardown`, `status`. | | `URBEX_AGE_KEY` | `bootstrap`, `plan`, `apply`, `destroy`, `teardown`, `secret set/unset`. | -| `URBEX_GITEA_TOKEN`, `URBEX_KOMODO_*`, ... | Generated by bootstrap into `~/.urbex/credentials.yaml`; an environment variable overrides the file. | +| `URBEX_FORGE_TOKEN`, `URBEX_KOMODO_*`, ... | Generated by bootstrap into `~/.urbex/credentials.yaml`; an environment variable overrides the file. | The full list, and how to obtain each, is in [credentials](credentials.md). diff --git a/docs/reference/credentials.md b/docs/reference/credentials.md index 98a23cf..463a6c8 100644 --- a/docs/reference/credentials.md +++ b/docs/reference/credentials.md @@ -12,7 +12,7 @@ never in the GitOps repo). These are enforced - `urbex bootstrap`/`plan`/`apply`/`destroy` refuse to run without them (`credentials.MissingForProvisioning()` in `urbex-cli`). `urbex release`, `deploy`, `promote`, and `secret` don't -need the Proxmox token, since they only talk to Gitea and Komodo - but +need the Proxmox token, since they only talk to Forgejo and Komodo - but they do need the [generated platform credentials](#generated-by-urbex-bootstrap). @@ -152,12 +152,12 @@ deploying needs none of it: a commit to the GitOps repo is enough. | Credentials file key | Env var | What it is | |---|---|---| -| `giteaAdminPassword` | `URBEX_GITEA_ADMIN_PASSWORD` | Password of `urbex-admin`, Gitea's admin user | -| `giteaToken` | `URBEX_GITEA_TOKEN` | Gitea token (repos, org, packages) used by the CLI (repos, webhooks, release tags, pushing the GitOps repo) and by Komodo (cloning, pushing and pulling images) | +| `forgeAdminPassword` | `URBEX_FORGE_ADMIN_PASSWORD` | Password of `urbex-admin`, the forge's (Forgejo's) admin user | +| `forgeToken` | `URBEX_FORGE_TOKEN` | Forgejo token (repos, org, packages) used by the CLI (repos, webhooks, release tags, pushing the GitOps repo) and by Komodo (cloning, pushing and pulling images) | | `komodoAdminPassword` | `URBEX_KOMODO_ADMIN_PASSWORD` | Password of `urbex-admin`, Komodo's initial admin | | `komodoApiKey` / `komodoApiSecret` | `URBEX_KOMODO_API_KEY` / `URBEX_KOMODO_API_SECRET` | Komodo API key the CLI declares builds and stacks with | | `komodoOnboardingKey` | `URBEX_KOMODO_ONBOARDING_KEY` | Key the Periphery agent on each project LXC registers itself in Komodo with | -| `komodoWebhookSecret` | `URBEX_KOMODO_WEBHOOK_SECRET` | Secret Gitea signs its webhooks to Komodo with | +| `komodoWebhookSecret` | `URBEX_KOMODO_WEBHOOK_SECRET` | Secret Forgejo signs its webhooks to Komodo with | | `komodoDbPassword`, `komodoJwtSecret` | `URBEX_KOMODO_DB_PASSWORD`, `URBEX_KOMODO_JWT_SECRET` | Komodo's internal database password and signing secret | | `keycloakAdminPassword` | `URBEX_KEYCLOAK_ADMIN_PASSWORD` | Keycloak's bootstrap admin password | | `keycloakDbPassword` | `URBEX_KEYCLOAK_DB_PASSWORD` | Keycloak's PostgreSQL password, also in the Keycloak Stack's encrypted secrets | @@ -166,11 +166,18 @@ deploying needs none of it: a commit to the GitOps repo is enough. | `technitiumToken` | `URBEX_TECHNITIUM_TOKEN` | Technitium API token, minted with the admin password, used to create the zone and the services' DNS records ([ADR-0026](../decisions/0026-technitium-internal-dns-records.md)) | `urbex apply`, `release`, `deploy`, `promote`, and `secret` refuse to -run without the Gitea token, the Komodo API key, the onboarding key, and +run without the Forgejo token, the Komodo API key, the onboarding key, and the webhook secret (`credentials.MissingForPlatform()`). -Bootstrap also stores the Gitea token in Komodo, as the secret variable -`URBEX_GITEA_TOKEN`: the `urbex-release` Action uses it to look up +Before the forge was Forgejo ([ADR-0034](../decisions/0034-forgejo-lts-forge.md)) +the two forge keys were `giteaAdminPassword` and `giteaToken` +(`URBEX_GITEA_ADMIN_PASSWORD`, `URBEX_GITEA_TOKEN`): urbex still reads +them, the new names win, and the next time urbex writes the file it +moves them to the new keys. + +Bootstrap also stores the forge's token in Komodo, as the secret variable +`URBEX_GITEA_TOKEN` (named for Gitea still: the Actions of existing +platforms read it): the `urbex-release` Action uses it to look up images and to commit staging's new version to the GitOps repo. Komodo never shows a secret variable's value in its UI or logs. See [platform resources](platform-resources.md). @@ -208,7 +215,7 @@ bootstrap` again. |---|---|---| | Account | Cloudflare Tunnel Write | the platform's tunnel and its routes | | Account | Workers Scripts Write | the web frontends' Workers | - | Account | Access: Apps and Policies Write | Access in front of Gitea and Komodo | + | Account | Access: Apps and Policies Write | Access in front of Forgejo and Komodo | | Account | Access: Organizations, Identity Providers, and Groups Write | only to enable the one-time PIN login if Zero Trust has none yet | | Zone (yours) | DNS Write | the public hostnames | | Zone (yours) | Workers Routes Write | the web frontends' custom domains | @@ -342,6 +349,6 @@ item each is waiting on. | Proxmox API token | `URBEX_PROXMOX_TOKEN` | ✅ yes | | SSH private key | (SSH agent, not an env var) | ✅ yes | | age keypair | `URBEX_AGE_KEY` | ✅ yes (encrypts every secret) | -| Gitea/Komodo/Keycloak/Grafana/Technitium passwords, tokens, keys | `URBEX_GITEA_*`, `URBEX_KOMODO_*`, `URBEX_TECHNITIUM_*`, ... | ✅ generated by `urbex bootstrap` | +| Forgejo/Komodo/Keycloak/Grafana/Technitium passwords, tokens, keys | `URBEX_FORGE_*`, `URBEX_KOMODO_*`, `URBEX_TECHNITIUM_*`, ... | ✅ generated by `urbex bootstrap` | | Cloudflare API token | `URBEX_CLOUDFLARE_TOKEN` | ✅ with Cloudflare configured | | Brevo API key | *(none defined)* | ❌ not yet | diff --git a/docs/reference/gitops-repo.md b/docs/reference/gitops-repo.md index d271554..72a9ba6 100644 --- a/docs/reference/gitops-repo.md +++ b/docs/reference/gitops-repo.md @@ -1,6 +1,6 @@ # GitOps repo reference -The GitOps repo (`/gitops` on Gitea) is the platform's single +The GitOps repo (`/gitops` on Forgejo) is the platform's single source of truth: how the infrastructure is built, and what every environment of every project runs. Komodo deploys from it; `urbex` writes to it; people can too - every change is a commit. @@ -280,7 +280,7 @@ application runs. logs and metrics are labelled. - `technitium/`, `gitea/`, `komodo/` hold **copies** of the compose files their Stacks deploy from their servers (`/opt/urbex`): Komodo - can't depend on Gitea or Technitium to deploy them, and `urbex + can't depend on Forgejo or Technitium to deploy them, and `urbex bootstrap` restores them if a redeploy breaks one. The copies are for review; no secret is in them. @@ -288,7 +288,7 @@ application runs. 1. A commit lands on `main` of the GitOps repo (a push, a merged pull request, `urbex`, or the `urbex-release` Action). -2. Gitea calls Komodo's webhook for the `urbex-gitops` Procedure, which +2. Forgejo calls Komodo's webhook for the `urbex-gitops` Procedure, which runs *deploy if changed* on every Urbex Stack. 3. Each Stack compares its folder with what it last deployed. Only a Stack whose `compose.yaml`, `version.env`, `config.env`, diff --git a/docs/reference/manifest.md b/docs/reference/manifest.md index 7e7e3bc..a375ab6 100644 --- a/docs/reference/manifest.md +++ b/docs/reference/manifest.md @@ -60,7 +60,7 @@ frontend: | Field | Type | Required | Meaning | |---|---|---|---| | `apiVersion` | `urbex/v1` | yes | Manifest format version. | -| `project` | string | yes | The project's name on the platform: 3-40 characters, lowercase letters, digits, `-`, starting with a letter. It names the repo on Gitea, the LXCs, the images, and the folders in the GitOps repo, so changing it means a new project. | +| `project` | string | yes | The project's name on the platform: 3-40 characters, lowercase letters, digits, `-`, starting with a letter. It names the repo on Forgejo, the LXCs, the images, and the folders in the GitOps repo, so changing it means a new project. | | `services` | list | one of `services` or `frontend` | The services to build and run. At least one if present. | | `environments` | `[staging, prod]` or `[prod]` | `[staging, prod]` | The environments of the stack. With `[prod]` the stack runs in production only: `urbex apply staging` is refused, and `urbex release` and `urbex promote` do not apply, since versions are set in production directly with `urbex deploy prod` ([ADR-0028](../decisions/0028-application-model.md)). | | `frontend` | object | | See [`frontend`](#frontend). | diff --git a/docs/reference/platform-config.md b/docs/reference/platform-config.md index 7e9f0fb..12af174 100644 --- a/docs/reference/platform-config.md +++ b/docs/reference/platform-config.md @@ -11,7 +11,7 @@ secrets - those are [credentials](credentials.md). domain: acme.example git: - giteaUrl: https://git.acme.example + forgeUrl: https://git.acme.example org: urbex proxmox: @@ -52,9 +52,9 @@ cloudflare: | Field | Default | Meaning | |---|---|---| -| `domain` | required | The platform's domain: the Cloudflare zone public hostnames are created in, and the Gitea admin's e-mail domain. | -| `git.giteaUrl` | required | The public URL Gitea will have. ⚠️ Not used yet: Urbex reaches Gitea at `http://:3000`. | -| `git.org` | `urbex` | Gitea organization holding the GitOps repo (`/gitops`), every project repo (`/`), and their images (`:3000//-`). | +| `domain` | required | The platform's domain: the Cloudflare zone public hostnames are created in, and the Forgejo admin's e-mail domain. | +| `git.forgeUrl` | required | The public URL the forge (Forgejo) will have; `git.giteaUrl`, its name before [ADR-0034](../decisions/0034-forgejo-lts-forge.md), is still read. ⚠️ Not used yet: Urbex reaches Gitea at `http://:3000`. | +| `git.org` | `urbex` | Forgejo organization holding the GitOps repo (`/gitops`), every project repo (`/`), and their images (`:3000//-`). | | `proxmox.apiUrl` | required | Proxmox API URL, ending in `/api2/json`. | | `proxmox.insecure` | `false` | Skip TLS verification of the Proxmox API (its default certificate is self-signed). | | `proxmox.node` | required | The node every LXC is created on. | @@ -74,7 +74,7 @@ cloudflare: | `cloudflare.name` | `urbex` | Last label of every public hostname, telling Urbex's apart from the zone's others. | | `cloudflare.hostnames` | `flat` | How labels are joined - see [public hostnames](#public-hostnames). | | `cloudflare.tunnelName` | `-platform` | The Cloudflare Tunnel Urbex creates and routes through. | -| `cloudflare.access.emails` | required with Cloudflare | Who may open Gitea and Komodo through Cloudflare Access (one-time PIN sent to the address). | +| `cloudflare.access.emails` | required with Cloudflare | Who may open Forgejo and Komodo through Cloudflare Access (one-time PIN sent to the address). | | `cloudflare.quickTunnel` | `false` | Alternative to `cloudflare.accountId`/`zoneId` (mutually exclusive with them): a Cloudflare Quick Tunnel per `public: true` service, no account needed - see [ADR-0025](../decisions/0025-cloudflare-quick-tunnel.md) and its [known limitations](../known-limitations.md#public-endpoints-cloudflare). Doesn't apply to `frontend.type: web`. | | `dns.zone` | `.` | The zone Technitium serves the services' internal names in - `git.urbex.example.com`, `api.staging.acme-app.urbex.example.com` ([ADR-0027](../decisions/0027-service-conventions.md)). Technitium answers for the whole zone: keep nothing of yours under it on Cloudflare. | | `dns.forwarders` | `proxmox.network.dnsServers`, or the gateway | IP addresses Technitium forwards every name outside `dns.zone` to. | @@ -145,7 +145,7 @@ With Cloudflare configured, Urbex publishes, under `domain`: | | `flat` (default) | `nested` | |---|---|---| | Keycloak (`/admin` and the `master` realm behind Access) | `auth-urbex.` | `auth.urbex.` | -| Gitea (behind Access) | `git-urbex.` | `git.urbex.` | +| Forgejo (behind Access) | `git-urbex.` | `git.urbex.` | | Komodo (behind Access) | `komodo-urbex.` | `komodo.urbex.` | | Komodo webhooks (`/listener/` only) | `hooks-urbex.` | `hooks.urbex.` | | Technitium's console (behind Access) | `dns-urbex.` | `dns.urbex.` | diff --git a/docs/reference/platform-resources.md b/docs/reference/platform-resources.md index 5ccef66..75418ad 100644 --- a/docs/reference/platform-resources.md +++ b/docs/reference/platform-resources.md @@ -1,11 +1,11 @@ # Platform resources reference -Everything Urbex creates outside the GitOps repo - on Proxmox, in Gitea, +Everything Urbex creates outside the GitOps repo - on Proxmox, in Forgejo, in Komodo - with its name, what creates it, and what removes it. Useful for finding your way in the UIs, and for knowing what is safe to touch. `` is `git.org` from [`urbex.platform.yaml`](platform-config.md) -(default `urbex`); `` is Gitea's `:3000`. +(default `urbex`); `` is Forgejo's `:3000`. ## Proxmox @@ -29,7 +29,7 @@ in the same pool, with its own kernel ([ADR-0033](../decisions/0033-vm-for-keyct | LXC | Runs | |---|---| -| `urbex-gitea` | Gitea 1.24 (web, git, container registry) on `:3000`, SSH on `:2222`. | +| `urbex-gitea` | Forgejo 15 LTS (web, git, container registry; [ADR-0034](../decisions/0034-forgejo-lts-forge.md)) on `:3000`, SSH on `:2222`. The LXC keeps its name from when it ran Gitea. | | `urbex-komodo` | Komodo Core on `:9120`, its database (FerretDB on PostgreSQL), and a Periphery agent that is also the **builder** (server `urbex-komodo`). | | `urbex-technitium` | Technitium DNS, web console on `:5380`. | | `urbex-keycloak` | Keycloak on `:8080`, in production mode, from an image the Stack builds once for PostgreSQL; its PostgreSQL 17, reachable only by Keycloak (no port published), with its data on the volume `urbex_keycloak-db` ([ADR-0029](../decisions/0029-keycloak-production-postgresql.md)). | @@ -55,7 +55,7 @@ Action and Procedure `platform`; a project's servers, Stacks and Builds The base services run as Docker Compose projects installed by Ansible; their data is in Docker volumes on the LXC. -## Gitea +## Forgejo | Resource | Name | Created by | Removed by | |---|---|---|---| @@ -64,13 +64,13 @@ their data is in Docker volumes on the LXC. | Organization | `` | `urbex bootstrap` | `urbex teardown` | | GitOps repo | `/gitops` | `urbex bootstrap` | `urbex teardown` | | GitOps webhook | on `/gitops`, branch `main` → the `urbex-gitops` Procedure | `urbex bootstrap` | `urbex teardown` | -| Project repo | `/` | `urbex apply` (if missing) | by hand, or with Gitea by `urbex teardown` | +| Project repo | `/` | `urbex apply` (if missing) | by hand, or with Forgejo by `urbex teardown` | | Project webhook | on `/`, every push → the `urbex-release` Action | `urbex apply` | `urbex destroy` of the last environment | | Release tags | `vX.Y.Z` on `/` | `urbex release`, or you | - | | Images | packages `-`, tags `` and ``: `//-:` | the `urbex-release` Action | - (by hand) | Images are never deleted automatically: one per commit of `main`. Clean -them up in Gitea under the organization's *Packages* when they pile up. +them up in Forgejo under the organization's *Packages* when they pile up. ## Komodo @@ -79,7 +79,7 @@ them up in Gitea under the organization's *Packages* when they pile up. | Admin user | `urbex-admin` | `urbex bootstrap` | `urbex teardown` | | API key | `urbex-cli` | `urbex bootstrap` | `urbex teardown` | | Onboarding key | `urbex-projects` | `urbex bootstrap` | `urbex teardown` | -| Git account, registry account | `urbex-admin` on ``, with the Gitea token | `urbex bootstrap` | `urbex teardown` | +| Git account, registry account | `urbex-admin` on ``, with the Forgejo token | `urbex bootstrap` | `urbex teardown` | | Variables | `URBEX_GITEA_URL`, `URBEX_GITEA_USER`, `URBEX_GITEA_TOKEN` (secret), `URBEX_ORG`, `URBEX_LOKI_PUSH_URL`; with Cloudflare `URBEX_CLOUDFLARE_TOKEN` (secret), `URBEX_CLOUDFLARE_ACCOUNT_ID` | `urbex bootstrap` | `urbex teardown` | | Variables of the linked environments | `URBEX_GRAPH__`, the graph of `uses` of an environment, for the reconciler | `urbex apply ` | `urbex apply ` once nothing is linked, `urbex destroy ` | | Variable of the reconciler | `URBEX_RECONCILE_STATE`, its state between runs | the `urbex-reconcile` Action | `urbex teardown` | @@ -132,7 +132,7 @@ commit whose image already exists, and only moves environments to one. A tag pushed with git resolves to the commit it points to, annotated or not. -It reads Gitea's address and token from the `URBEX_*` variables. +It reads Forgejo's address and token from the `URBEX_*` variables. `urbex release` and `urbex apply` also run it directly. Its source is `platform/komodo/release.ts` in `urbex-cli`. @@ -235,7 +235,7 @@ nothing is published. ## What is safe to change by hand - **Yes:** anything under `environments/` in the GitOps repo; tags and - branches on project repos; old images in Gitea; Komodo's UI for + branches on project repos; old images in Forgejo; Komodo's UI for looking, running the Procedure, or redeploying a Stack. - **Overwritten by the next `bootstrap` or `apply`:** the Action, the Procedure, Builds, Stacks, the `URBEX_*` variables. Change them in the diff --git a/docs/reference/startup.md b/docs/reference/startup.md index 4c94087..1a0e5b7 100644 --- a/docs/reference/startup.md +++ b/docs/reference/startup.md @@ -25,14 +25,14 @@ flowchart TD DNS1["technitium
Ansible: the DNS server first,
every LXC resolves through it
~25 s"] subgraph BASE["base - Ansible, all at once ~5 min"] direction LR - G["Gitea"] + G["Forgejo"] K["Komodo:
Core, database, Periphery
(its images: the longest)"] I["Keycloak, observability,
tunnel LXCs:
pull their Stacks' images"] end A["agents
Ansible: telemetry agents' files
~5-20 s"] D["dns
Technitium: zone, records
~5 s"] - GO["gitops
Gitea org and repo, Komodo keys,
Action, Procedure; push the GitOps repo
~10-20 s"] - CO["connect
Ansible: Periphery on every LXC;
Komodo adopts Technitium, Gitea, Komodo
~20 s"] + GO["gitops
Forgejo org and repo, Komodo keys,
Action, Procedure; push the GitOps repo
~10-20 s"] + CO["connect
Ansible: Periphery on every LXC;
Komodo adopts Technitium, Forgejo, Komodo
~20 s"] subgraph ST["stacks - Komodo, all at once ~1.5 min; ~8 from an empty node"] direction LR KC["Keycloak and its PostgreSQL;
its image built once, ~7 min"] @@ -82,10 +82,10 @@ Keycloak's image in **stacks** are most of the time (the **stacks** and everything is already right. - **What runs at the same time.** In **base**, each LXC runs its own - part (Ansible's `free` strategy): Gitea and Komodo install while the + part (Ansible's `free` strategy): Forgejo and Komodo install while the LXCs of Keycloak, the observability stack and the tunnel pull the images Komodo deploys on them later - one LXC at a time, so as not to - slow Gitea's and Komodo's first starts on the shared disk. In + slow Forgejo's and Komodo's first starts on the shared disk. In **stacks**, Komodo deploys every Stack at once. - **Keycloak** runs in production mode on an image built once for its PostgreSQL ([ADR-0029](../decisions/0029-keycloak-production-postgresql.md)): diff --git a/docs/roadmap.md b/docs/roadmap.md index c19ac39..81b883c 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -7,10 +7,10 @@ works today and its limits, see [`status.md`](status.md) and ## v1 — scope - Infrastructure target: **Proxmox only** (an already-running server). -- Git server managed by Urbex: **Gitea only**. -- Container registry: **Gitea's built-in registry** +- Git server managed by Urbex: **Forgejo only**. +- Container registry: **Forgejo's built-in registry** ([ADR-0018](decisions/0018-image-build-komodo-gitea-registry.md)). -- CI/CD (image build + deploy): **Komodo**, triggered by Gitea webhooks +- CI/CD (image build + deploy): **Komodo**, triggered by Forgejo webhooks ([ADR-0020](decisions/0020-trunk-releases-gitops-environments.md)). - LXC operating system: **Debian 13**. - Orchestrator: **Docker Compose** (one per LXC). @@ -19,7 +19,7 @@ works today and its limits, see [`status.md`](status.md) and of Pages), **Firebase** (mobile). - Services: **Java, Python, Go**, or any **Docker image** with a ready Dockerfile. -- Base services created on-demand: **Gitea, Komodo, Technitium, Keycloak, +- Base services created on-demand: **Forgejo, Komodo, Technitium, Keycloak, Prometheus + Grafana + Loki**. - Ingress: **Cloudflare Tunnel**, with **Cloudflare Access** in front of the admin UIs ([ADR-0022](decisions/0022-cloudflare-tunnel-access-workers.md)), @@ -96,15 +96,15 @@ What the planned additions of v1 became: - **Hosts beyond Proxmox**: a server you bring over SSH, then Hetzner Cloud, then DigitalOcean (ADR in [urbex#24](https://github.com/urbforge/urbex/issues/24)) - E3-bis (M3). -- **Backups and restore** of Gitea, Komodo, Keycloak, databases and +- **Backups and restore** of Forgejo, Komodo, Keycloak, databases and volumes - E3 (M3). ## v2+ — future evolutions - **Cloud providers** beyond Proxmox: Azure, GCP, AWS (VPS hosts come first, in E3-bis). -- **Git servers** beyond Gitea: GitHub, GitLab. -- **Container registries** beyond Gitea: ghcr.io (paired with GitHub). +- **Git servers** beyond Forgejo: GitHub, GitLab. +- **Container registries** beyond Forgejo: ghcr.io (paired with GitHub). - **CI/CD** beyond Komodo: GitHub Actions, ArgoCD. - **Orchestrators** beyond Docker Compose: Kubernetes. - **Secrets**: optional HashiCorp Vault support. diff --git a/docs/status.md b/docs/status.md index c06ebea..32705c0 100644 --- a/docs/status.md +++ b/docs/status.md @@ -26,10 +26,10 @@ Proxmox VE 9.2 node, see [What has been validated](#what-has-been-validated). | 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 | -| Base-service provisioning | Terraform (5 fixed Debian 13 LXCs: Gitea, Komodo, Technitium, Keycloak, observability; optional resource pool) + Ansible (Docker + each service's compose); idempotent, with a pre-flight check that aborts instead of adopting/duplicating an untracked container | -| Platform setup (`urbex bootstrap`) | Generates admin passwords/secrets into `~/.urbex/credentials.yaml`; creates a Gitea token, org, and `gitops` repo; a Komodo API key, the onboarding key project LXCs join with, Komodo's Gitea git/registry accounts and `URBEX_*` variables; the release Action, the GitOps Procedure and its webhook; `.sops.yaml`; pushes the GitOps repo to Gitea ([platform resources](reference/platform-resources.md)) | +| Base-service provisioning | Terraform (5 fixed Debian 13 LXCs: Forgejo, Komodo, Technitium, Keycloak, observability; optional resource pool) + Ansible (Docker + each service's compose); idempotent, with a pre-flight check that aborts instead of adopting/duplicating an untracked container | +| Platform setup (`urbex bootstrap`) | Generates admin passwords/secrets into `~/.urbex/credentials.yaml`; creates a Forgejo token, org, and `gitops` repo; a Komodo API key, the onboarding key project LXCs join with, Komodo's Forgejo git/registry accounts and `URBEX_*` variables; the release Action, the GitOps Procedure and its webhook; `.sops.yaml`; pushes the GitOps repo to Forgejo ([platform resources](reference/platform-resources.md)) | | Project-service provisioning | Generic `for_each` Terraform module (any number of manifest services); static VMID/IP allocation shared across all projects in one GitOps repo, so they never collide; Docker + Komodo Periphery + sops on each LXC | -| **Builds** | Every push to a project's `main` makes Komodo build each service and push `-:` to Gitea's registry ([ADR-0018](decisions/0018-image-build-komodo-gitea-registry.md), [ADR-0021](decisions/0021-staging-follows-main.md)) | +| **Builds** | Every push to a project's `main` makes Komodo build each service and push `-:` to Forgejo's registry ([ADR-0018](decisions/0018-image-build-komodo-gitea-registry.md), [ADR-0021](decisions/0021-staging-follows-main.md)) | | **Continuous deployment to staging** | Staging follows `main` (`TRACK=main` in its version files): after each build, Komodo commits the new version to the GitOps repo and deploys it ([ADR-0021](decisions/0021-staging-follows-main.md)) | | **Releases** | A `vX.Y.Z` tag (pushed by hand or by `urbex release`, which tags the commit staging runs) gives that commit's images the tag `X.Y.Z` - no rebuild ([ADR-0020](decisions/0020-trunk-releases-gitops-environments.md), [ADR-0021](decisions/0021-staging-follows-main.md)) | | **Environments in the GitOps repo** | `environments////` holds the compose file, `version.env`, `config.env`, and `secrets.sops.env`; Komodo deploys each folder as a Stack on the service's LXC whenever it changes (webhook), and reconciles every 15 minutes | @@ -45,7 +45,7 @@ Proxmox VE 9.2 node, see [What has been validated](#what-has-been-validated). | `urbex teardown` | Destroys the base-service LXCs and urbex's LXC and VM templates (refusing while project environments exist), forgets the generated credentials, keeps the GitOps repo locally | | `urbex destroy` | Takes the environment's Stacks down, removes its folder, `terraform destroy`, clears the allocation ledger; the project's Builds go with its last environment | | `urbex status` | Proxmox container presence, allocation ledger and, per service, the version the GitOps repo asks for against what Komodo runs | -| **Public endpoints (Cloudflare)** | One tunnel for the platform, `cloudflared` on `urbex-tunnel`; Keycloak public, Gitea and Komodo behind Cloudflare Access (one-time PIN for listed e-mails), Komodo's webhook listener public; services with `public: true` published per environment; flat or nested hostnames ([ADR-0022](decisions/0022-cloudflare-tunnel-access-workers.md)) | +| **Public endpoints (Cloudflare)** | One tunnel for the platform, `cloudflared` on `urbex-tunnel`; Keycloak public, Forgejo and Komodo behind Cloudflare Access (one-time PIN for listed e-mails), Komodo's webhook listener public; services with `public: true` published per environment; flat or nested hostnames ([ADR-0022](decisions/0022-cloudflare-tunnel-access-workers.md)) | | **Cloudflare Quick Tunnel** | `cloudflare.quickTunnel: true`, without an account, exposes every `public: true` service on its own `https://*.trycloudflare.com` hostname: a `cloudflared` sidecar on the service's LXC, `urbex apply`/`urbex status` reading the hostname live from it. Not a production substitute for ADR-0022 ([ADR-0025](decisions/0025-cloudflare-quick-tunnel.md)) | | **Logs and resource monitoring** | A Grafana Alloy agent on every LXC - base services and project services - sends every container's logs to Loki, and the LXC's CPU, memory, disk and network and each container's CPU and memory to Prometheus, labelled `kind` (`platform`/`app`/`agent`, from the containers' `urbex.*` Docker labels), `service`, `host`, and `project`/`env` for apps; Grafana comes with both data sources and the *Urbex logs* and *Urbex resources* dashboards, and alerts when an LXC's disk or volume is filling up (85%, 95%) or its memory runs short (under 10% available); `observability.logs: false` stops a project's logs ([ADR-0023](decisions/0023-service-logs-to-loki.md)) | | **Identity (Keycloak)** | A realm per project environment (`-`) with the services' roles and a public OIDC client per frontend; in staging a test user per role (`urbex users staging`) and a password-login client for tests; services with `auth.keycloak` get the issuer and keys ([ADR-0024](decisions/0024-keycloak-realm-per-environment.md)) | @@ -60,9 +60,9 @@ Proxmox VE 9.2 node, see [What has been validated](#what-has-been-validated). | Area | Gap | ADR(s) | |---|---|---| -| Promotion by pull request | `urbex promote` commits to the GitOps repo directly; a PR-gated production folder is a Gitea setting Urbex doesn't manage (see the [cookbook](cookbook.md#gate-production-behind-a-pull-request)) | [0020](decisions/0020-trunk-releases-gitops-environments.md) | +| Promotion by pull request | `urbex promote` commits to the GitOps repo directly; a PR-gated production folder is a Forgejo setting Urbex doesn't manage (see the [cookbook](cookbook.md#gate-production-behind-a-pull-request)) | [0020](decisions/0020-trunk-releases-gitops-environments.md) | | Image cleanup | Every push to `main` leaves an image in the registry; nothing prunes them | [0021](decisions/0021-staging-follows-main.md) | -| Service conventions | Every service should be deployed by Komodo, reached by internal name, tagged by kind (`platform`/`app`/`agent`) and exposed by its kind of endpoint; services reach each other by internal name; admin and internal UIs (Gitea, Komodo, Technitium, Grafana, Prometheus, Loki, Keycloak's `/admin` and `master` realm) behind Cloudflare Access; every service - the platform's included - is a Komodo Stack; a service catalog in the CLI generates names, routes and Access, and a test rejects a service that doesn't declare them | [0027](decisions/0027-service-conventions.md) | +| Service conventions | Every service should be deployed by Komodo, reached by internal name, tagged by kind (`platform`/`app`/`agent`) and exposed by its kind of endpoint; services reach each other by internal name; admin and internal UIs (Forgejo, Komodo, Technitium, Grafana, Prometheus, Loki, Keycloak's `/admin` and `master` realm) behind Cloudflare Access; every service - the platform's included - is a Komodo Stack; a service catalog in the CLI generates names, routes and Access, and a test rejects a service that doesn't declare them | [0027](decisions/0027-service-conventions.md) | | Databases | A PostgreSQL runs as an application of the stack. Every application that uses it gets its own role, schema and password, made by `urbex apply` through a Komodo exec in the PostgreSQL's container before the application starts; it can't touch the other applications' schemas or `public`. An application removed keeps its schema until `urbex apply --delete-data`; `urbex status ` lists the schemas and who uses each; a new major version is refused while the data directory is the old one's ([urbex-cli#9](https://github.com/urbforge/urbex-cli/issues/9), epic [redemptor#17](https://github.com/urbforge/redemptor/issues/17)). The `mysql` and `redis` interfaces, `uses` between stacks, PostgreSQL's own metrics and automated major upgrades are not implemented | [0028](decisions/0028-application-model.md), [0030](decisions/0030-postgresql-application.md) | | Removing a service | Dropping a service from `urbex.yaml` has the next `apply` delete its LXC, and leaves its Stack, folder and internal DNS record behind; an application with named volumes is refused unless `urbex apply --delete-data` | - | | Pre-releases | Only `vX.Y.Z` tags are releases; `-rc.1` and the like are ignored | [0020](decisions/0020-trunk-releases-gitops-environments.md) | @@ -77,7 +77,7 @@ Proxmox VE 9.2 node, see [What has been validated](#what-has-been-validated). | Per-project Proxmox isolation | New projects should get their own resource pool, a group for their users with minimal permissions, and dedicated technical users; today every LXC goes in the platform-wide `proxmox.pool`, managed with the operator's token | [roadmap](roadmap.md) | | Cross-machine concurrency guard | Two machines applying against copies of the same GitOps repo can silently conflict | [0013](decisions/0013-terraform-state-in-gitops-repo.md) | | Cloud providers beyond Proxmox (Azure, GCP, AWS) | Not started - v2+ by design | [roadmap](roadmap.md) | -| Git servers beyond Gitea (GitHub, GitLab) | Not started - v2+ by design | [roadmap](roadmap.md) | +| Git servers beyond Forgejo (GitHub, GitLab) | Not started - v2+ by design | [roadmap](roadmap.md) | | Vault secrets backend | Not started - v2+ by design | [0011](decisions/0011-secrets-sops-age.md) | ## What has been validated @@ -86,7 +86,7 @@ Proxmox VE 9.2 node, see [What has been validated](#what-has-been-validated). Debian 13 systemd machines reachable over SSH at the static IPs Urbex allocates - the same thing an LXC is to Ansible - and checks every step. Only `terraform` (a stub) and the Proxmox API (a stub listing the -machines and keeping their mount points) are faked; Ansible, Docker, Gitea, Komodo, sops, and the other +machines and keeping their mount points) are faked; Ansible, Docker, Forgejo, Komodo, sops, and the other base services are real. It covers: 1. `urbex bootstrap`: all five base-service roles, the platform setup, @@ -157,7 +157,7 @@ project's LXCs, their ZFS volumes and pool membership, its Komodo Servers, Stacks and Build, the project webhook, and its files in the GitOps repo (environment folders, Terraform state and files, Ansible inventories, ledger entries) were gone; the base services, the project -repo and its images on Gitea (kept by design) untouched. It surfaced +repo and its images on Forgejo (kept by design) untouched. It surfaced three bugs, fixed: `destroy` worked from a stale copy of the GitOps repo and conflicted with the release Action's commits (now it refreshes, and removes the folder last); a Build busy with a push made during `destroy` @@ -216,7 +216,7 @@ where Technitium has no prior configuration at all. **On a real Cloudflare account** (Free plan zone, 2026-10-02), with a pool-scoped Proxmox token: bootstrap published Keycloak -(`auth-urbex.`, issuer public), Gitea and Komodo behind Access +(`auth-urbex.`, issuer public), Forgejo and Komodo behind Access (redirect to the team's login, one-time PIN), and the webhook listener; a project with a public API and a web frontend then ran on staging (`api-staging-hello-urbex`, `staging-hello-urbex`), followed `main` - @@ -225,7 +225,7 @@ released and promoted to prod (`api-hello-urbex`, `hello-urbex`, the same build). `destroy` of both environments and `teardown` left nothing of urbex on the account - tunnel, routes, DNS records, Access objects, Workers and their domains - and everything else untouched. It surfaced: -Access set up after routing (a failed Access setup left Gitea and Komodo +Access set up after routing (a failed Access setup left Forgejo and Komodo exposed for a few minutes; now Access comes first and nothing is published without it), Access errors carried in a different field, and a Workers API answering 200 with no body. @@ -257,12 +257,12 @@ Roughly in the order that makes each subsequent item worth doing. 1. ~~**Validate against a real Proxmox.**~~ Done (see [What has been validated](#what-has-been-validated)). -2. ~~**Image build & push.**~~ Done: Komodo builds, Gitea's registry +2. ~~**Image build & push.**~~ Done: Komodo builds, Forgejo's registry stores ([ADR-0018](decisions/0018-image-build-komodo-gitea-registry.md)). ### P1 - complete the v1 promise (in dependency order) -3. ~~**Push the GitOps repo to Gitea.**~~ Done. +3. ~~**Push the GitOps repo to Forgejo.**~~ Done. 4. ~~**Komodo-driven rollouts, from the GitOps repo.**~~ Done ([ADR-0020](decisions/0020-trunk-releases-gitops-environments.md)). 5. ~~**DNS registration in Technitium.**~~ Done @@ -304,7 +304,7 @@ Roughly in the order that makes each subsequent item worth doing. ### P4 - v2+ scope (deliberately deferred) -14. Cloud providers beyond Proxmox, Git servers beyond Gitea (and +14. Cloud providers beyond Proxmox, Git servers beyond Forgejo (and ghcr.io as registry), CI/CD beyond Komodo (GitHub Actions, ArgoCD), Kubernetes as orchestrator, Vault - already scoped for later in [`roadmap.md`](roadmap.md); no urgency diff --git a/docs/upgrading.md b/docs/upgrading.md index fc06d71..8a91e9a 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -49,13 +49,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.0. +which its `cli` skill states: urbex 0.1.0 for plugin 0.2.1. ### Plugin and CLI versions | Plugin | urbex | |---|---| -| 0.2.0 | 0.1.0 or later, major 0 | +| 0.2.0, 0.2.1 | 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 f29c580..0360f78 100644 --- a/skills/cli/SKILL.md +++ b/skills/cli/SKILL.md @@ -47,7 +47,7 @@ Neither: use the `setup` skill. ## Versions -This plugin (0.2.0) needs **urbex 0.1.0 or later, with the same major +This plugin (0.2.1) needs **urbex 0.1.0 or later, with the same major version (0)**. Once per session, run `urbex version` (`urbex-op 'urbex version'`): @@ -103,13 +103,13 @@ a yes for that command: - `urbex bootstrap` (it creates or changes the platform's LXCs); - `urbex apply prod`, `urbex deploy prod ...`, `urbex promote`; -- `urbex release` (it tags a version on Gitea; versions are never +- `urbex release` (it tags a version on Forgejo; versions are never reused); - `urbex destroy `, `urbex teardown --yes`; - any `--delete-data` (it deletes data, nothing is kept) or `--allow-major` (the data may need a migration first); - `urbex secret set` or `unset` in prod; -- a push to the project's `main` on Gitea (it deploys to staging). +- a push to the project's `main` on Forgejo (it deploys to staging). `init`, `plan`, `status`, `users`, `secret list` and `bootstrap --dry-run` change nothing: run them freely. So are `apply staging` and @@ -124,7 +124,7 @@ suggests. Don't add a flag that overrides the refusal on your own. - Never print, read or copy `credentials.yaml`, `age.key`, or a decrypted `secrets.sops.env`, and never ask for a token, password or key in the chat. To check that a credential is set, test for the key - without printing the value (`grep -q '^giteaToken:' ...`). + without printing the value (`grep -qE '^(forgeToken|giteaToken):' ...`: `giteaToken` in a workspace from urbex 0.1.0). - **Setting a secret**: the value must not go through the chat. Give the user the commands to run in their own terminal: ```sh @@ -148,7 +148,7 @@ suggests. Don't add a flag that overrides the refusal on your own. | The user says | Run | |---|---| -| "deploy to staging" | Push to `main` on Gitea (staging follows it); `urbex status staging` until it runs the new commit. The first time, `urbex apply staging`. | +| "deploy to staging" | Push to `main` on Forgejo (staging follows it); `urbex status staging` until it runs the new commit. The first time, `urbex apply staging`. | | "what runs where?" | `urbex status` (platform and every project), `urbex status ` (one project). | | "release and promote" | `urbex release`, then `urbex promote`; ask first. | | "roll back prod" | `urbex deploy prod --version `; ask first. | @@ -161,7 +161,7 @@ suggests. Don't add a flag that overrides the refusal on your own. | "my push didn't deploy" / "the build failed" | `urbex status staging`, then the cookbook's *A push didn't deploy* and *A build or a deploy failed*; logs in Grafana and Komodo. | | "apps don't come back after a reboot" | `urbex status `, its *Reconciler* section, and the cookbook's *The reconciler holds applications back*. | | "remove staging" / "remove the project" | `urbex destroy ` for each environment; ask first. | -| "remove the whole platform" | `urbex teardown`, then `--yes` after the user has read what it destroys. Every repository and image on Gitea goes with it. | +| "remove the whole platform" | `urbex teardown`, then `--yes` after the user has read what it destroys. Every repository and image on Forgejo goes with it. | After a command, report what changed and where it runs (the addresses it printed), in a few lines. For errors, quote the CLI's one-line message: diff --git a/skills/setup/SKILL.md b/skills/setup/SKILL.md index 61be4be..7901fd9 100644 --- a/skills/setup/SKILL.md +++ b/skills/setup/SKILL.md @@ -88,7 +88,7 @@ LAN, the free block you propose. Then ask only: - **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, Gitea and Komodo behind + own zone (public HTTPS on their domain, Forgejo and Komodo behind Cloudflare Access). It can be added later. ## 3. Get Urbex and the workspace @@ -287,9 +287,9 @@ resolve names*) and [known limitations](${CLAUDE_PLUGIN_ROOT}/docs/known-limitat the rest. At the end, `urbex-op -w ~/urbex-work 'urbex status'` lists every -address. Give the user the Gitea, Komodo, Grafana and Keycloak +address. Give the user the Forgejo, Komodo, Grafana and Keycloak addresses, and tell them the `urbex-admin` passwords are in -`~/urbex-work/home/.urbex/credentials.yaml` (`giteaAdminPassword`, +`~/urbex-work/home/.urbex/credentials.yaml` (`forgeAdminPassword`, `komodoAdminPassword`, ...), without opening it. Tell them to back up the workspace: after a teardown, `gitops/` is the GitOps repo's only copy. @@ -303,15 +303,15 @@ copy. values in the code and proposes them the same way; commit it. 3. Ask, then `urbex-op -w ~/urbex-work 'cd /work/projects/ && urbex apply staging'`. - It creates the LXCs, the repository on Gitea from the local `main`, + It creates the LXCs, the repository on Forgejo from the local `main`, the build, and deploys `main`. Give the user the addresses it prints. -4. Gitea is now the app's remote: every push to `main` is deployed to +4. Forgejo is now the app's remote: every push to `main` is deployed to staging. ```sh cd ~/urbex-work/projects/ git remote add urbex http://:3000/urbex/.git ``` - Pushing asks for Gitea credentials: the user's own Gitea account, or + Pushing asks for Forgejo credentials: the user's own Forgejo account, or `urbex-admin` with its password from the credentials file, typed by the user. 5. Production, each step only when the user asks: `urbex apply prod` From 20580f9e2bd8bb410b7283437ef5b28ab25a3ebb Mon Sep 17 00:00:00 2001 From: Teg79 Date: Wed, 18 Nov 2026 08:25:13 +0100 Subject: [PATCH 2/2] docs(changelog): plugin 0.2.1 and the docs of Forgejo LTS Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0182yxsfwRowwnxCfgrQwjnA --- CHANGELOG.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 62eb3c9..4ea7579 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,24 @@ workflow refuses a tag whose version has no entry here. ## [Unreleased] +### Plugin 0.2.1 + +Needs **urbex 0.1.0 or later, major 0**. + +- **Changed**: the skills name the forge Forgejo, and its credentials + `forgeToken` and `forgeAdminPassword`; the `cli` skill's token check + accepts `giteaToken` too, for a workspace written by urbex 0.1.0. + +### Docs + +- **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 + 1.24. +- **Changed**: Gitea is Forgejo throughout; the reference documents + `forgeToken`, `forgeAdminPassword`, `URBEX_FORGE_*` and `git.forgeUrl`, + the old names still read. + ## [0.1.0] - 2026-11-17 The first preview release: the docs install urbex from the