Blocks · Developer tools

dev/forgejo

Forgejo Git forge. Forgejo with its repositories, database, SSH host key and secrets on a replicated volume behind a VIP.

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

forgejo.yaml
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.

KeyDefaultMeaning
rootURLrequiredURL users browse to; links and clone URLs are built from it.
adminUserrequiredAdministrator, created on first start. Forgejo reserves some names, such as admin.
adminPasswordrequiredThe administrator's password, at least 8 characters; applied on every start. Sealed: kept out of the stored block (block secrets).
adminEmailrequiredThe administrator's email address.
allowRegistrationfalseLet anyone who reaches Forgejo register an account.
port13000Forgejo's HTTP port, the target_port of 80.
sshPort12222The built-in SSH server's port, the target_port of 2222.
publicSSHPort2222SSH port shown in clone URLs: the port exposed on the VIP.
settingsnoneExtra 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/caddy in front.
  • SSH on port 22 of the VIP.

Source

All block types · Fields every block shares