diff --git a/demo/homeassistant/README.md b/demo/homeassistant/README.md index 9d339f2..5ccbd02 100644 --- a/demo/homeassistant/README.md +++ b/demo/homeassistant/README.md @@ -9,7 +9,7 @@ setup users in only about [15 lines](./flake.nix#L29-L45) of related code. This guide will show how to deploy this setup to a Virtual Machine, like showed [here](https://nixos.wiki/wiki/NixOS_modules#Developing_modules), in 4 commands. -## Deploy to the VM {#deploy-to-the-vm} +## Deploy to the VM {#demo-homeassistant-deploy-to-the-vm} Build the VM and start it: @@ -22,8 +22,6 @@ rm nixos.qcow2; \ This last call is blocking, so I advice adding a `&` at the end of the command otherwise you will need to run the rest of the commands in another terminal. -The nested command, the one in between the parenthesis `$(...)` is used to print the VM's public age key, whic. - With the VM started, make the secrets in `secrets.yaml` decryptable in the VM. This change will appear in `git status` but you don't need to commit this. @@ -34,6 +32,10 @@ SOPS_AGE_KEY_FILE=keys.txt \ secrets.yaml ``` +The nested command, the one in between the parenthesis `$(...)`, is used to print the VM's public +age key, which is then added to the `secrets.yaml` file in order to make the secrets decryptable by +the VM. + If you forget this step, the deploy will seem to go fine but the secrets won't be populated and neither LLDAP nor Home Assistant will start. @@ -61,7 +63,7 @@ SSH_CONFIG_FILE=ssh_config nix run nixpkgs#colmena --impure -- apply The deploy will take a few minutes the first time and subsequent deploys will take around 15 seconds. -## Access Home Assistant Through Your Browser {#access-home-assistant-through-your-browser} +## Access Home Assistant Through Your Browser {#demo-homeassistant-access-through-your-browser} Add the following entry to your `/etc/hosts` file: @@ -88,9 +90,9 @@ Create the group `homeassistant_user` and a user assigned to that group. Go to [http://ha.example.com:8080](http://ha.example.com:8080) and login with the user and password you just created above. -## In More Details {#in-more-details} +## In More Details {#demo-homeassistant-in-more-details} -### Files {#files} +### Files {#demo-homeassistant-files} - [`flake.nix`](./flake.nix): nix entry point, defines one target host for [colmena](https://colmena.cli.rs) to deploy to as well as the selfhostblock's config for @@ -114,7 +116,7 @@ user and password you just created above. hostname `example`. Usually you would store this info in your `~/.ssh/config` file but it's provided here to avoid making you do that. -### Virtual Machine {#virtual-machine} +### Virtual Machine {#demo-homeassistant-virtual-machine} _More info about the VM._ @@ -131,7 +133,7 @@ That being said, the VM uses `tmpfs` to create the writable nix store so if you space issue, you must increase the `virtualisation.vmVariantWithBootLoader.virtualisation.memorySize` setting. -### Secrets {#secrets} +### Secrets {#demo-homeassistant-secrets} _More info about the secrets._ @@ -178,7 +180,7 @@ $ nix run nixpkgs#openssl -- rand -hex 64 If you choose a password too small, ldap could refuse to start. -#### Why do we need the VM's public key {#public-key-necessity} +#### Why do we need the VM's public key {#demo-homeassistant-public-key-necessity} The [`sops.yaml`](./sops.yaml) file describes what private keys can decrypt and encrypt the [`secrets.yaml`](./secrets.yaml) file containing the application secrets. Usually, you will create and add @@ -191,7 +193,7 @@ creating the VM in the step above, a new private key and its accompanying public automatically generated under `/etc/ssh/ssh_host_ed25519_key` in the VM. We just need to get the public key and add it to the `secrets.yaml` which we did in the Deploy section. -### SSH {#ssh} +### SSH {#demo-homeassistant-ssh} The private and public ssh keys were created with: @@ -209,7 +211,7 @@ authentication, here is what you would need to do to copy over the key: nix shell nixpkgs#openssh --command ssh-copy-id -i sshkey -F ssh_config example ``` -### Deploy {#deploy} +### Deploy {#demo-homeassistant-deploy} If you get a NAR hash mismatch error like hereunder, you need to run `nix flake lock --update-input selfhostblocks`. @@ -218,7 +220,7 @@ selfhostblocks`. error: NAR hash mismatch in input ... ``` -### Update Demo {#update-demo} +### Update Demo {#demo-homeassistant-update-demo} If you update the Self Host Blocks configuration in `flake.nix` file, you can just re-deploy. diff --git a/demo/nextcloud/README.md b/demo/nextcloud/README.md index 171f8f2..a3b47a0 100644 --- a/demo/nextcloud/README.md +++ b/demo/nextcloud/README.md @@ -7,9 +7,9 @@ The [`flake.nix`](./flake.nix) file sets up a Nextcloud server in only about [15 lines](./flake.nix#L29-L45) of related code. This guide will show how to deploy this setup to a Virtual Machine, like showed -[here](https://nixos.wiki/wiki/NixOS_modules#Developing_modules), in 6 commands. +[here](https://nixos.wiki/wiki/NixOS_modules#Developing_modules), in 4 commands. -## Deploy to the VM {#deploy-to-the-vm} +## Deploy to the VM {#demo-nextcloud-deploy-to-the-vm} Build the VM and start it: @@ -22,8 +22,6 @@ rm nixos.qcow2; \ This last call is blocking, so I advice adding a `&` at the end of the command otherwise you will need to run the rest of the commands in another terminal. -The nested command, the one in between the parenthesis `$(...)` is used to print the VM's public age key, whic. - With the VM started, make the secrets in `secrets.yaml` decryptable in the VM. This change will appear in `git status` but you don't need to commit this. @@ -34,6 +32,10 @@ SOPS_AGE_KEY_FILE=keys.txt \ secrets.yaml ``` +The nested command, the one in between the parenthesis `$(...)`, is used to print the VM's public +age key, which is then added to the `secrets.yaml` file in order to make the secrets decryptable by +the VM. + If you forget this step, the deploy will seem to go fine but the secrets won't be populated and Nextcloud will not start. @@ -61,7 +63,7 @@ SSH_CONFIG_FILE=ssh_config nix run nixpkgs#colmena --impure -- apply The deploy will take a few minutes the first time and subsequent deploys will take around 15 seconds. -## Access Nextcloud Through Your Browser {#access-nextcloud-through-your-browser} +## Access Nextcloud Through Your Browser {#demo-nextcloud-access-through-your-browser} Add the following entry to your `/etc/hosts` file: @@ -86,9 +88,9 @@ Go to [http://n.example.com:8080](http://n.example.com:8080) and login with: Nextcloud doesn't like being run without SSL protection, which this demo does not setup yet, so you might see errors loading scripts. -## In More Details {#in-more-details} +## In More Details {#demo-nextcloud-in-more-details} -### Files {#files} +### Files {#demo-nextcloud-files} - [`flake.nix`](./flake.nix): nix entry point, defines one target host for [colmena](https://colmena.cli.rs) to deploy to as well as the selfhostblock's config for @@ -111,7 +113,7 @@ might see errors loading scripts. hostname `example`. Usually you would store this info in your `~/.ssh/config` file but it's provided here to avoid making you do that. -### Virtual Machine {#virtual-machine} +### Virtual Machine {#demo-nextcloud-virtual-machine} _More info about the VM._ @@ -128,7 +130,7 @@ That being said, the VM uses `tmpfs` to create the writable nix store so if you space issue, you must increase the `virtualisation.vmVariantWithBootLoader.virtualisation.memorySize` setting. -### Secrets {#secrets} +### Secrets {#demo-nextcloud-secrets} _More info about the secrets._ @@ -166,7 +168,7 @@ $ nix run nixpkgs#openssl -- rand -hex 64 If you choose a password too small, ldap could refuse to start. -#### Why do we need the VM's public key {#public-key-necessity} +#### Why do we need the VM's public key {#demo-nextcloud-public-key-necessity} The [`sops.yaml`](./sops.yaml) file describes what private keys can decrypt and encrypt the [`secrets.yaml`](./secrets.yaml) file containing the application secrets. Usually, you will create and add @@ -179,7 +181,7 @@ creating the VM in the step above, a new private key and its accompanying public automatically generated under `/etc/ssh/ssh_host_ed25519_key` in the VM. We just need to get the public key and add it to the `secrets.yaml` which we did in the Deploy section. -### SSH {#ssh} +### SSH {#demo-nextcloud-ssh} The private and public ssh keys were created with: @@ -197,7 +199,7 @@ authentication, here is what you would need to do to copy over the key: $ nix shell nixpkgs#openssh --command ssh-copy-id -i sshkey -F ssh_config example ``` -### Deploy {#deploy} +### Deploy {#demo-nextcloud-deploy} If you get a NAR hash mismatch error like hereunder, you need to run `nix flake lock --update-input selfhostblocks`. @@ -206,7 +208,7 @@ selfhostblocks`. error: NAR hash mismatch in input ... ``` -### Update Demo {#update-demo} +### Update Demo {#demo-nextcloud-update-demo} If you update the Self Host Blocks configuration in `flake.nix` file, you can just re-deploy. diff --git a/docs/default.nix b/docs/default.nix index 473209e..6f39680 100644 --- a/docs/default.nix +++ b/docs/default.nix @@ -78,6 +78,12 @@ let includeModuleSystemOptions = false; }; + nextcloudOptionsDocs = buildOptionsDocs { + modules = [ ../modules/services/nextcloud-server.nix scrubbedModule ]; + variablelistId = "selfhostblocks-options"; + includeModuleSystemOptions = false; + }; + nmd = import nmdsrc { inherit lib; # The DocBook output of `nixos-render-docs` doesn't have the change @@ -134,6 +140,11 @@ in stdenv.mkDerivation { '@OPTIONS_JSON@' \ ${backupOptionsDocs.optionsJSON}/share/doc/nixos/options.json + substituteInPlace ./modules/services/nextcloud-server/docs/default.md \ + --replace \ + '@OPTIONS_JSON@' \ + ${nextcloudOptionsDocs.optionsJSON}/share/doc/nixos/options.json + find . -name "*.md" -print0 | \ while IFS= read -r -d ''' f; do substituteInPlace "''${f}" \ diff --git a/docs/demos.md b/docs/demos.md new file mode 100644 index 0000000..f83a818 --- /dev/null +++ b/docs/demos.md @@ -0,0 +1,12 @@ +# Demos {#demos} + +These demos are showcasing what Self Host Blocks can do. They deploy a block or a service on a VM on +your local machine with minimal manual steps. + +```{=include=} chapters html:into-file=//demo-homeassistant.html +demo/homeassistant/README.md +``` + +```{=include=} chapters html:into-file=//demo-nextcloud-server.html +demo/nextcloud/README.md +``` diff --git a/docs/manual.md b/docs/manual.md index ebc00a2..f2385d5 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -7,12 +7,16 @@ preface.md ``` +```{=include=} chapters html:into-file=//services.html +services.md +``` + ```{=include=} chapters html:into-file=//blocks.html blocks.md ``` -```{=include=} chapters html:into-file=//demo-homeassistant.html -demo/homeassistant/README.md +```{=include=} chapters html:into-file=//demos.html +demos.md ``` ```{=include=} appendix html:into-file=//options.html diff --git a/docs/services.md b/docs/services.md new file mode 100644 index 0000000..eb82b7f --- /dev/null +++ b/docs/services.md @@ -0,0 +1,17 @@ +# Services {#services} + +| Service | Backup | Reverse Proxy | SSO | LDAP | Monitoring | Profiling | +|-----------------------|--------|---------------|-----|-------|------------|-----------| +| [Nextcloud Server][1] | P (1) | Y | N | P (2) | Y | P (3) | + +Legend: **N**: no but WIP; **P**: partial; **Y**: yes + +1. Does not backup the database yet. +2. Works but requires manually setting up the integration. +3. Works but the traces are not exported to Grafana yet. + +[1]: services-nextcloud.html + +```{=include=} chapters html:into-file=//services-nextcloud.html +modules/services/nextcloud-server/docs/default.md +``` diff --git a/modules/blocks/backup/docs/default.md b/modules/blocks/backup/docs/default.md index 9946c00..9405da5 100644 --- a/modules/blocks/backup/docs/default.md +++ b/modules/blocks/backup/docs/default.md @@ -209,6 +209,11 @@ below) is the former splits the backups into sub-folders on the repositories. shb.backup.instances.all = backupcfg repos ["/var/lib/myfolder1" "/var/lib/myfolder2"]; ``` +## Demo {#blocks-backup-demo} + +Head over to the [Home Assistant demo](demo-homeassistant.html) for a demo that installs Home +Assistant on a VM with minimal manual steps. + ## Monitoring {#monitoring-backup-block} [WIP] diff --git a/modules/services/nextcloud-server/docs/default.md b/modules/services/nextcloud-server/docs/default.md new file mode 100644 index 0000000..d95f8b4 --- /dev/null +++ b/modules/services/nextcloud-server/docs/default.md @@ -0,0 +1,152 @@ +# Nextcloud Server Service {#services-nextcloud-server} + +Defined in [`/modules/services/nextcloud-server.nix`](@REPO@/modules/services/nextcloud-server.nix). + +This NixOS module is a service that sets up a [Nextcloud Server](https://nextcloud.com/). + +## Features {#services-nextcloud-server-features} + +- Integration Tests (TODO: need to add some) +- [Demo](./demo-nextcloud-server.html) +- Access through subdomain using reverse proxy. +- Access through HTTPS using reverse proxy. +- Automatic setup of PostgreSQL database. +- Backup of the [`shb.nextcloud.dataDir`][1] through the [backup block](./blocks-backup.html). +- Monitoring of reverse proxy, PHP-FPM, and database backups through the [monitoring + block](./blocks-monitoring.html). +- Automatic setup of Only Office service if the `shb.nextcloud.onlyoffice` option is given. The + integration still needs to be set up in the UI manually though. +- Access to advanced options not exposed here thanks to how NixOS modules work. + +[1]: ./services-nextcloud.html#services-nextcloud-server-options-shb.nextcloud.dataDir + +## Usage {#services-nextcloud-server-usage} + +### Minimal {#services-nextcloud-server-usage-minimal} + +This will set up a Nextcloud service that runs on the NixOS target machine, reachable at +`http://nextcloud.example.com`. If the `shb.ssl` block is [enabled](block-ssl.html#usage), the +instance will be reachable at `https://nextcloud.example.com`. + +```nix +shb.nextcloud = { + enable = true; + domain = "example.com"; + subdomain = "nextcloud"; + dataDir = "/var/lib/nextcloud"; + adminPassFile = ; +}; +``` + +The secret should not be stored in the nix store. If you're using +[sops-nix](https://github.com/Mic92/sops-nix) and assuming your secrets file is located at +`./secrets.yaml`, you can set the `adminPassFile` option with: + +```nix +shb.nextcloud.adminPassFile = config.sops.secrets."nextcloud/adminpass".path; + +sops.secrets."nextcloud/adminpass" = { + sopsFile = ./secrets.yaml; + mode = "0400"; + owner = "nextcloud"; + group = "nextcloud"; + restartUnits = [ "phpfpm-nextcloud.service" ]; +}; +``` + +### Tweak PHPFpm Config {#services-nextcloud-server-usage-phpfpm} + +```nix +shb.nextcloud.phpFpmPoolSettings = { + "pm" = "dynamic"; + "pm.max_children" = 800; + "pm.start_servers" = 300; + "pm.min_spare_servers" = 300; + "pm.max_spare_servers" = 500; + "pm.max_spawn_rate" = 50; + "pm.max_requests" = 50; + "pm.process_idle_timeout" = "20s"; +}; +``` + +### Tweak PostgreSQL Settings {#services-nextcloud-server-usage-postgres} + +```nix +shb.nextcloud.postgresSettings = { + max_connections = "100"; + shared_buffers = "512MB"; + effective_cache_size = "1536MB"; + maintenance_work_mem = "128MB"; + checkpoint_completion_target = "0.9"; + wal_buffers = "16MB"; + default_statistics_target = "100"; + random_page_cost = "1.1"; + effective_io_concurrency = "200"; + work_mem = "2621kB"; + huge_pages = "off"; + min_wal_size = "1GB"; + max_wal_size = "4GB"; +}; +``` + +### Backup the Nextcloud data {#services-nextcloud-server-usage-backup} + +TODO + +### Enable OnlyOffice Server {#services-nextcloud-server-usage-onlyoffice} + +The following snippets sets up an onlyoffice instance listening at `onlyoffice.example.com` that +only listens on the local nextwork. + +```nix +shb.nextcloud.onlyoffice = { + subdomain = "onlyoffice"; + localNextworkIPRange = "192.168.1.1/24"; +}; +``` + +You still need to install the OnlyOffice integration in Nextcloud UI. Setting up the integration +declaratively is WIP. + +Also, you will need to explicitly allow the package `corefonts`: + +```nix +nixpkgs.config.allowUnfreePredicate = pkg: builtins.elem (pkgs.lib.getName pkg) [ + "corefonts" +]; +``` + +### Enable Monitoring {#services-nextcloud-server-server-usage-monitoring} + +Enable the [monitoring block](./blocks-monitoring.html). + +### Enable Tracing {#services-nextcloud-server-server-usage-tracing} + +You can enable tracing with: + +```nix +shb.nextcloud.debug = true; +``` + +Traces will be located at `/var/log/xdebug`. + +See [my blog +post](http://blog.tiserbox.com/posts/2023-08-12-what%27s-up-with-nextcloud-webdav-slowness.html) for +how to look at the traces. + +## Demo {#services-nextcloud-server-demo} + +Head over to the [Nextcloud demo](demo-nextcloud.html) for a demo that installs Nextcloud on a VM +with minimal manual steps. + +## Maintenance {#services-nextcloud-server-maintenance} + +On the command line, the `occ` tool is called `nextcloud-occ`. + +## Options Reference {#services-nextcloud-server-options} + +```{=include=} options +id-prefix: services-nextcloud-server-options- +list-id: selfhostblocks-service-nextcloud-options +source: @OPTIONS_JSON@ +```