docs: add README.md

docs/README.md

@@ -0,0 +1,54 @@
+# tuxcord.nix
+
+Declarative NixOS system configurations for [tuxcord](https://tuxcord.net/) server infrastructure.
+
+You should have basic nix knowledge before diving into any details of this configuration as nix knowledge will be assumed arbitrarily.
+
+# Documentation
+
+This README serves as the documentation entry point of the repository, any other specific aspects like users, structure, filesystem, security, services, etc, should be documented in markdown under this same `docs/` directory.
+
+Mind that documentation takes work and this can be outdated or not completely accurate, remember that nothing will always be as accurate as the configuration code itself.
+
+# Repository
+
+Active work is done in the `staging` branch, which get periodically merged into `main` branch. `main` is guaranteed to not break commit history unless explicitly required, `staging` is relaxed in this regard and can rewrite commit history if we deem it appropriate.
+
+# Hosts
+
+There's currently a single tuxcord shared server, but we've already adopted a host naming convention in case this ever scales.
+
+That is, hostnames are `tuxcord-<region>`, where `<region>` is the lowercase two-letter national code of the geographical location. We doubt there will ever be more than a server per country, so further disambiguation is not specified.
+
+Host specific configuration can be found at `nixos/hosts/tuxcord-XX`, this is useful for host specific hardware, firmware, storage layout, etc.
+
+# Development
+
+To get an environment with the basic tooling there's a nix development shell provided, just run:
+
+``` sh
+nix develop
+```
+
+To test the environment you can use nix utilities to virtualize a NixOS system configuration:
+
+```sh
+nix run '.#nixosConfigurations.<system>.config.system.build.vm'
+```
+
+Where `<system>` is the name of a host to test, for example `tuxcord-ca`.
+
+Mind that this will create a `qcow2` image file in the project directory. Nix will automatically manage changes to the configuration and update the image file accordingly while keeping part of its mutable state (e.g. root bash history).
+
+> [!WARNING]
+> Not all changes will be updated properly, mind that changes to user passwords or changes in the filesystem layout will require the image file to be deleted so that nix can recreate it from scratch.
+
+# Contributions
+
+For any contribution you'd like to make, whether it's a discussion, changes, or any other issue, there's no official channel nor does this git server allow arbitrary user registration. But we recommend reaching out to us through email (`javalsai@proton.me`/`javalsai@tuxcord.net`, `error@tuxcord.net`, or both).
+
+# License
+
+All contents under this repository are licensed under the GNU Lesser General Public License **only** (`LGPL-3.0-only`).
+
+You are free to use work based on this configuration for your own systems and redistribute modifications as long as you uphold the license terms.