hosting/selfhostblocks
1
0
Fork 0
Code Issues Activity

add nextcloud manual

Browse source
This commit is contained in:
ibizaman 2023-12-23 22:50:22 -08:00 committed by Pierre Penninckx
parent 58bc179192
commit d908ae31c5
8 changed files with 232 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
demo/homeassistant/README.md
View file

@ -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.

28
demo/nextcloud/README.md
View file

@ -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.

11
docs/default.nix
View file

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

12
docs/demos.md Normal file
View file

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

8
docs/manual.md
View file

@ -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

17
docs/services.md Normal file
View file

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

5
modules/blocks/backup/docs/default.md
View file

@ -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]

152
modules/services/nextcloud-server/docs/default.md Normal file
View file

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