nixos/modules/services/misc/forgejo.md

   1 # Forgejo {#module-forgejo}
   2
   3 Forgejo is a soft-fork of gitea, with strong community focus, as well
   4 as on self-hosting and federation. [Codeberg](https://codeberg.org) is
   5 deployed from it.
   6
   7 See [upstream docs](https://forgejo.org/docs/latest/).
   8
   9 The method of choice for running forgejo is using [`services.forgejo`](#opt-services.forgejo.enable).
  10
  11 ::: {.warning}
  12 Running forgejo using `services.gitea.package = pkgs.forgejo` is no longer
  13 recommended.
  14 If you experience issues with your instance using `services.gitea`,
  15 **DO NOT** report them to the `services.gitea` module maintainers.
  16 **DO** report them to the `services.forgejo` module maintainers instead.
  17 :::
  18
  19 ## Migration from Gitea {#module-forgejo-migration-gitea}
  20
  21 ::: {.note}
  22 Migrating is, while not strictly necessary at this point, highly recommended.
  23 Both modules and projects are likely to diverge further with each release.
  24 Which might lead to an even more involved migration.
  25 :::
  26
  27 ### Full-Migration {#module-forgejo-migration-gitea-default}
  28
  29 This will migrate the state directory (data), rename and chown the database and
  30 delete the gitea user.
  31
  32 ::: {.note}
  33 This will also change the git remote ssh-url user from `gitea@` to `forgejo@`,
  34 when using the host's openssh server (default) instead of the integrated one.
  35 :::
  36
  37 Instructions for PostgreSQL (default). Adapt accordingly for other databases:
  38
  39 ```sh
  40 systemctl stop gitea
  41 mv /var/lib/gitea /var/lib/forgejo
  42 runuser -u postgres -- psql -c '
  43   ALTER USER gitea RENAME TO forgejo;
  44   ALTER DATABASE gitea RENAME TO forgejo;
  45 '
  46 nixos-rebuild switch
  47 systemctl stop forgejo
  48 chown -R forgejo:forgejo /var/lib/forgejo
  49 systemctl restart forgejo
  50 ```
  51
  52 ### Alternatively, keeping the gitea user {#module-forgejo-migration-gitea-impersonate}
  53
  54 Alternatively, instead of renaming the database, copying the state folder and
  55 changing the user, the forgejo module can be set up to re-use the old storage
  56 locations and database, instead of having to copy or rename them.
  57 Make sure to disable `services.gitea`, when doing this.
  58
  59 ```nix
  60 {
  61   services.gitea.enable = false;
  62
  63   services.forgejo = {
  64     enable = true;
  65     user = "gitea";
  66     group = "gitea";
  67     stateDir = "/var/lib/gitea";
  68     database.name = "gitea";
  69     database.user = "gitea";
  70   };
  71
  72   users.users.gitea = {
  73     home = "/var/lib/gitea";
  74     useDefaultShell = true;
  75     group = "gitea";
  76     isSystemUser = true;
  77   };
  78
  79   users.groups.gitea = {};
  80 }
  81 ```