Forgejo
Forgejo is a lightweight software forge, with a highlight on being completely free software. It's a fork of Gitea.
This article extends the documentation in the NixOS manual.
Usage
NixOS provides a module for easily setting-up a Forgejo server, here is an example of typical usage with some optional features:
- Use Nginx to enable easy https configuration
- You can choose what database you want to use (postgres in this example)
- Support for git-lfs
- Disabling registrations for personal servers
- Support for Actions, similar to Github Actions
- Support for sending email notifications
- No exposed secrets in the nix store, see Comparison of secret managing schemes and choose one
{ lib, pkgs, config, ... }:
let
cfg = config.services.forgejo;
srv = cfg.settings.server;
in
{
services.nginx = {
virtualHosts.${cfg.settings.server.DOMAIN} = {
forceSSL = true;
enableACME = true;
extraConfig = ''
client_max_body_size 512M;
'';
locations."/".proxyPass = "http://localhost:${toString srv.HTTP_PORT}";
};
};
services.forgejo = {
enable = true;
database.type = "postgres";
# Enable support for Git Large File Storage
lfs.enable = true;
settings = {
server = {
DOMAIN = "git.example.com";
# You need to specify this to remove the port from URLs in the web UI.
ROOT_URL = "https://${srv.DOMAIN}/";
HTTP_PORT = 3000;
};
# You can temporarily allow registration to create an admin user.
service.DISABLE_REGISTRATION = true;
# Add support for actions, based on act: https://github.com/nektos/act
actions = {
ENABLED = true;
DEFAULT_ACTIONS_URL = "github";
};
# Sending emails is completely optional
# You can send a test email from the web UI at:
# Profile Picture > Site Administration > Configuration > Mailer Configuration
mailer = {
ENABLED = true;
SMTP_ADDR = "mail.example.com";
FROM = "noreply@${srv.DOMAIN}";
USER = "noreply@${srv.DOMAIN}";
};
};
secrets = {
mailer.PASSWD = config.age.secrets.forgejo-mailer-password.path;
};
};
age.secrets.forgejo-mailer-password = {
file = ../secrets/forgejo-mailer-password.age;
mode = "400";
owner = "forgejo";
};
}
Setting up OpenSSH integration
If you plan to use SSH keys for authenticating your git usage, there's a little extra configuration to be done to set that up:
{ config, lib, ... }: {
...
services = {
forgejo.settings.server.SSH_PORT = lib.head config.services.openssh.ports;
openssh.settings.AcceptEnv = "GIT_PROTOCOL";
};
...
}
Actions Runner
According to the documentation the Forgejo runner is:
A daemon that fetches workflows to run from a Forgejo instance, executes them, sends back with the logs and ultimately reports its success or failure.
In order to use Actions, you will need to setup at least one Runner. You can use your server, another machine or both as runners.
To register a runners you will need to generate a token. https://forgejo.org/docs/latest/user/actions/#forgejo-runner
You can create a server-wide Runner by going to Profile Picture > Site Administration > Actions > Runners > Create new Runner.
Store your token in your secrets management system of choice, then add the following to the configuration of the machine to be used as a runner:
{ pkgs, config, ... }: {
services.gitea-actions-runner = {
package = pkgs.forgejo-runner;
instances.default = {
enable = true;
name = "monolith";
url = "https://git.example.com";
# Obtaining the path to the runner token file may differ
# tokenFile should be in format TOKEN=<secret>, since it's EnvironmentFile for systemd
tokenFile = config.age.secrets.forgejo-runner-token.path;
labels = [
"ubuntu-latest:docker://node:16-bullseye"
"ubuntu-22.04:docker://node:16-bullseye"
"ubuntu-20.04:docker://node:16-bullseye"
"ubuntu-18.04:docker://node:16-buster"
## optionally provide native execution on the host:
# "native:host"
];
};
};
}
Ensure users
Using the following snippet, you can declaratively ensure these users will always exist:
sops.secrets.forgejo-admin-password.owner = "forgejo";
systemd.services.forgejo.preStart = let
adminCmd = "${lib.getExe cfg.package} admin user";
pwd = config.sops.secrets.forgejo-admin-password;
user = "joe"; # Note, Forgejo doesn't allow creation of an account named "admin"
in ''
${adminCmd} create --admin --email "root@localhost" --username ${user} --password "$(tr -d '\n' < ${pwd.path})" || true
## uncomment this line to change an admin user which was already created
# ${adminCmd} change-password --username ${user} --password "$(tr -d '\n' < ${pwd.path})" || true
'';
You may remove the --admin flag to create only a regular user. The || true is necessary, so the snippet does not fail if the user already exists.
Naturally, instead of sops, you may use any file or secret manager, as explained above.
Adding a custom theme to Forgejo
Its possible to customize the CSS styles and HTML templates of Forgejo declaratively using Nix. In this simple example i will show you how to: Create a basic theme, set it as the default theme and modify the home template.
{ config, pkgs, lib, ... }: {
...
systemd.tmpfiles.rules = [
"d '${config.services.forgejo.customDir}/templates' - forgejo forgejo - -"
"d '${config.services.forgejo.customDir}/public' - forgejo forgejo - -"
"d '${config.services.forgejo.customDir}/public/assets' - forgejo forgejo - -"
"d '${config.services.forgejo.customDir}/public/assets/css' - forgejo forgejo - -"
"C+ '${config.services.forgejo.customDir}/public/assets/css/theme-custom.css' - forgejo forgejo - ${
./theme-custom.css
}"
"C+ '${config.services.forgejo.customDir}/templates/home.tmpl' - forgejo forgejo - ${
./home.tmpl
}"
];
forgejo.settings.ui = {
DEFAULT_THEME = "custom";
THEMES = "forgejo-auto,forgejo-light,forgejo-dark,custom";
};
...
}
@import url('https://fonts.googleapis.com/css2?family=Space+Mono&display=swap');
@import "./theme-forgejo-auto.css";
:root {
--fonts-override: "Space Mono";
}
[[:Template:Template "base/head" .]]
<div role="main" aria-label="[[:Template:If .IsSigned]][[:Template:Ctx.Locale.Tr "dashboard"]][[:Template:Else]][[:Template:Ctx.Locale.Tr "home"]][[:Template:End]]" class="page-content home">
<div class="tw-mb-8 tw-px-8">
<div class="center">
<div class="hero">
<h1 class="ui icon header title">
Forgejo hosted on NixOS!
</h1>
</div>
</div>
</div>
</div>
[[:Template:Template "base/footer" .]]