Official NixOS Wiki

Forgejo: Difference between revisions

← Older edit
VisualWikitext
Dave (talk | contribs)
2 edits
Add way to create/ensure users without wizard/webpage
Onny (talk | contribs)
285 edits
Add see also section
 
(9 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Infobox application
| name = Forgejo
| type = Free and open-source software forge
| image = Forgejo_logo.svg
| website = https://forgejo.org/
| documentation = https://forgejo.org/docs/latest/
| bugTracker = https://codeberg.org/forgejo/forgejo/issues
| platform = Cross-platform
| initialRelease = 15 December 2022
| latestRelease = 11.0.7; 26 October 2025
| programmingLanguage = Go, JavaScript
}}
[https://forgejo.org/ Forgejo] is a lightweight [[wikipedia:Software_forge|software forge]], with a highlight on being completely free software. It's a fork of [[Gitea]].
[https://forgejo.org/ Forgejo] is a lightweight [[wikipedia:Software_forge|software forge]], with a highlight on being completely free software. It's a fork of [[Gitea]].


Line 4: Line 17:


== Usage ==
== Usage ==
NixOs provides a module for easily setting-up a Forgejo server, here is an example of typical usage with some optional features:
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
* Use Nginx to enable easy https configuration
Line 60: Line 73:
       };
       };
     };
     };
     mailerPasswordFile = config.age.secrets.forgejo-mailer-password.path;
     secrets = {
      mailer.PASSWD = config.age.secrets.forgejo-mailer-password.path;
    };
   };
   };


Line 71: Line 86:
</syntaxhighlight>
</syntaxhighlight>


== Runner ==
== 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:
{{File|3={ config, lib, ... }: {
  ...
  services = {
    forgejo.settings.server.SSH_PORT = lib.head config.services.openssh.ports;
    openssh.settings.AcceptEnv = "GIT_PROTOCOL";
  };
  ...
}|name=/etc/nixos/configuration.nix|lang=nix}}
 
== Actions Runner ==
According to the [https://forgejo.org/docs/latest/admin/actions/#forgejo-runner documentation] the <code>Forgejo runner</code> is:<blockquote>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.</blockquote>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.
According to the [https://forgejo.org/docs/latest/admin/actions/#forgejo-runner documentation] the <code>Forgejo runner</code> is:<blockquote>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.</blockquote>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
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.''
You can create a server-wide Runner by going to ''Profile Picture > Site Administration > Actions > Runners > Create new Runner.''
Store your token in your [[Comparison of secret managing schemes|secrets management system]] of choice, then add the following to the configuration of the machine to be used as a runner:<syntaxhighlight lang="nixos">
Store your token in your [[Comparison of secret managing schemes|secrets management system]] of choice, then add the following to the configuration of the machine to be used as a runner:<syntaxhighlight lang="nixos">
{ pkgs, config, ... }: {
{ pkgs, config, ... }: {
   services.gitea-actions-runner = {
   services.gitea-actions-runner = {
     package = pkgs.forgejo-actions-runner;
     package = pkgs.forgejo-runner;
     instances.default = {
     instances.default = {
       enable = true;
       enable = true;
Line 89: Line 111:
       url = "https://git.example.com";
       url = "https://git.example.com";
       # Obtaining the path to the runner token file may differ
       # 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;
       tokenFile = config.age.secrets.forgejo-runner-token.path;
       labels = [
       labels = [
Line 104: Line 127:


== Ensure users ==
== Ensure users ==
Using the following snippet, you can ensure users:
Using the following snippet, you can declaratively ensure these users will always exist:
<syntaxhighlight lang="nixos">
<syntaxhighlight lang="nixos">
systemd.services.forgejo.preStart = ''
sops.secrets.forgejo-admin-password.owner = "forgejo";
create="${lib.getExe config.services.forgejo.package} admin user create"
systemd.services.forgejo.preStart = let
$create --admin --email "you@example.com" --username you --password "`cat ${config.sops.secrets.forgejo.path}`" &>/dev/null || true
  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
'';  
 
</syntaxhighlight>
</syntaxhighlight>
You may remove the <code>--admin</code> flag to create only a regular user. The <code>&>/dev/null || true</code> is necessary, so 1. The code snippet doesn't write to the log, 2. The snippet does not fail if the user already exists.
You may remove the <code>--admin</code> flag to create only a regular user. The <code>|| true</code> 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.
Naturally, instead of sops, you may use any file or secret manager, as explained above.
== Adding a custom theme to Forgejo ==
Its possible to [https://forgejo.org/docs/latest/contributor/customization/ 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.
{{File|3={ 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";
  };
  ...
}|name=/etc/nixos/forgejo/default.nix|lang=nix}}{{File|3=@import url('https://fonts.googleapis.com/css2?family=Space+Mono&display=swap');
@import "./theme-forgejo-auto.css";
:root {
    --fonts-override: "Space Mono";
}|name=/etc/nixos/forgejo/theme-custom.css|lang=css}}{{File|3={{template "base/head" .}}
<div role="main" aria-label="{{if .IsSigned}}{{ctx.Locale.Tr "dashboard"}}{{else}}{{ctx.Locale.Tr "home"}}{{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 "base/footer" .}}|name=/etc/nixos/forgejo/home.tmpl|lang=gotmpl}}
== See also ==
* [[Gitlab]], a web application offers git repository management, code reviews, issue tracking, activity feeds and wikis.
* [[Gitea]], a web app, Git development repository and project management.


[[Category:Web Applications]]
[[Category:Web Applications]]
[[Category:Server]]
[[Category:Server]]
[[Category:NixOS Manual]]
[[Category:NixOS Manual]]
Retrieved from "https://wiki.nixos.org/wiki/Forgejo"