diff options
Diffstat (limited to 'content/theses/self-sufficiency/git-forge.md')
| -rw-r--r-- | content/theses/self-sufficiency/git-forge.md | 170 |
1 files changed, 170 insertions, 0 deletions
diff --git a/content/theses/self-sufficiency/git-forge.md b/content/theses/self-sufficiency/git-forge.md new file mode 100644 index 0000000..644c893 --- /dev/null +++ b/content/theses/self-sufficiency/git-forge.md @@ -0,0 +1,170 @@ +--- +title: git-forge +weight: 10 +--- +For all of the work one might do regarding self-sufficiency (or other personal projects), be that modifications to code, documents, images, or literally any modifiable process on a computer system, it is wise to use a version control system to keep track. + +Version contol systems, like `git`, or `fossil`, allow for the set-up of trackers and managers that are able to present a history of changes, as they are logged. + +This means that after a modification is made, it can be "commited" to the version control system, and stored. Effectively, you commit to the change. + +Although it is relatively simple to set up a `git` server for self-hosting (via [`cgit`](https://git.zx2c4.com/cgit/about/) perhaps), on its own it lacks an intuitive, easy to use way to interact with, apart from a command line interface. For this reason I personally use a [`Forgejo`](https://forgejo.org) instance, which is the same software running in [`Codeberg`](https://codeberg.org) + +## specs +`Forgejo` is extremely lightweight, and on it barely registers any resource usage. As a nix service, it consumes around 139M of RAM on my system. + +## installation + +Create a `forgejo` folder and a `default.nix` file inside it, at the place where you have the rest of your nixos configuration +```sh +$ mkdir forgejo && touch forgejo/default.nix +``` +(or use the file explorer of your choice) + +### nix declaration + +Open `forgejo/default.nix` in any text editor, and copy the following + +```nix +{ + services = { + forgejo = { + enable = true; + + dump.enable = true; + + useWizard = true; + + settings = { + DEFAULT = { + APP_NAME = "<A-COOL-INSTANCE-NAME>"; # Like "yourname's Forge" + RUN_MODE = "prod"; + APP_SLOGAN = "<SOMETHING-COOL>"; # Try "Fuck Microsoft" + RUN_USER = "forgejo"; + }; + + server = { + HTTP_ADDR = "127.0.0.1"; + HTTP_PORT = 3040; + DOMAIN = "forge.<YOUR-DOMAIN>"; + }; + + service = { + DISABLE_REGISTRATION = false; + DEFAULT_KEEP_EMAIL_PRIVATE = true; + }; + + lfs = { + enable = true; + }; + }; + }; + + nginx = { + virtualHosts."code.<YOUR-DOMAIN>" = { + enableACME = true; + forceSSL = true; + + locations."/" = { + proxyPass = "http://127.0.0.1:${config.services.forgejo.settings.server.HTTP_PORT}"; + proxyWebsockets = true; + }; + }; + }; + }; +} +``` + +Then to enable it, just include it in the server config file: +```nix + imports = [ + # ... other services + ./forgejo + # ... other services + ]; +``` +and you're done. + +Let's break the config file down. + +### explanation + +1) First of all we declare the `forgejo` service as enabled. +2) `dump.enable` enables backups, to be performed daily at 04:31 (4:31AM), and stored at `/var/lib/forgejo/dump` +3) `useWizard` enables the `Initial Configuration` page on first launch. It allows for some non-nixo-style configuration, just in case. +4) The `settings` define the configuration of forgejo itself: + 1) `DEFAULT` are the base options, such as the name, slogan, and type (production or development) of the instance + 2) `server` are server configuration options, which are options that will be written in the `app.ini` (the forgejo config file at run-time), under the [service] tag. You can find all of them [here](https://forgejo.org/docs/latest/admin/config-cheat-sheet/#server-server) + - We set the DOMAIN to be `forge.<YOUR-DOMAIN>` so that it apperas on `git clone` commands, + - We set the HTTP_PORT to `3010` because it's a non-standard port (the default of `3000` might clash with other services) + - We set the HTTP_ADDR to `127.0.0.1` so that the service is not accessible to anyone outside of the machine, *except* via reverse proxy through [`nginx`](/notes/self-sufficiency/web-server) + 3) `service` deals with some of the more middleware things; here we have it set to allow registrations, so that we might make our own admin account. After that is done, it should be + `DISABLE_REGISTRATION = false;` + 4) We enable git LFS (Large File Storage) just in case. + +5) Finally, we declare an [`nginx`](/notes/self-sufficiency/web-server) virtual host to set up a reverse proxy to point `forge.<YOUR-DOMAIN>` to HTTP_PORT 3040, so that you can access `forgejo` via the web. +{{% hint warning %}} +If you change the `HTTP_PORT`, remember to change it also in the `nginx` block. +{{% /hint %}} +{{% hint info %}} +In general the `settings` block works as follows: +Each of `name = {}` that starts a block within settings declares the equivalent `[name]` block in the non-default `app.ini`. Then, in that, it adds the items you define in the config. +For example, assume we have this: + +```nixos +{ + services = { + forgejo ={ + settings = { + server = { + HTTP_PORT = 3000; + }; + }; + }; + }; +} +``` +this then translates inside of the `app.ini` file to +```ini +[server] +HTTP_PORT = 3000 +``` +once the setup is set up. +{{% /hint %}} + +{{% hint info %}} +More information can be found at the [wiki](https://wiki.nixos.org/wiki/forgejo), but it can be opaque. +More options can be found [here](https://mynixos.com/nixpkgs/options/services.forgejo). +For example, if you plan to use this instance with more that ~4-5 people, it might be good to change the backend database from SQLite3 to PostgreSQL. +I leave the process of doing that as an exercise to the reader (Hint: It's a single line inside of `services.forgejo.database`). +{{% /hint %}} + +Make sure to update the parts inside of `<>`. +It should now appear in `localhost:3010`. If you are hosting this in a public server (like a VPS), it can be found in `http://forge.<YOUR-DOMAIN>`. + +### further setup +Once the service is up and running, go to `localhost:3010`, or `forge.<YOUR-DOMAIN>`, or whatever domain you set it to. + +You will see a setup page `Initial Configuration`. + +You must set up an administrator account. This can either be a completely seperate account to your own, or it could be your own account. + +You can also set up an email server using the [SMTP address of the email provider](/notes/self-sufficiency/email), as well as check out other small configuration stuff you can do. Configuring things like this however beats the purpose of using `NixOS`. You can always copy `app.ini` and translate it into `NixOS` later anyway though. + +{{% hint danger %}} +If you do translate `app.ini` ---> `nix`, make sure to not include any secrets (JWT/INTERNAL_TOKEN/etc). +{{% /hint %}} + +{{% hint danger %}} +If you don't want to have registration open for everyone, remember to set +`DISABLE_REGISTRATION = false;` +{{% /hint %}} + +## backups +### code backups +In general it is a good idea to have your code in multiple repositories. This allows you to not worry about your server going down, your code getting deleted, etc. + +I use [`codeberg`](https://codeberg.org) as a backup mirror for my personal work, and [`github`](https://github.com) for my work at [αpothēke](https://apotheke.earth). Although I don't like github, it is the best place for others to discover and contribute. + +### service backups +Because we have `service.forgejo.dump.enabled = true;`, we can simply copy `/var/lib/forgejo/dump` to another computer. If you want to keep any updates and configurtions after running, and made outside of nix, you can simply make a copy of the entire `/var/lib/forgejo` folder at regular intervals. |