Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "urbex",
"version": "0.2.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",
Expand Down
18 changes: 18 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
14 changes: 7 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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,
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -266,7 +266,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:

Expand Down
34 changes: 17 additions & 17 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,20 @@ 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]
end

subgraph Proxmox["Proxmox server"]
subgraph Base["Base services LXCs"]
Gitea
Forgejo
Komodo
Technitium[Technitium DNS]
Keycloak
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 <env>` | Computes the infrastructure changes needed (Terraform diff + Ansible config) for an environment, without applying them. |
| `urbex apply <env>` | 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`. |
Expand All @@ -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),
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
24 changes: 12 additions & 12 deletions docs/cookbook.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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**
Expand Down Expand Up @@ -198,7 +198,7 @@ prod --version <commit>` 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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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-<env>`; 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
Expand Down Expand Up @@ -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

Expand All @@ -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`
Expand All @@ -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
Expand All @@ -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://<its LXC's IP>:<port>` - `state/allocations.json` in the GitOps repo |
Expand All @@ -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:

Expand Down Expand Up @@ -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 <same> --ref <commit>`). A tag
pushed while `main` is still building that commit is fine: runs of the
Action queue up.
Expand Down
2 changes: 1 addition & 1 deletion docs/decisions/0004-gitops-gitea-komodo.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/decisions/0018-image-build-komodo-gitea-registry.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading