add nextcloud manual

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.
 

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.
 

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}" \

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
+```

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
+```{=include=} chapters html:into-file=//demos.html
-demo/homeassistant/README.md
+demos.md
 ```
 
 ```{=include=} appendix html:into-file=//options.html

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
+```

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]

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 = <path/to/secret>;
+};
+```
+
+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@
+```