From 4a3ae4248600dce106804b8e9a792cbe1e2df41b Mon Sep 17 00:00:00 2001 From: aethrvmn Date: Sat, 20 Sep 2025 23:13:27 +0200 Subject: renamed for better url --- content/theses/self-sufficiency/forge.md | 183 +++++++++++++++++++++++++++ content/theses/self-sufficiency/git-forge.md | 183 --------------------------- 2 files changed, 183 insertions(+), 183 deletions(-) create mode 100644 content/theses/self-sufficiency/forge.md delete mode 100644 content/theses/self-sufficiency/git-forge.md (limited to 'content/theses') diff --git a/content/theses/self-sufficiency/forge.md b/content/theses/self-sufficiency/forge.md new file mode 100644 index 0000000..23672c3 --- /dev/null +++ b/content/theses/self-sufficiency/forge.md @@ -0,0 +1,183 @@ +--- +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 = ""; # Like "yourname's Forge" + RUN_MODE = "prod"; + APP_SLOGAN = ""; # Try "Fuck Microsoft" + RUN_USER = "forgejo"; + }; + + server = { + HTTP_PORT = 3040; + DOMAIN = "forge."; + ROOT_URL = "http://forge./"; + SSH_DOMAIN = "forge."; + SSH_PORT = 22; + DISABLE_SSH = false; + }; + + database = { + DB_TYPE = "sqlite3"; + }; + + service = { + DISABLE_REGISTRATION = false; + DEFAULT_KEEP_EMAIL_PRIVATE = true; + REQUIRE_SIGNIN_VIEW = false; + REGISTER_EMAIL_CONFIRM = false; + ENABLE_NOTIFY_MAIL = false; + ALLOW_ONLY_EXTERNAL_REGISTRATION = false; + ENABLE_CAPTCHA = false; + DEFAULT_ALLOW_CREATE_ORGANIZATION = true; + DEFAULT_ENABLE_TIMETRACKING = true; + }; + + lfs = { + enable = true; + }; + }; + }; + + nginx = { + virtualHosts."forge." = { + enableACME = true; + forceSSL = true; + + locations."/" = { + proxyPass = "http://127.0.0.1:3040"; + 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.` so that it apperas on `git clone` commands, + - We set the HTTP_PORT to `3040` 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 = true;` so so that only the admin (you) can create new users. + 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.` 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.`. + +### further setup +Once the service is up and running, go to `localhost:3010`, or `forge.`, 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. diff --git a/content/theses/self-sufficiency/git-forge.md b/content/theses/self-sufficiency/git-forge.md deleted file mode 100644 index 23672c3..0000000 --- a/content/theses/self-sufficiency/git-forge.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -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 = ""; # Like "yourname's Forge" - RUN_MODE = "prod"; - APP_SLOGAN = ""; # Try "Fuck Microsoft" - RUN_USER = "forgejo"; - }; - - server = { - HTTP_PORT = 3040; - DOMAIN = "forge."; - ROOT_URL = "http://forge./"; - SSH_DOMAIN = "forge."; - SSH_PORT = 22; - DISABLE_SSH = false; - }; - - database = { - DB_TYPE = "sqlite3"; - }; - - service = { - DISABLE_REGISTRATION = false; - DEFAULT_KEEP_EMAIL_PRIVATE = true; - REQUIRE_SIGNIN_VIEW = false; - REGISTER_EMAIL_CONFIRM = false; - ENABLE_NOTIFY_MAIL = false; - ALLOW_ONLY_EXTERNAL_REGISTRATION = false; - ENABLE_CAPTCHA = false; - DEFAULT_ALLOW_CREATE_ORGANIZATION = true; - DEFAULT_ENABLE_TIMETRACKING = true; - }; - - lfs = { - enable = true; - }; - }; - }; - - nginx = { - virtualHosts."forge." = { - enableACME = true; - forceSSL = true; - - locations."/" = { - proxyPass = "http://127.0.0.1:3040"; - 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.` so that it apperas on `git clone` commands, - - We set the HTTP_PORT to `3040` 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 = true;` so so that only the admin (you) can create new users. - 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.` 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.`. - -### further setup -Once the service is up and running, go to `localhost:3010`, or `forge.`, 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. -- cgit v1.2.3