selfhostblocks/modules/services/forgejo/docs/default.md

Forgejo Service

Defined in /modules/services/forgejo.nix.

This NixOS module is a service that sets up a Forgejo instance.

Compared to the stock module from nixpkgs, this one sets up, in a fully declarative manner, LDAP and SSO integration as well as one local runner.

Features

• Declarative creation of users, admin or not.
• Also declarative LDAP Configuration. Manual.
• Declarative SSO Configuration. Manual.
• Declarative local runner Configuration.
• Access through subdomain using reverse proxy. Manual.
• Access through HTTPS using reverse proxy. Manual.
• Backup through the backup block. Manual.

Usage

Initial Configuration

The following snippet enables Forgejo and makes it available under the forgejo.example.com endpoint.

shb.forgejo = {
  enable = true;
  subdomain = "forgejo";
  domain = "example.com";

  users = {
    "theadmin" = {
      isAdmin = true;
      email = "theadmin@example.com";
      password.result = config.shb.sops.secret.forgejoAdminPassword.result;
    };
    "theuser" = {
      email = "theuser@example.com";
      password.result = config.shb.sops.secret.forgejoUserPassword.result;
    };
  };
};

shb.sops.secret."forgejo/admin/password" = {
  request = config.shb.forgejo.users."theadmin".password.request;
};

shb.sops.secret."forgejo/user/password" = {
  request = config.shb.forgejo.users."theuser".password.request;
};

Two users are created, theadmin and theuser, respectively with the passwords forgejo/admin/password and forgejo/user/password from a SOPS file.

This assumes secrets are setup with SOPS as mentioned in the secrets setup section of the manual. Secrets can be randomly generated with nix run nixpkgs#openssl -- rand -hex 64.

Forgejo through HTTPS

:::: {.note} We will build upon the Initial Configuration section, so please follow that first. ::::

If the shb.ssl block is used (see manual on how to set it up), the instance will be reachable at https://forgejo.example.com.

Here is an example with Let's Encrypt certificates, validated using the HTTP method:

shb.certs.certs.letsencrypt."example.com" = {
  domain = "example.com";
  group = "nginx";
  reloadServices = [ "nginx.service" ];
  adminEmail = "myemail@mydomain.com";
};

Then you can tell Forgejo to use those certificates.

shb.certs.certs.letsencrypt."example.com".extraDomains = [ "forgejo.example.com" ];

shb.forgejo = {
  ssl = config.shb.certs.certs.letsencrypt."example.com";
};

With LDAP Support

:::: {.note} We will build upon the HTTPS section, so please follow that first. ::::

We will use the LLDAP block provided by Self Host Blocks. Assuming it has been set already, add the following configuration:

shb.forgejo.ldap = {
  enable = true;
  host = "127.0.0.1";
  port = config.shb.lldap.ldapPort;
  dcdomain = config.shb.lldap.dcdomain;
  adminPassword.result = config.shb.sops.secret."forgejo/ldap/adminPassword".result
};

shb.sops.secret."forgejo/ldap/adminPassword" = {
  request = config.shb.forgejo.ldap.adminPassword.request;
  settings.key = "ldap/userPassword";
};

The shb.forgejo.ldap.adminPasswordFile must be the same as the shb.lldap.ldapUserPasswordFile which is achieved with the key option. The other secrets can be randomly generated with nix run nixpkgs#openssl -- rand -hex 64.

And that's it. Now, go to the LDAP server at http://ldap.example.com, create the forgejo_user and forgejo_admin groups, create a user and add it to one or both groups. When that's done, go back to the Forgejo server at http://forgejo.example.com and login with that user.

With SSO Support

:::: {.note} We will build upon the LDAP section, so please follow that first. ::::

We will use the SSO block provided by Self Host Blocks. Assuming it has been set already, add the following configuration:

shb.forgejo.sso = {
  enable = true;
  endpoint = "https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}";

  secretFile = <path/to/oidcForgejoSharedSecret>;
  secretFileForAuthelia = <path/to/oidcForgejoSharedSecret>;
};

Passing the ssl option will auto-configure nginx to force SSL connections with the given certificate.

The shb.forgejo.sso.secretFile and shb.forgejo.sso.secretFileForAuthelia options must have the same content. The former is a file that must be owned by the forgejo user while the latter must be owned by the authelia user. I want to avoid needing to define the same secret twice with a future secrets SHB block.

SMTP

To send e-mails, notifications, define the SMTP settings like so:

{
  services.forgejo = {
    smtp = {
      host = "smtp.mailgun.org";
      port = 587;
      username = "postmaster@mg.${domain}";
      from_address = "authelia@${domain}";
      password.result = config.shb.sops.secret."forgejo/smtpPassword".result;
    };
  };

  shb.sops.secret."forgejo/smtpPassword" = {
    request = config.shb.forgejo.smtp.password.request;
  };
}

Backup

Every hour, Forgejo takes a backup using the built-in dump command. This backup is ephemeral and should be moved in a permanent location. This can be accomplished using the following config.

Backing up Forgejo using the Restic block is done like so:

shb.restic.instances."forgejo" = {
  request = config.shb.forgejo.backup;
  settings = {
    enable = true;
  };
};

The name "forgejo" in the instances can be anything. The config.shb.forgejo.backup option provides what directories to backup. You can define any number of Restic instances to backup Forgejo multiple times.

Extra Settings

Other Forgejo settings can be accessed through the nixpkgs stock service.

Debug

In case of an issue, check the logs for systemd service forgejo.service.

Enable verbose logging by setting the shb.forgejo.debug boolean to true.

Access the database with sudo -u forgejo psql.

Options Reference

id-prefix: services-forgejo-options-
list-id: selfhostblocks-service-forgejo-options
source: @OPTIONS_JSON@