Overview
Runs Forgejo, a Git forge with repositories, issues, pull requests and packages. The block is a singleton that runs where its volume's primary is, behind one VIP serving both HTTP and Forgejo's built-in SSH server. Everything Forgejo keeps lives on the volume: repositories, the SQLite database, LFS objects, attachments, the SSH host key and the secrets that sign sessions and tokens. The block writes app.ini on every start and creates the administrator account on the first.
- Shape
- Singleton on a replicated volume
- Reached at
- VIP on HTTP and SSH
- Node package
pkgs.forgejo
Fetched on demand: the first time a block of this type is placed on a node, its agent fetches pkgs.forgejo, built from the node's own nixpkgs so the NixOS binary cache serves it. That first placement needs network access (or a binary cache on the LAN) and waits for the download; later placements on that node start at once.
Example
apiVersion: expanse.io/v1 kind: Block metadata: name: forge namespace: default spec: type: dev/forgejo replicas: 1 strategy: kind: SINGLETON resources: requests: cpu: 500m memory: 512Mi storage: - name: forgejo-data size: 20Gi replication: 3 mountPath: /var/lib/forgejo config: rootURL: http://git.example.com/ adminUser: gitadmin adminPassword: change-me-please adminEmail: ops@example.com network: ports: - name: http port: 80 target_port: 13000 protocol: tcp expose: EXPOSE_VIP - name: ssh port: 2222 target_port: 12222 protocol: tcp expose: EXPOSE_VIP health_check: readiness: type: PROBE_TCP port: 13000 period_seconds: 2
$ expanse ctl block apply -f forgejo.yaml --dry-run # validate only $ expanse ctl block apply -f forgejo.yaml
Configuration
Keys go under spec.config and are checked against the type's JSON Schema when the block is applied. A default is what the block uses when the key is unset.
| Key | Default | Meaning |
|---|---|---|
rootURL | required | URL users browse to; links and clone URLs are built from it. |
adminUser | required | Administrator, created on first start. Forgejo reserves some names, such as admin. |
adminPassword | required | The administrator's password, at least 8 characters; applied on every start. Sealed: kept out of the stored block (block secrets). |
adminEmail | required | The administrator's email address. |
allowRegistration | false | Let anyone who reaches Forgejo register an account. |
port | 13000 | Forgejo's HTTP port, the target_port of 80. |
sshPort | 12222 | The built-in SSH server's port, the target_port of 2222. |
publicSSHPort | 2222 | SSH port shown in clone URLs: the port exposed on the VIP. |
settings | none | Extra app.ini settings by section, applied after the block's own, such as a mailer or an external database. |
Using it
Point git.example.com at the block's VIP (expanse ctl block get forge). Clone URLs then read http://git.example.com/<owner>/<repo>.git and ssh://git@git.example.com:2222/<owner>/<repo>.git. SSH is exposed on 2222, not 22, because the node's own sshd already listens on 22. For HTTPS, put a web/caddy block in front and set rootURL to the https:// address.
settings takes any Forgejo setting by section:
settings: database: DB_TYPE: mysql HOST: 10.0.0.40:3306 NAME: forgejo USER: forgejo PASSWD: secret mailer: ENABLED: true SMTP_ADDR: smtp.example.com
A db/mariadb block's VIP can be the external database; Expanse's VM test covers only SQLite. Moving state off the volume means a failover no longer carries it. The block passes adminPassword on Forgejo's command line at start, so it shows briefly in the serving node's process list.
When a node fails
When the serving node dies, the block, its volume's primary and its VIP move together to a survivor, and Forgejo starts there on the same volume. Pushes, clones and page loads in flight fail; clients retry against the same address and see the same SSH host key, so ssh raises no warning. Logged-in users stay logged in, and a push acknowledged before the crash is still there.
Limits
- One Forgejo per set of repositories: several instances would need shared storage and an external database.
- Forgejo Actions runners are not part of the block.
- No HTTPS inside the block; use
web/caddyin front. - SSH on port 22 of the VIP.
Source
- docs/FORGEJO.md: the Expanse guide this page follows.
- nix/blocks/dev/forgejo: the type's identity and JSON Schema.