From 9bf187766a94b3e0f6a9959583a590c6c7479cf0 Mon Sep 17 00:00:00 2001 From: ibizaman Date: Sat, 14 Oct 2023 15:07:38 -0700 Subject: [PATCH] add example usage --- README.md | 213 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 208 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3c8e2e6..f675438 100644 --- a/README.md +++ b/README.md @@ -51,9 +51,211 @@ services. Also, the design will be extendable to allow users to add services not - [ ] Slow log monitoring. - [ ] Export metrics to Prometheus. +## Repo layout + +The top-level `flake.nix` just outputs a nixos module that gathers all other modules from `modules/`. + +Some provided modules are low-level and some are high-level that re-use those low-level ones. For +example, the nextcloud module re-uses the backup and nginx ones. + +## How to Use + +You want to use this repo as a flake input to your own repo. The `inputs` field of your `flake.nix` +file in your repo should look like so: + +```nix +inputs = { + nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; + sops-nix.url = "github:Mic92/sops-nix"; + + selfhostblocks.url = "github:ibizaman/selfhostblocks"; + selfhostblocks.inputs.nixpkgs.follows = "nixpkgs"; + selfhostblocks.inputs.sops-nix.follows = "sops-nix"; +}; +``` + +`sops-nix` is used to setup passwords and secrets. Currently `selfhostblocks` has a strong +dependency on it but I'm working on removing that so you could use any secret provider. + +Also, if you ever want to hack on `selfhostblocks` yourself, you can clone it and then update the +`selfhostblocks` url to point to the absolute path of where you cloned it: + +```nix +selfhostblocks.url = "/home/me/projects/selfhostblocks"; +``` + +Now, how you actually deploy using selfhostblocks depends on what system you chose. If you use colmena, this is what your `outputs` field should look like: + +```nix +outputs = inputs@{ self, nixpkgs, ... }: { + colmena = { + meta = { + nixpkgs = import inputs.nixpkgs { + system = "x86_64-linux"; + }; + specialArgs = inputs; + }; + + myserver = import ./machines/myserver.nix; + }; +} +``` + +### Deploy a Nextcloud Instance + +Now, what goes inside this `./machines/myserver.nix` file? Let's say you want to deploy Nextcloud, +you would use the [`nextcloud.nix`](./modules/nextcloud.nix) module from this repo as reference and have something like the following. + +First, some common configuration: + +```nix +imports = [ + selfhostblocks.nixosModules.default + sops-nix.nixosModules.default +] + +shb.ssl = { + enable = true; + domain = "example.com"; + adminEmail = "me@example.com"; + sopsFile = ./secrets/linode.yaml; + dnsProvider = "linode"; +}; +``` + +Then, the configuration for Nextcloud which sets up: +- the nginx reverse proxy to listen on requests for the `nextcloud.example.com` domain, +- backup of the config folder and the data folder, +- an onlyoffice instance listening at `oo.example.com` that only listens on the local + nextwork; you still need to setup the onlyoffice plugin in Nextcloud, +- and all the required databases and secrets. + +```nix +shb.nextcloud = { + enable = true; + domain = "example.com"; + subdomain = "nextcloud"; + sopsFile = ./secrets/nextcloud.yaml; + localNetworkIPRange = "192.168.1.0/24"; + debug = false; +}; + +services.nextcloud = { + datadir = "/srv/nextcloud"; + poolSettings = { + "pm" = "dynamic"; + "pm.max_children" = 120; + "pm.start_servers" = 12; + "pm.min_spare_servers" = 6; + "pm.max_spare_servers" = 18; + }; +}; + +shb.backup.instances.nextcloud = { + backend = "restic"; + + keySopsFile = ./secrets/backup.yaml; + + repositories = [ + "/srv/backup/restic/nextcloud" + "s3:s3.us-west-000.backblazeb2.com/myserver-backup/nextcloud" + ]; + + retention = { + keep_within = "1d"; + keep_hourly = 24; + keep_daily = 7; + keep_weekly = 4; + keep_monthly = 6; + }; + + consistency = { + repository = "2 weeks"; + archives = "1 month"; + }; + + environmentFile = true; # Needed for s3 +}; +``` + +### Deploy an hledger Instance with LDAP and SSO support + +First, use the same common configuration as above. Then add the SSO and LDAP providers: + +```nix +shb.ldap = { + enable = true; + domain = "example.com"; + subdomain = "ldap"; + dcdomain = "dc=example,dc=com"; + sopsFile = ./secrets/ldap.yaml; + localNetworkIPRange = "192.168.1.0/24"; +}; +shb.backup.instances.lldap = # Same as for the Nextcloud one above + +shb.authelia = { + enable = true; + domain = "example.com"; + subdomain = "authelia"; + sopsFile = ./secrets/authelia.yaml; + + ldapEndpoint = "ldap://127.0.0.1:3890"; + dcdomain = config.shb.ldap.dcdomain; + + smtpHost = "smtp.mailgun.org"; + smtpPort = 587; + smtpUsername = "postmaster@mg.example.com"; +}; +``` + +Finally, the hledger specific part which sets up: +- the nginx reverse proxy to listen on requests for the `hledger.example.com` domain, +- backup of everything, +- only allow users of the hledger_user to be able to login, +- all the required databases and secrets + +```nix +shb.hledger = { + enable = true; + subdomain = "hledger"; + domain = "example.com"; + oidcEndpoint = "https://authelia.example.com"; + localNetworkIPRange = "192.168.1.0/24"; +}; +shb.backup.instances.hledger = # Same as the examples above +``` + +### Deploy a Jellyfin instance with LDAP and SSO support + +First, use the same common configuration as for the Nextcloud example and the SSO and LDAP +configuration than for the hledger example. Then, the jellyfin specific part which sets up : + +- the nginx reverse proxy to listen on requests for the `jellyfin.example.com` domain, +- backup of everything, +- only allow users of the `jellyfin_user` or `jellyfin_admin` ldap group to be able to login, +- all the required databases and secrets + +```nix +shb.jellyfin = { + enable = true; + domain = "example.com"; + subdomain = "jellyfin"; + + sopsFile = ./secrets/jellyfin.yaml; + ldapHost = "127.0.0.1"; + ldapPort = 3890; + dcdomain = config.shb.ldap.dcdomain; + oidcEndpoint = "https://authelia.example.com"; + oidcClientID = "jellyfin"; + oidcAdminUserGroup = "jellyfin_admin"; + oidcUserGroup = "jellyfin_user"; +}; +shb.backup.instances.jellyfin = # Same as the examples above +``` + ## Tips -### Deploy +### Deploy using colmena ```bash $ nix run nixpkgs#colmena -- apply @@ -61,10 +263,8 @@ $ nix run nixpkgs#colmena -- apply ### Diff changes -```bash -$ nix run nixpkgs#colmena -- build -... -Built "/nix/store/yyw9rgn8v5jrn4657vwpg01ydq0hazgx-nixos-system-baryum-23.11pre-git" +```bash $ nix run nixpkgs#colmena -- build ... Built +"/nix/store/yyw9rgn8v5jrn4657vwpg01ydq0hazgx-nixos-system-baryum-23.11pre-git" # Make some changes @@ -88,4 +288,7 @@ nix run nixpkgs#nvd -- diff \ ## TODOs +- [ ] Add examples that sets up instance in a VM. +- [ ] Do not depend on sops. +- [ ] Add more options to avoid hardcoding stuff. - [ ] Make sure nginx gets reloaded when SSL certs gets updated.