docs: update with current information

garuda-linux · Aug 23, 2024 · 313a488 · 313a488
1 parent 6ebb71b
commit 313a488
Show file tree

Hide file tree

Showing 24 changed files with 817 additions and 104 deletions.
diff --git a/docs/src/404.md b/docs/src/404.md
@@ -1,5 +1,5 @@
 # Be aware of dragons!
 
-Here is nothing to be found yet. You may want to return to [home](https://docs.garudalinux.net)?
+There is nothing to be found yet. You may want to return to [home](https://docs.garudalinux.net)?
 
 ![Snowflake](https://raw.githubusercontent.com/NixOS/nixos-artwork/e7e665687ff9d80550e26948405511bc70b5c6de/logo/nix-snowflake.svg)
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -15,17 +15,17 @@
 # Hosts
 
 - [immortalis](./hosts/immortalis.md)
-  - [chaotic-kde](./nixos-containers/chaotic-kde.md)
-  - [docker-proxied](./nixos-containers/docker-proxied.md)
   - [docker](./nixos-containers/docker.md)
+  - [docker-proxied](./nixos-containers/docker-proxied.md)
   - [forum](./nixos-containers/forum.md)
   - [github-runner](./nixos-containers/github-runner.md)
   - [lemmy](./nixos-containers/lemmy.md)
   - [mastodon](./nixos-containers/mastodon.md)
+  - [mongodb](./nixos-containers/mongodb.md)
   - [postgres](./nixos-containers/postgres.md)
-  - [repo](./nixos-containers/repo.md)
   - [temeraire](./nixos-containers/temeraire.md)
   - [web-front](./nixos-containers/web-front.md)
+- [garuda-build](./hosts/garuda-build.md)
 - [garuda-mail](./hosts/garuda-mail.md)
 
 # Repository infrastructure
@@ -35,6 +35,7 @@
 
 # Services
 
+- [Chaotic 4.0](./services/chaotic-4.0.md)
 - [Discourse](./services/discourse.md)
 - [Documentation](./websites/documentation.md)
 - [Tailscale](./services/tailscale.md)

diff --git a/docs/src/common.md b/docs/src/common.md
@@ -12,7 +12,8 @@ sudo ./launcher rebuild app
 
 ### Building ISO files
 
-To build Garuda ISO, one needs to connect to the `iso-runner` container and execute the `buildiso` command, which opens a shell containing the needed environment:
+To build Garuda ISO, one needs to connect to the `iso-runner` container and execute the `buildiso` command, which opens
+a shell containing the needed environment:
 
 ```sh
 ssh -p 227 $user@116.202.208.112 # if one ran nix develop before, this can be skipped
@@ -21,9 +22,12 @@ buildiso -i # updates the iso-profiles repo
 buildiso -p dr460nized
 ```
 
-Further information on available commands can be found in the [garuda-tools](https://gitlab.com/garuda-linux/tools/garuda-tools) repository.
-After the build process is finished, builds can be found on [iso.builds.garudalinux.org](https://iso.builds.garudalinux.org/iso/garuda/).
-No automatic pushing to Sourceforge and Cloudflare R2 happens by default, see below for more information on how to achieve this.
+Further information on available commands can be found in
+the [garuda-tools](https://gitlab.com/garuda-linux/tools/garuda-tools) repository.
+After the build process is finished, builds can be found
+on [iso.builds.garudalinux.org](https://iso.builds.garudalinux.org/iso/garuda/).
+No automatic pushing to Sourceforge and Cloudflare R2 happens by default, see below for more information on how to
+achieve this.
 
 ### Deploying a new ISO release
 
@@ -40,7 +44,8 @@ deployiso -FSRd # oneliner for the above-given commands
 
 ### Updating the system
 
-One needs to have the [infra-nix](https://gitlab.com/garuda-linux/infra-nix) repo cloned locally. Then proceed by updating the `flake.lock` file, pushing it to the server & building the configurations:
+One needs to have the [infra-nix](https://gitlab.com/garuda-linux/infra-nix) repo cloned locally. Then proceed by
+updating the `flake.lock` file, pushing it to the server & building the configurations:
 
 ```sh
 nix flake update
@@ -59,11 +64,14 @@ ssh -p 666 [email protected] # Manually, exemplary on immortalis
 sudo nixos-rebuild switch
 ```
 
-Keep in mind that this will restart every service whose files changed since the last system update. On our Hetzner server, this includes a restart of every declarative `nixos-container` if needed, causing a small downtime.
+Keep in mind that this will restart every service whose files changed since the last system update. On our Hetzner
+server, this includes a restart of every declarative `nixos-container` if needed, causing a small downtime.
 
 ### Changing system configurations
 
-Most system configurations are contained in individual Nix files in the `nix` directory of this repo. This means changing anything must not be done manually but by editing the corresponding file and pushing/applying the configuration afterward.
+Most system configurations are contained in individual Nix files in the `nix` directory of this repo. This means
+changing anything must not be done manually but by editing the corresponding file and pushing/applying the configuration
+afterward.
 
 ```sh
 ansible-playbook garuda.yml -l $servername # Eg. immortalis for the Hetzner host
@@ -85,22 +93,30 @@ sudo nixos-rebuild switch
 
 Adding users needs to be done in `users.nix`:
 
-- Add a new user [here](https://gitlab.com/garuda-linux/infra-nix/-/blob/main/nixos/modules/users.nix?ref_type=heads#L14)
-- Add the SSH public key to [flake inputs](https://gitlab.com/garuda-linux/infra-nix/-/blob/main/flake.nix?ref_type=heads#L43)
-- Add the specialArgs `keys.user` as seen [here](https://gitlab.com/garuda-linux/infra-nix/-/blob/main/nixos/flake-module.nix?ref_type=heads#L38)
+- Add a new
+  user [here](https://gitlab.com/garuda-linux/infra-nix/-/blob/main/nixos/modules/users.nix?ref_type=heads#L14)
+- Add the SSH public key
+  to [flake inputs](https://gitlab.com/garuda-linux/infra-nix/-/blob/main/flake.nix?ref_type=heads#L43)
+- Add the specialArgs `keys.user` as
+  seen [here](https://gitlab.com/garuda-linux/infra-nix/-/blob/main/nixos/flake-module.nix?ref_type=heads#L38)
 - Deploy & apply the configuration
 
 ### Changing Docker configurations
 
-If configurations of services running in Docker containers need to be altered, one needs to edit the corresponding `docker-compose.yml` (`./nix/docker-compose/$name`) file or `.env` file in the `secrets` directory (see the secrets section for details on that topic).
+If configurations of services running in Docker containers need to be altered, one needs to edit the
+corresponding `docker-compose.yml` (`./nix/docker-compose/$name`) file or `.env` file in the `secrets` directory (see
+the secrets section for details on that topic).
 The deployment is done the same way as with normal system configuration.
 
 ### Updating Docker containers
 
-Docker containers sometimes use the `latest` tag in case no current tag is available or in the case of services like Piped and Searx, where it is often crucial to have the latest build to bypass Google's restrictions.
+Docker containers sometimes use the `latest` tag in case no current tag is available or in the case of services like
+Piped and Searx, where it is often crucial to have the latest build to bypass Google's restrictions.
 Containers using the `latest` tag are automatically updated via [watchtower](https://containrrr.dev/watchtower/) daily.
-The remaining ones can be updated by changing their version in the corresponding `docker-compose.yml` and then running `deploy` & `apply`.
-If containers are to be updated manually, this can be achieved by connecting to the host, running `nixos-container root-login $containername`, and executing:
+The remaining ones can be updated by changing their version in the corresponding `docker-compose.yml` and then
+running `deploy` & `apply`.
+If containers are to be updated manually, this can be achieved by connecting to the host,
+running `nixos-container root-login $containername`, and executing:
 
 ```sh
 cd /var/garuda/docker-compose-runner/$name/ # replace $name with the actual docker-compose.yml or autocomplete via tab
@@ -112,9 +128,13 @@ The updated containers will be pulled and automatically recreated using the new
 
 ### Rotating IPv6
 
-Sometimes it is needed to rotate the available IPv6 addresses to solve the current ones being rate-limited for outgoing requests of Piped, Searx, etc.
-This can be achieved by editing the hosts Nix file `immortalis.nix`, replacing the existing values of the `networking.interfaces."eth0".ipv6.addresses` keys seen [here](https://gitlab.com/garuda-linux/infra-nix/-/blob/main/nixos/hosts/immortalis.nix?ref_type=heads#L30).
-Then, proceed doing the same with the [squid configuration](https://gitlab.com/garuda-linux/infra-nix/-/blob/main/nixos/hosts/immortalis.nix?ref_type=heads#L219).
+Sometimes it is needed to rotate the available IPv6 addresses to solve the current ones being rate-limited for outgoing
+requests of Piped, Searx, etc.
+This can be achieved by editing the hosts Nix file `immortalis.nix`, replacing the existing values of
+the `networking.interfaces."eth0".ipv6.addresses` keys
+seen [here](https://gitlab.com/garuda-linux/infra-nix/-/blob/main/nixos/hosts/immortalis.nix?ref_type=heads#L30).
+Then, proceed doing the same with
+the [squid configuration](https://gitlab.com/garuda-linux/infra-nix/-/blob/main/nixos/hosts/immortalis.nix?ref_type=heads#L219).
 IPv6 addresses need to be generated from our available /64 subnet space and can't be chosen completely random.
 To ease the process, a command called `ipv6-generator` is available in this git repos' devshell.
 
@@ -126,28 +146,29 @@ To check whether backups to Hetzner are still working as expected, connect to th
 systemctl status borgbackup-job-backupToHetzner
 ```
 
-This should yield a successful unit state. The only exception is having an exit code != `0` due to files having changed during the run.
+This should yield a successful unit state. The only exception is having an exit code != `0` due to files having changed
+during the run.
 
 ### Updating Chaotic-AUR toolbox
 
-This needs to be done by updating the flake input (git repo URL of the website) [src-chaotic-toolbox](https://gitlab.com/garuda-linux/infra-nix/-/blob/main/nix/flake.nix?ref_type=heads#L44):
+This needs to be done by updating the flake input (git repo URL of the
+website) [src-chaotic-toolbox](https://gitlab.com/garuda-linux/infra-nix/-/blob/main/nix/flake.nix?ref_type=heads#L44):
 
 ```sh
 cd nix
 nix flake lock --update-input src-chaotic-toolbox # toolbox
 ```
 
-After that deploy as usual by running `deploy` and `apply`. The commit and corresponding hash will be updated and NixOS will use it to build the toolbox using the new revision automatically.
+After that deploy as usual by running `deploy` and `apply`. The commit and corresponding hash will be updated and NixOS
+will use it to build the toolbox using the new revision automatically.
 
-### Updating the Garuda startpage content
+### Creating new Docker Compose configs
 
-Our startpage consists of a simple [homer](https://github.com/bastienwirtz/homer) deployment.
-Its configuration is stored in the [startpage](https://gitlab.com/garuda-linux/website/startpage) repo, which gets cloned to the docker-compose.yml's directory to serve the files.
-In order, updating is currently done manually after pushing the changes to the repo (might automate this soon via systemd timer!):
-
-```sh
-ssh -p 225 $user@116.202.208.112
-cd /var/garuda/docker-compose-runner/all-in-one/startpage
-git pull
-sudo docker restart homer
-```
+In case a new service needs to be added to the Docker Compose runner,
+one can either write the needed Nix expressions directly,
+or use [compose2nix](https://github.com/aksiksi/compose2nix)
+to transform an existing `docker-compose.yml` to valid Nix expressions.
+Using native Nix expressions has the advantage of being more flexible and easier to maintain,
+as well as taking advantage of Systemd service management, e.g., by restarting crashed containers.
+This was not working reliably with our `docker-compose-runner` module, which simply started
+existing `docker-compose.yml` files.
diff --git a/docs/src/general.md b/docs/src/general.md
@@ -4,29 +4,38 @@ A general overview of the folder structure can be found below:
 
 ```shell
 ├── assets
-├── docker-compose
-│   ├── all-in-one
-│   ├── github-runner
-│   └── proxied
 ├── docs
-│   ├── hosts
-│   └── theme
+│  ├── src
+│  │  ├── hosts
+│  │  ├── nixos-containers
+│  │  ├── repositories
+│  │  ├── services
+│  │  ├── users
+│  │  └── websites
+│  └── theme
+│     ├── css
+│     └── fonts
 ├── home-manager
 ├── host_vars
-│   ├── garuda-build
-│   ├── garuda-mail
-│   └── immortalis
+│  ├── garuda-build
+│  ├── garuda-mail
+│  └── immortalis
 ├── nixos
-│   ├── hosts
-│   │   ├── garuda-build
-│   │   ├── garuda-mail
-│   │   └── immortalis
-│   ├── modules
-│   │   └── static
-│   └── services
-│       ├── chaotic
-│       ├── docker-compose-runner
-│       └── monitoring
+│  ├── hosts
+│  │  ├── chaotic-v4
+│  │  ├── docker
+│  │  │  └── configs
+│  │  ├── docker-proxied
+│  │  ├── garuda-build
+│  │  ├── garuda-mail
+│  │  ├── github-runner
+│  │  └── immortalis
+│  ├── modules
+│  │  └── static
+│  └── services
+│     ├── chaotic
+│     ├── docker-compose-runner
+│     └── monitoring
 ├── playbooks
 ├── scripts
 └── secrets

diff --git a/docs/src/hosts/docker-proxied.md b/docs/src/hosts/docker-proxied.md
@@ -0,0 +1 @@
+# docker-proxied
diff --git a/docs/src/hosts/garuda-build.md b/docs/src/hosts/garuda-build.md
@@ -0,0 +1,20 @@
+## garuda-build (Legacy Fosshost VPS)
+
+### General
+
+This server is a legacy, still up Fosshost VPS. Fosshost itself ceased to be quite a while ago,
+but this server is still up for some reason.
+Since we can't be sure how long it will stay up, we don't want to put anything important on it.
+Therefore, its sole purpose is running a disposable build environment for the Chaotic-AUR infra 4.0
+
+### Nix expression
+
+```nix
+{{#include ../../../nixos/hosts/garuda-build.nix}}
+```
+
+### Docker containers
+
+```nix
+{{#include ../../../nixos/hosts/garuda-build/docker-compose.nix}}
+```
diff --git a/docs/src/hosts/garuda-mail.md b/docs/src/hosts/garuda-mail.md
@@ -33,7 +33,7 @@ It features a few plugins to enhance the general user experience.
 - custom_from - allows customizing from address
 - managesieve - allows managing Sieve rules, which automatically sort incoming mails based on rules
 - newmail_notifier - new mail notifier for desktops
-- persistent_login - alows storing a persistent login cookie for no more login prompts
+- persistent_login - allows storing a persistent login cookie for no more login prompts
 - thunderbird_labels - shows Thunderbird labels
 - zipdownload - allows downloading all attachments at once
 
@@ -44,14 +44,14 @@ Backups are happening daily via Borg. A Hetzner storage box is used to store mul
 ### Creating a new user
 
 A new user can be created be adding a new `loginAccounts` value and supplying the password via `secrets`.
-We make use of `hashedPasswordFile`, therefore new hashes can be generated by running `nix-shell -p mkpasswd --run 'mkpasswd -sm bcrypt'`. Add it to the `secrets`, then execute `deploy` and `apply`.
+We make use of `hashedPasswordFile`, therefore, new hashes can be generated by running `nix-shell -p mkpasswd --run 'mkpasswd -sm bcrypt'`. Add it to the `secrets`, then execute `deploy` and `apply`.
 Don't forget to commit both changes.
 
 ### Issues and their solution
 
 #### Local DNS resolver failing to start
 
-Simple NixOS mailserver runs a local DNS server to prevent the log filling up with junk ([source](https://mailserver.readthedocs.io/en/latest/options.html#cmdoption-arg-mailserver.localDnsResolver)).
+Simple NixOS mail server runs a local DNS server to prevent the log filling up with junk ([source](https://mailserver.readthedocs.io/en/latest/options.html#cmdoption-arg-mailserver.localDnsResolver)).
 There can be cases of the persisted files need to be deleted in order for the service to recover from dumping core.
 See [this issue](https://gitlab.nic.cz/knot/knot-resolver/-/issues/627) for reference.
 

diff --git a/docs/src/hosts/immortalis.md b/docs/src/hosts/immortalis.md
@@ -11,27 +11,27 @@ The current line-up looks as follows:
 ```sh
 nico@immortalis ~> machinectl
 MACHINE        CLASS     SERVICE        OS    VERSION ADDRESSES
-chaotic-kde    container systemd-nspawn nixos 24.05   10.0.5.90
-chaotic-v4     container systemd-nspawn nixos 24.05   10.0.5.140
-docker         container systemd-nspawn nixos 24.05   10.0.5.100
-docker-proxied container systemd-nspawn nixos 24.05   10.0.5.110
-forum          container systemd-nspawn nixos 24.05   10.0.5.70
-github-runner  container systemd-nspawn nixos 24.05   10.0.5.130
-iso-runner     container systemd-nspawn nixos 24.05   10.0.5.40
-lemmy          container systemd-nspawn nixos 24.05   10.0.5.120
-mastodon       container systemd-nspawn nixos 24.05   10.0.5.80
-postgres       container systemd-nspawn nixos 24.05   10.0.5.50
-temeraire      container systemd-nspawn nixos 24.05   10.0.5.20
-web-front      container systemd-nspawn nixos 24.05   10.0.5.10
+chaotic-v4     container systemd-nspawn nixos 24.11   10.0.5.140…
+docker         container systemd-nspawn nixos 24.11   10.0.5.100…
+docker-proxied container systemd-nspawn nixos 24.11   10.0.5.110…
+forum          container systemd-nspawn nixos 24.11   10.0.5.70…
+github-runner  container systemd-nspawn nixos 24.11   10.0.5.130…
+iso-runner     container systemd-nspawn nixos 24.11   10.0.5.40…
+lemmy          container systemd-nspawn nixos 24.11   10.0.5.120…
+mastodon       container systemd-nspawn nixos 24.11   10.0.5.80…
+mongodb        container systemd-nspawn nixos 24.11   10.0.5.60…
+postgres       container systemd-nspawn nixos 24.11   10.0.5.50…
+temeraire      container systemd-nspawn nixos 24.11   10.0.5.20…
+web-front      container systemd-nspawn nixos 24.11   10.0.5.10…
 ```
 
 We are seeing:
 
 - 1 ISO builder (`iso-runner`)
 - 1 reverse proxy serving all the websites and services (`web-front`)
 - 2 Docker dedicated nspawn containers (`docker` & `docker-proxied`)
-- 4 Chaotic-AUR builders (`chaotic-kde`, `chaotic-v4`, `github-runner` & `temeraire`)
-- 5 app dedicated containers (`forum`, `lemmy`, `mastodon` & `postgres`)
+- 3 Chaotic-AUR builders ( `chaotic-v4`, `github-runner` & `temeraire`)
+- 6 app dedicated containers (`forum`, `lemmy`, `mastodon`, `mongodb` & `postgres`)
 
 ### Connecting to the server
 
@@ -40,7 +40,6 @@ After connecting to the host via `ssh -p 666 [email protected]`, containers
 - 22: `temeraire` (needs to be 22 to allow pushing packages to the main Chaotic-AUR node via rsync)
 - 224: `forum`
 - 225: `docker`
-- 226: `chaotic-kde`
 - 227: `iso-runner`
 - 228: `web-front`
 - 229: `postgres` (access the database in `127.0.0.1` via `ssh -p 229 [email protected] -L 5432:127.0.0.1:5432`)
@@ -64,8 +63,6 @@ chaotic rm $package # remove the package from the repository
 Further information may be obtained by clicking `chaotic` seen above. The corresponding builders are:
 
 - `[chaotic-aur]`: `temeraire`
-- `[garuda]`: `repo`
-- `[chaotic-kde]`: `chaotic-kde`
 
 ### Squid proxy