From d398b9f9e107ab692f4b465ea4d953c132e9ae8b Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Sun, 20 Sep 2026 16:21:57 +0200
Subject: [PATCH 01/21] allow specifying #! inside shell

fixes #51
---
 CHANGELOG.md      |  4 ++++
 README.md         | 15 +++++++++++--
 example-script.sh |  1 +
 src/script.rs     | 57 ++++++++++++++++++++++++++++++++++-------------
 4 files changed, 60 insertions(+), 17 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8c1b845..d3e4fd8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## Unreleased
+
+- Support having a `#!` inside a haze script to specify the interperter to use
+
 ## 2.4.1
 
 - Show database location on start
diff --git a/README.md b/README.md
index d66688b..b05dfe4 100644
--- a/README.md
+++ b/README.md
@@ -447,8 +447,19 @@ script can be overriden by running the script with
 
 ## Nushell scripts
 
-By default, the script contents are executed as a `bash` script, you can instead
-execute the script as a `nushell` script by using `.nu` as the file extention.
+By default, the script contents are executed as either `bash` script, or `nu` script based on the extension.
+
+You can overwrite the interpreter used to execute the script by adding an extra `#!` line to the script, for example:
+
+```bash
+#! /usr/bin/env -S haze script
+#! haze shell pgsql s3
+#! php -f
+<?php
+print("Hello");
+```
+
+Note that the interpreter used needs to already be available inside the haze container.
 
 ## Configuration
 
diff --git a/example-script.sh b/example-script.sh
index 5e8a821..410a702 100755
--- a/example-script.sh
+++ b/example-script.sh
@@ -1,5 +1,6 @@
 #! /usr/bin/env -S haze script
 #! haze shell pgsql s3
+#! /usr/bin/env nu
 
 echo 'test' | occ file:put '-' /admin/files/test.txt
 FILE_ID=$(occ info:file /admin/files/test.txt | grep fileid: | grep -oE '[0-9]+')
diff --git a/src/script.rs b/src/script.rs
index 4154be0..da972f6 100644
--- a/src/script.rs
+++ b/src/script.rs
@@ -1,4 +1,4 @@
-use std::fs::read_to_string;
+use std::{fs::read_to_string, iter::once};
 
 use bollard::Docker;
 use camino::Utf8PathBuf;
@@ -36,15 +36,17 @@ pub async fn run_script(
     let contents = read_to_string(&path)
         .into_diagnostic()
         .wrap_err_with(|| format!("Failed to read script file {path}"))?;
-    let (mut options, mode) = parse_script(&contents, config)
+    let script = parse_script(&contents, config)
         .wrap_err_with(|| format!("Failed to parse script file {path}"))?;
-    let mode = mode_override.unwrap_or(mode);
+
+    let mode = mode_override.unwrap_or(script.mode);
+    let mut options = script.options;
 
     let target_path = Utf8PathBuf::from(format!("/{}", path.file_name().unwrap()));
-    let shell = if path.extension() == Some("nu") {
-        "nu"
-    } else {
-        "bash"
+    let shell = match (script.shell, path.extension()) {
+        (Some(shell), _) => shell,
+        (None, Some("nu")) => vec!["nu".into()],
+        _ => vec!["bash".into()],
     };
 
     options.mappings.push(
@@ -61,7 +63,10 @@ pub async fn run_script(
     cloud
         .exec(
             docker,
-            vec![shell.to_string(), target_path.into_string()],
+            shell
+                .into_iter()
+                .chain(once(target_path.into_string()))
+                .collect(),
             true,
             get_forward_env(),
         )
@@ -74,14 +79,22 @@ pub async fn run_script(
     Ok(())
 }
 
-fn parse_script(script: &str, config: &HazeConfig) -> Result<(CloudOptions, ScriptMode)> {
-    let (options, mode) = script
+#[derive(Debug)]
+struct Script {
+    options: CloudOptions,
+    mode: ScriptMode,
+    shell: Option<Vec<String>>,
+}
+
+fn parse_script(script: &str, config: &HazeConfig) -> Result<Script> {
+    let (options, mode, line_num) = script
         .lines()
-        .find_map(|line| line.strip_prefix("#! haze "))
+        .enumerate()
+        .find_map(|(i, line)| Some((i, line.strip_prefix("#! haze ")?)))
         .and_then(
-            |line| match (line.strip_prefix("shell"), line.strip_prefix("start")) {
-                (Some(shell_options), None) => Some((shell_options.trim(), ScriptMode::Shell)),
-                (None, Some(script_options)) => Some((script_options.trim(), ScriptMode::Start)),
+            |(i, line)| match (line.strip_prefix("shell"), line.strip_prefix("start")) {
+                (Some(shell_options), None) => Some((shell_options.trim(), ScriptMode::Shell, i)),
+                (None, Some(script_options)) => Some((script_options.trim(), ScriptMode::Start, i)),
                 _ => None,
             },
         )
@@ -90,5 +103,19 @@ fn parse_script(script: &str, config: &HazeConfig) -> Result<(CloudOptions, Scri
 
     let options =
         CloudOptions::parse(config, &mut options).wrap_err("Failed to parse shell options")?;
-    Ok((options, mode))
+
+    let first_content_line = script.lines().nth(line_num + 1).unwrap_or_default();
+    let shell = first_content_line.strip_prefix("#!").map(|bang| {
+        bang.split(" ")
+            .map(str::trim)
+            .filter(|s| !s.is_empty())
+            .map(String::from)
+            .collect()
+    });
+
+    Ok(Script {
+        options,
+        mode,
+        shell,
+    })
 }

From d615322449a8cb94ced351f876b3573be3a694fb Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Sun, 20 Sep 2026 18:11:28 +0200
Subject: [PATCH 02/21] [wip] port readme contents over to an mdbook

---
 README.md                 |   9 +-
 book/.gitignore           |   1 +
 book/book.toml            |   4 +
 book/src/README.md        |   7 +
 book/src/SUMMARY.md       |  11 ++
 book/src/configuration.md | 272 ++++++++++++++++++++++++++++++++++++++
 book/src/frankenphp.md    |   1 +
 book/src/proxy/README.md  |  91 +++++++++++++
 book/src/proxy/dns.md     |  27 ++++
 book/src/proxy/https.md   |  78 +++++++++++
 book/src/setup.md         |  33 +++++
 book/src/xdebug.md        |   1 +
 flake.nix                 |   1 +
 13 files changed, 533 insertions(+), 3 deletions(-)
 create mode 100644 book/.gitignore
 create mode 100644 book/book.toml
 create mode 100644 book/src/README.md
 create mode 100644 book/src/SUMMARY.md
 create mode 100644 book/src/configuration.md
 create mode 100644 book/src/frankenphp.md
 create mode 100644 book/src/proxy/README.md
 create mode 100644 book/src/proxy/dns.md
 create mode 100644 book/src/proxy/https.md
 create mode 100644 book/src/setup.md
 create mode 100644 book/src/xdebug.md

diff --git a/README.md b/README.md
index b05dfe4..23f3b8d 100644
--- a/README.md
+++ b/README.md
@@ -447,9 +447,11 @@ script can be overriden by running the script with
 
 ## Nushell scripts
 
-By default, the script contents are executed as either `bash` script, or `nu` script based on the extension.
+By default, the script contents are executed as either `bash` script, or `nu`
+script based on the extension.
 
-You can overwrite the interpreter used to execute the script by adding an extra `#!` line to the script, for example:
+You can overwrite the interpreter used to execute the script by adding an extra
+`#!` line to the script, for example:
 
 ```bash
 #! /usr/bin/env -S haze script
@@ -459,7 +461,8 @@ You can overwrite the interpreter used to execute the script by adding an extra
 print("Hello");
 ```
 
-Note that the interpreter used needs to already be available inside the haze container.
+Note that the interpreter used needs to already be available inside the haze
+container.
 
 ## Configuration
 
diff --git a/book/.gitignore b/book/.gitignore
new file mode 100644
index 0000000..e9c0728
--- /dev/null
+++ b/book/.gitignore
@@ -0,0 +1 @@
+book
\ No newline at end of file
diff --git a/book/book.toml b/book/book.toml
new file mode 100644
index 0000000..c2ab188
--- /dev/null
+++ b/book/book.toml
@@ -0,0 +1,4 @@
+[book]
+title = "Haze"
+authors = ["Robin Appelman"]
+language = "en"
diff --git a/book/src/README.md b/book/src/README.md
new file mode 100644
index 0000000..8d340b0
--- /dev/null
+++ b/book/src/README.md
@@ -0,0 +1,7 @@
+# Haze
+
+Hazy with a chance of clouds.
+
+`haze` is a tool that provides provides an easy way to set up Nextcloud test
+instances with a choice of php version, database server, optional s3 or ldap
+setup and much more.
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
new file mode 100644
index 0000000..565c8e4
--- /dev/null
+++ b/book/src/SUMMARY.md
@@ -0,0 +1,11 @@
+# Summary
+
+[Introduction](README.md)
+
+- [Setup](setup.md)
+- [Configuration](configuration.md)
+- [Proxy](proxy/README.md)
+  - [DNS](proxy/dns.md)
+  - [HTTPS](proxy/https.md)
+- [Xdebug](xdebug.md)
+- [FrankenPHP (experimental)](frankenphp.md)
diff --git a/book/src/configuration.md b/book/src/configuration.md
new file mode 100644
index 0000000..ab42b18
--- /dev/null
+++ b/book/src/configuration.md
@@ -0,0 +1,272 @@
+# Configuration
+
+Configuration is loaded from `~/.config/haze/haze.toml`.
+
+The minimum required configuration needed to get started is just the
+`sources_root` options.
+
+The full list of supported options is:
+
+### sources_root
+
+The local path of the nextcloud sources. This options is **required**.
+
+Type: string
+
+### app_directories
+
+A list of additional app directory paths to look for apps into
+
+Default `[]`
+
+Type: list of strings
+
+### work_dir
+
+The location where haze keeps it's temporary files and caches
+
+Default: `/tmp/haze`
+
+Type: string
+
+### worktree_dir
+
+The location to to store git worktrees when using instances with detached
+sources.
+
+Default: `<work_dir>/worktrees`
+
+Type: string
+
+## auto_setup
+
+Options for automatically setting up the newly created Nextcloud instance.
+
+Examples:
+
+```toml
+[auto_setup]
+username = "foo"
+password = "bar"
+enable_apps = ["files_external"]
+disable_apps = ["contacts"]
+post_setup = [
+    "occ group:add test",
+]
+config = { "enforce_theme" = "dark" }
+```
+
+```toml
+[auto_setup]
+enabled = false
+```
+
+### auto_setup.enabled
+
+Whether to automatically setup Nextcloud inside a created instance.
+
+Default: `true`
+
+Type: boolean
+
+### auto_setup.username
+
+The username to use for the admin account during auto setup.
+
+Default: `admin`
+
+Type: string
+
+### auto_setup.password
+
+The password to use for the admin account during auto setup.
+
+Default: `admin`
+
+Type: string
+
+### auto_setup.enabled_apps
+
+Extra apps to enable after auto setup
+
+Default: `[]`
+
+Type: list of strings
+
+### auto_setup.disabled_apps
+
+Apps to disabled after auto setup
+
+Default: `[]`
+
+Type: list of strings
+
+### auto_setup.post_setup
+
+Commands to execute after auto setup
+
+Default: `[]`
+
+Type: list of strings
+
+### auto_setup.config
+
+System configuration options to set before auto setup
+
+Default: `{}`
+
+Type: Object
+
+## volume
+
+Additional files or directories to bind-mount into instances.
+
+Any number of volume options can be configured
+
+Examples:
+
+```toml
+[[volume]]
+source = "/tmp/haze-shared"
+target = "/shared"
+create = true
+```
+
+```toml
+[[volume]]
+source = "/home/me/Downloads"
+target = "/Downloads"
+read_only = true
+```
+
+### volume.source
+
+The source path on the host
+
+Type: string
+
+### volume.target
+
+The target path inside the container
+
+Type: string
+
+### volume.create
+
+Create the source directory on the host if it doesn't exist already.
+
+Default: `false`
+
+Type: boolean
+
+### volume.read_only
+
+Whether to mount the file or directory as read read_only
+
+Default: `false`
+
+Type: boolean
+
+### preset
+
+Configured presets that can be used when creating instances.
+
+Any number of presets can be configured.
+
+Example:
+
+```toml
+[[preset]]
+name = "groupfolders"
+apps = ["groupfolders"]
+commands = [
+    "occ groupfolders:create gf",
+    "occ groupfolders:group 1 admin read write share delete"
+]
+```
+
+### preset.name
+
+The name of the preset, this is used when creating instances to select the
+preset.
+
+Type: string without whitespace
+
+### preset.apps
+
+A list of apps to enable when the preset is used.
+
+Default: `[]`
+
+Type: list of strings
+
+### preset.commands
+
+A list of commands to run post-setup when the preset is used.
+
+Default: `[]`
+
+Type: list of strings
+
+## proxy
+
+Configuration for the haze proxy. Only required when using the proxy.
+
+```toml
+[proxy]
+address = "haze.example.com"
+listen = "/run/haze/haze.sock"
+https = true
+cert = "/path/to/haze.test.crt"
+key = "/path/to/haze.test.key"
+```
+
+### proxy.listen
+
+The ip and port or unix socket for the proxy to listen on.
+
+**Required** when the proxy is enabled.
+
+Type: string
+
+Examples:
+
+```toml
+listen = "/run/haze/haze.sock"
+```
+
+```toml
+listen = "127.0.0.1:8080"
+```
+
+### proxy.address
+
+The base domain the proxy is accessible on.
+
+**Required** if the proxy is enabled.
+
+Type: string
+
+### proxy.https
+
+Whether to enable built-in https support for the proxy.
+
+Default: `false`
+
+Type: boolean
+
+### proxy.cert
+
+The path of the PEM encoded certificate chain to use for https.
+
+**Required** if https is enabled for the proxy.
+
+Type: string.
+
+### proxy.cert
+
+The path of the PEM encoded private key to use for https.
+
+**Required** if https is enabled for the proxy.
+
+Type: string.
diff --git a/book/src/frankenphp.md b/book/src/frankenphp.md
new file mode 100644
index 0000000..ad8871f
--- /dev/null
+++ b/book/src/frankenphp.md
@@ -0,0 +1 @@
+# FrankenPHP (experimental)
diff --git a/book/src/proxy/README.md b/book/src/proxy/README.md
new file mode 100644
index 0000000..5be009b
--- /dev/null
+++ b/book/src/proxy/README.md
@@ -0,0 +1,91 @@
+# Proxy
+
+By default, instances can be accessed by their IP. In order to get more
+memorable URLs and allow supporting https. haze comes with a builtin reverse
+proxy to allow using a wildcard domain.
+
+## Setup
+
+- [Setup a DNS record](./dns.html) for `*.haze.example.com` and
+  `haze.example.com` pointing to your development machine.
+- Set the `proxy` configuration with your domain and desired listen endpoint.
+- Set up a service to run `haze proxy` in the background as your own user. A
+  systemd user service is recommended (see
+  [haze.service](<[./haze.service](https://codeberg.org/icewind/haze/src/branch/main/haze.service)>)
+  for an example).
+- If you're already running a reverse proxy, configure your reverse proxy of
+  choice to proxy `*.haze.example.com` and `haze.example.com` to the proxy's
+  listen endpoint.
+- (Optionally) [setup https](./https.html) for the proxy.
+
+### Configuration
+
+Add the following configuration to the `haze.toml` config file:
+
+```toml
+[proxy]
+address = "haze.example.com" # the base domain for the proxy to use
+listen = "127.0.0.1:8080" # the port+ip to listen on
+# listen = "/var/run/haze/haze.sock" # or a unix socket path
+```
+
+### Without a reverse proxy
+
+If you have no other http(s) servers on your development machine, you can setup
+things without a reverse proxy.
+
+Simply configure the proxy to listen on port `80` (or `443` when using http).
+
+Binding to port 80 or443 as a regular user requires either giving the haze
+binary the `net_bind_service` capability with
+`sudo setcap cap_net_bind_service=+ep $(which haze)` (this will have to be done
+every time your upgrade haze) or configure your system to allow unpriviled users
+to bind on the low port numbers. Using
+`sysctl net.ipv4.ip_unprivileged_port_start=80` and writing
+
+```
+net.ipv4.ip_unprivileged_port_start=80
+```
+
+to `/etc/sysctl.d/bind.conf` to make it persistent across reboot.
+
+### With a reverse proxy
+
+If you're already have other http(s) services listening on your machine, you'll
+probably want to setup a reverse proxy to allow them to all be served on your
+machine.
+
+The setup for this will depend on your reverse proxy of the choice, the
+following example config is for `nginx`.
+
+```nginx
+upstream haze-handler {
+    server unix:/var/run/haze/haze.sock;
+}
+
+server {
+    listen 80;
+    server_name *.haze.example.com;
+
+    location / {
+            proxy_pass http://haze-handler;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+## Usage
+
+When the proxy is configured, generated URLs for the instances will use a
+subdomain of the configured domain, e.g. the `rolling-bees` instance will be
+available at `rolling-bees.haze.example.com`. Additionally, `haze.example.com`
+will automatically point to the last created instance.
+
+Additionally, the proxy allows access to the service containers trough either
+`<instance id>-<service id>.haze.example.com` for a specific instance, or
+`<service-id>.haze.example.com` for the last created instance. For example
+`rolling-bees-mail.haze.example.com` will give access to the smtp4dev web
+interface of the `rolling-bees` instance.
diff --git a/book/src/proxy/dns.md b/book/src/proxy/dns.md
new file mode 100644
index 0000000..c0dc85d
--- /dev/null
+++ b/book/src/proxy/dns.md
@@ -0,0 +1,27 @@
+# DNS
+
+Since the domain name used for the instance is dynamic, a wildcard dns record is
+required.
+
+## With your domain's DNS provider
+
+If you own a domain you would like to use, you can create a wildcard domain
+withing the DNS settings of your DNS provider. For example creating a record an
+`A` record for `*.haze.example.com` with a value of `127.0.0.1` and a similar
+one for `haze.example.com`.
+
+## With a local dnsmasq
+
+If you do not own a "real" domain for using with haze, you can setup `dnsmasq`
+locally to achieve the same goal instead.
+
+How to install and enable `dnsmasq` will depend on your distro of choice and
+should be documented by it's documentation.
+
+Once setup, a configuration line like
+
+```
+address=/haze.local/172.0.0.1
+```
+
+should be enough to point `haze.local` and `*.haze.local` to your local host.
diff --git a/book/src/proxy/https.md b/book/src/proxy/https.md
new file mode 100644
index 0000000..0acd6c1
--- /dev/null
+++ b/book/src/proxy/https.md
@@ -0,0 +1,78 @@
+# HTTPS
+
+The proxy can be setup to enable using https to access the running instances.
+Besides the warm and fuzy feeling of knowing that nobody can snoop on the trafic
+that is happening completely local inside your machine. Accessing the page over
+https is required for some javascript features (such as service workers), as
+they are only available in "secure contexts".
+
+## Getting a wildcard certificate
+
+Since the domain name used for the instance is dynamic, a wildcard certificate
+is required.
+
+## Let's encrypt
+
+Let's encrypt allows getting trusted wildcard certificates for free if you can
+use DNS validation.
+
+How to setup DNS validation will depend on the specifics of the DNS provider and
+ACME client.
+[This](https://community.letsencrypt.org/t/dns-providers-who-easily-integrate-with-lets-encrypt-dns-validation/86438)
+lists some DNS providers and supported ACME clients.
+
+## Self signed
+
+You can also create a self-signed wildcard certificate using a tool like
+`mkcert`. This certificate will not be trusted by your browser and tools like
+curl, but you can add manually add it to the trusted certificates on your
+system, or bypass the certficate warning in the browser/curl every time.
+
+```bash
+# Generate local wildcard certificate
+mkcert -cert-file <path-to-your-certificats>haze.example.com.crt -key-file <path-to-your-certificats>haze.example.com.key '*.haze.example.com'
+```
+
+## Using the certificate
+
+### Without reverse proxy
+
+The haze proxy can serve over https directly, to enable that add the following
+to the `[proxy]` section of your `haze.toml`.
+
+```toml
+https = true
+cert = "/path/to/haze.example.com.crt"
+key = "/path/to/haze.example.com.key"
+```
+
+You might also want to change the port it's listening on to `443`.
+
+### With a reverse proxy
+
+This depends on what reverse proxy you have setup. The following example is for
+`nginx`.
+
+```nginx
+upstream haze-handler {
+    server unix:/run/haze/haze.sock;
+}
+
+server {
+    listen 80;
+    listen 443 ssl;
+    http2 on;
+    server_name *.haze.example.com;
+
+    ssl_certificate     <path-to-your-certificats>/haze.example.com.crt;
+    ssl_certificate_key <path-to-your-certificats>/haze.example.com.key;
+
+    location / {
+            proxy_pass http://haze-handler;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
diff --git a/book/src/setup.md b/book/src/setup.md
new file mode 100644
index 0000000..f191167
--- /dev/null
+++ b/book/src/setup.md
@@ -0,0 +1,33 @@
+# Setup
+
+## Requirements
+
+- Docker
+
+## Installation
+
+- Grab a binary from the
+  [Codeberg releases](https://codeberg.org/icewind/haze/releases) and place it
+  in your `$PATH`
+
+## Config
+
+Create a file `~/.config/haze/haze.toml` with the following options:
+
+```toml
+sources_root = "/path/to/nextcloud/sources"
+```
+
+See the [configuration section](./configuration.html) for more options.
+
+## Test the Setup
+
+### Quick examples
+
+- Start a basic Nextcloud instance:
+
+  ```bash
+  haze start
+  ```
+
+- Navigate to the address that is provided in the output.
diff --git a/book/src/xdebug.md b/book/src/xdebug.md
new file mode 100644
index 0000000..e0cf5e1
--- /dev/null
+++ b/book/src/xdebug.md
@@ -0,0 +1 @@
+# Xdebug
diff --git a/flake.nix b/flake.nix
index 99f9772..bde0f45 100644
--- a/flake.nix
+++ b/flake.nix
@@ -63,6 +63,7 @@
           bacon
           skopeo
           dive
+          mdbook
         ];
 
       homeModules = {

From 070972a316c2b5aac9879120140e4d56be7453a2 Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Sun, 20 Sep 2026 18:28:33 +0200
Subject: [PATCH 03/21] book ci

---
 .forgejo/workflows/book-pr.yaml | 58 +++++++++++++++++++++++++++++++++
 .forgejo/workflows/book.yaml    | 29 +++++++++++++++++
 flake.nix                       |  1 +
 nix/book.nix                    | 20 ++++++++++++
 nix/overlay.nix                 |  1 +
 5 files changed, 109 insertions(+)
 create mode 100644 .forgejo/workflows/book-pr.yaml
 create mode 100644 .forgejo/workflows/book.yaml
 create mode 100644 nix/book.nix

diff --git a/.forgejo/workflows/book-pr.yaml b/.forgejo/workflows/book-pr.yaml
new file mode 100644
index 0000000..cde53e6
--- /dev/null
+++ b/.forgejo/workflows/book-pr.yaml
@@ -0,0 +1,58 @@
+name: "Book - PR"
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+
+concurrency:
+  group: page-preview
+  cancel-in-progress: false
+
+jobs:
+  createPreview:
+    runs-on: nix
+    env:
+      SITE_ORIGIN:
+        "https://${{ forge.event.repository.owner.username
+        }}.preview.codeberg.page"
+      SITE_BASEPATH:
+        "/${{ forge.event.repository.name }}@${{ forge.event.number }}/"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: https://codeberg.org/icewind/attic-action@v1
+        with:
+          name: link
+          instance: https://cache.icewind.link
+          authToken: "${{ secrets.ATTIC_TOKEN }}"
+      - name: Build
+        run: |
+          # git-pages/action doesn't like symlinks
+          cp -r $(nix build .#haze-book --print-out-paths --no-link) dist
+      - name: "Deploy Site"
+        uses: https://code.forgejo.org/actions/git-pages@v2
+        with:
+          site: "${{ env.SITE_ORIGIN }}${{ env.SITE_BASEPATH }}" #
+          token: "${{ forge.token }}" #
+          source: "dist/" #
+      - name: "Find comment"
+        uses: "https://github.com/peter-evans/find-comment@v4" #
+        id: comment
+        with:
+          issue-number: ${{ forge.event.number }} #
+          body-includes: "<!-- preview-comment -->" #
+      - name: "Create or update comment"
+        uses: "https://github.com/peter-evans/create-or-update-comment@v5" #
+        with:
+          issue-number: ${{ forge.event.number }} #
+          comment-id: "${{ steps.comment.outputs.comment-id }}" #
+          edit-mode: "replace"
+          body: |-
+            # Pull request preview ready!
+
+            The Preview of commit ${{ forge.event.pull_request.head.sha }} has been created.
+            You can find it here: ${{ env.SITE_ORIGIN }}${{ env.SITE_BASEPATH }}
+
+            <!-- preview-comment -->
diff --git a/.forgejo/workflows/book.yaml b/.forgejo/workflows/book.yaml
new file mode 100644
index 0000000..05b4f11
--- /dev/null
+++ b/.forgejo/workflows/book.yaml
@@ -0,0 +1,29 @@
+name: "Book"
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  preview:
+    runs-on: nix
+    env:
+      SITE_ORIGIN: "${{forge.event.repository.owner.username}}.codeberg.page"
+      SITE_BASEPATH: "/${{forge.event.repository.name}}/"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: https://codeberg.org/icewind/attic-action@v1
+        with:
+          name: link
+          instance: https://cache.icewind.link
+          authToken: "${{ secrets.ATTIC_TOKEN }}"
+      - name: Build
+        run: |
+          # git-pages/action doesn't like symlinks
+          cp -r $(nix build .#haze-book --print-out-paths --no-link) dist
+      - uses: https://codeberg.org/git-pages/action@v2
+        with:
+          site: https://${{ env.SITE_ORIGIN }}${{ env.SITE_BASEPATH }}
+          token: ${{ forge.token }}
+          source: dist/
diff --git a/flake.nix b/flake.nix
index bde0f45..b9efaaa 100644
--- a/flake.nix
+++ b/flake.nix
@@ -55,6 +55,7 @@
         "haze-image-php-8.2" = pkgs: pkgs.haze-image-php-82;
         "haze-image-php-8.1" = pkgs: pkgs.haze-image-php-81;
         "haze-image-php-8.0" = pkgs: pkgs.haze-image-php-80;
+        haze-book = pkgs: pkgs.haze-book;
       };
 
       tools = pkgs:
diff --git a/nix/book.nix b/nix/book.nix
new file mode 100644
index 0000000..a1b1442
--- /dev/null
+++ b/nix/book.nix
@@ -0,0 +1,20 @@
+{
+  mdbook,
+  stdenv,
+  ...
+}:
+stdenv.mkDerivation {
+  name = "haze-book";
+  src = ../book;
+
+  nativeBuildInputs = [mdbook];
+
+  buildPhase = ''
+    mdbook build
+  '';
+
+  installPhase = ''
+    mkdir -p $out
+    cp -r book/* $out/
+  '';
+}
diff --git a/nix/overlay.nix b/nix/overlay.nix
index 276b70e..030b559 100644
--- a/nix/overlay.nix
+++ b/nix/overlay.nix
@@ -6,4 +6,5 @@ final: prev: {
   haze-image-php-82 = final.callPackage ./image/haze.nix {php = final.php82;};
   haze-image-php-81 = final.callPackage ./image/haze.nix {php = final.php81;};
   haze-image-php-80 = final.callPackage ./image/haze.nix {php = final.php80;};
+  haze-book = final.callPackage ./book.nix {};
 }

From d027f17ec65456dbcaaab2fa1988d93cd3a4f17a Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Sun, 20 Sep 2026 19:06:54 +0200
Subject: [PATCH 04/21] move the rest of the docs over

---
 README.md              | 539 +----------------------------------------
 book/src/README.md     |  23 ++
 book/src/SUMMARY.md    |   4 +
 book/src/federation.md |  13 +
 book/src/frankenphp.md |  10 +
 book/src/scripts.md    |  72 ++++++
 book/src/services.md   |  41 ++++
 book/src/setup.md      |   3 +
 book/src/usage.md      | 230 ++++++++++++++++++
 book/src/xdebug.md     |  30 +++
 10 files changed, 429 insertions(+), 536 deletions(-)
 create mode 100644 book/src/federation.md
 create mode 100644 book/src/scripts.md
 create mode 100644 book/src/services.md
 create mode 100644 book/src/usage.md

diff --git a/README.md b/README.md
index 23f3b8d..7e516d0 100644
--- a/README.md
+++ b/README.md
@@ -9,540 +9,7 @@ Easy setup and management of Nextcloud test instances using docker
 `haze` provides an easy way to set up Nextcloud test instances with a choice of
 php version, database server, optional s3 or ldap setup and more.
 
-## Setup
+## Documentation
 
-### Requirements
-
-- Docker
-
-### Installation
-
-- Grab a binary from the
-  [Codeberg releases](https://codeberg.org/icewind/haze/releases) and place it
-  in your `$PATH`
-
-### Config
-
-Create a file `~/.config/haze/haze.toml` with the following options:
-
-```toml
-sources_root = "/path/to/nextcloud/sources"
-```
-
-See the [configuration section](#configuration) for more options.
-
-### Quick examples
-
-- Start a Nextcloud instance with `postgresql`, and `s3` primary storage:
-
-  ```bash
-  haze start pgsql s3
-  ```
-
-- Start a Nextcloud instance with `sqlite`, `php 8.3` and an `smb` external
-  storage:
-
-  ```bash
-  haze start 8.3 smb
-  ```
-
-- Run specific units test against an `oracle` database
-  ```bash
-  haze test oracle apps/dav/tests/unit/Connector/Sabre
-  ```
-
-## Managing instances
-
-#### Start an instance
-
-```bash
-haze start [--name <name>] [--detach] [database] [php-version] [services] [vX.Y.Z]
-```
-
-Where `database` is one of `sqlite`, `mysql`, `mariadb`, `pgsql` or `oracle`
-with an optional version (e.g. `pgsql:12`), defaults to `sqlite`. And
-`php-version` is one of `8.0`, `8.1`, `8.2`, `8.3`, `8.4` or `8.5`, defaults to
-the maximum version support by the current Nextcloud version.
-
-You can specify a version number (e.g. `v32.0.2`) to use the sources from a
-release instead of using the local sources.
-
-Use `--name <name>` to give the instance a specific name instead of a randomly
-generated one. For example:
-
-Use `--detach` to give the instance
-[its own sources](#instances-with-their-own-sources) instead of sharing
-`sources_root` with all other instances.
-
-Additionally, you can use the following options when starting an instance:
-
-- `s3`: set up an S3 server and configure to Nextcloud to use it as primary
-  storage.
-  - `s3s`: enable TLS for the S3 setup.
-  - `s3mb`: enable multi-bucket S3 setup.
-  - `s3m`: enable multi-instance S3 setup.
-- `ldap`: set up an LDAP server.
-- `saml`: set up authentik as a SAML IDP.
-- `oidc`: set up authentik as an OIDC IDP.
-- `scim`: set up authentik as a SCIM server.
-- `office`: set up a Nextcloud Office server.
-- `onlyoffice` setup an onlyoffice document server.
-- `push` set up [client push](https://github.com/nextcloud/notify_push).
-- `smb`: set up a samba server for external storage use.
-- `dav`: set up a WebDAV server for external storage use.
-- `sftp`: set up a SFTP server for external storage use.
-- `sftp-key`: set up a SFTP server for external storage use with public key
-  authentication.
-- `kaspersky`: set up a kaspersky scan engine server in http mode. ( Requires
-  [manually setting up the image](https://github.com/icewind1991/kaspersky-docker))
-- `kaspersky-icap`: setup a kaspersky scan engine server in ICAP mode.
-- `clamav`: set up a local clam av scanner in executable mode.
-- `clamav-socket`: set up a clam av scanner in socket mode.
-- `clamav-icap`: set up a clam av scanner in ICAP mode.
-- `clamav-icap-tls`: set up a clam av scanner in ICAP mode with TLS encryption.
-- `oc`: start an ownCloud instance in the same network.
-- `imaginary`: start an Imaginary service and configure it for preview
-  generation.
-- `mail`: start a [smtp4dev](https://github.com/rnwood/smtp4dev) server and
-  configure it the mail server.
-- `webhook` start a
-  [webhook tester](https://github.com/tarampampam/webhook-tester)
-- `redis`: start a separate container for redis.
-- `redis-tls`: connect to redis over TLS.
-- `<path to app.tar.gz>`: by specifying the path to an app package this package
-  will be extracted into the apps. directory of the new instance (overwriting
-  any existing app code). This can be used to quickly test a packaged app.
-- The name of any configured preset.
-
-#### Run tests in a new instance
-
-```bash
-haze test [database] [php-version] [phpunit version] [path]
-```
-
-Where `path` is a file or folder to run PHPUnit in, relative to the sources
-root.
-
-### List running instances
-
-```bash
-haze
-```
-
-or
-
-```bash
-haze list
-```
-
-#### Remove all running instances
-
-```bash
-haze clean
-```
-
-### Instances with their own sources
-
-By default every instance shares the sources configured as `sources_root`, so
-all instances always run the same code. An instance started with `--detach` gets
-its own `git worktree` of `sources_root` instead, created in `worktree_dir`,
-which lets you run several instances on different branches at the same time.
-
-```bash
-haze start --name my-fix --detach
-```
-
-The worktree is checked out with a detached head. Every app in one of the
-`app_directories` that gets enabled during setup receives its own worktree as
-well, other apps keep running from the shared app directory.
-
-The worktrees are removed together with the instance, by `haze stop` or
-`haze clean`.
-
-## Controlling running instances
-
-The following commands run against the most recently started instance and allow
-optionally providing a `match` to select a specific instance by its name.
-
-#### Open an instance
-
-```bash
-haze [match] open
-```
-
-#### Open the database of an instance
-
-```bash
-haze [match] db
-```
-
-#### Execute a command on an instance
-
-```bash
-haze [match] [service] [cmd]
-```
-
-If no `cmd` is specified it will launch `bash`
-
-If a service name or `db` is provided, the command will be in the container of
-the service or database.
-
-#### Create a new instance and run a command
-
-```bash
-haze [match] shell [cmd]
-```
-
-If no `cmd` is specified it will launch `bash`
-
-#### Execute an occ command on an instance
-
-```bash
-haze [match] occ [cmd]
-```
-
-#### Connect to the database on an instance
-
-```bash
-haze [match] db
-```
-
-#### Show the logs of an instance
-
-```bash
-haze [match] logs
-```
-
-#### Stop an instance
-
-```bash
-haze [match] stop
-```
-
-#### Pin an instance
-
-```bash
-haze [match] pin
-```
-
-Pinned instances will not be removed by `haze clean`.
-
-#### Unpin an instance
-
-```bash
-haze [match] unpin
-```
-
-#### Run a command with instance environment variables set
-
-```bash
-haze [match] env <cmd> [args]
-```
-
-Runs the provided command with `NEXTCLOUD_URL`, `DATABASE_URL` and `REDIS_URL`
-environment variables set for the matched instance.
-
-This is intended to run a local
-[push daemon](https://github.com/nextcloud/notify_push) against an instance.
-
-#### Update the container images
-
-```bash
-haze update
-```
-
-#### Edit a file in an instance with the local $EDITOR
-
-```bash
-haze [match] edit <path>
-```
-
-#### Reload the php config of an instance
-
-```bash
-haze [match] reload
-```
-
-The php configuration can edit changed with `haze edit  /config/php.ini`
-
-#### Checkout a branch for all local apps
-
-```bash
-haze git checkout [branch]
-```
-
-Checks out the branch in all git repositories within the apps folder.
-
-Defaults to the branch matching the current checked out server versions (e.g.
-`master` or `stable33`).
-
-`master` and `main` can be used interchangeably.
-
-#### Pull remote changes for all local apps
-
-```bash
-haze git pull
-```
-
-Performs a pull in all git repositories within the apps folder.
-
-## Federation
-
-Multiple instances can reach each other by using their instance name as domain
-name to allow for testing federation between instances. Alternatively, you can
-set up the haze proxy and the proxied domains to get https support between
-instances.
-
-## Proxy
-
-By default, instances can be accessed by their IP. In order to get more
-memorable URLs and allow supporting https, haze comes with a builtin reverse
-proxy to allow using a wildcard domain.
-
-### DNS Setup
-
-#### Requirements
-
-- A domain name you can set wildcard DNS records for
-- A reverse proxy like Nginx or Apache
-- (optionally) a wildcard ssl certificate (can be acquiring using letsencrypt
-  and dns verification)
-
-#### Steps
-
-- Set a DNS record for `*.haze.example.com` and `haze.example.com` pointing to
-  your development machine.
-- Set the `proxy` configuration with your domain and desired listen endpoint.
-- Set up a service to run `haze proxy` in the background as your own user. A
-  systemd user service is recommended (see [haze.service](./haze.service) for an
-  example).
-- Configure your reverse proxy of choice to proxy `*.haze.example.com` and
-  `haze.example.com` to the proxy's listen endpoint
-- (optional) acquire a wildcard ssl certificate for your domain and set your
-  reverse proxy to use it. This will be highly dependent on your DNS provider,
-  [this](https://community.letsencrypt.org/t/dns-providers-who-easily-integrate-with-lets-encrypt-dns-validation/86438)
-  lists some DNS providers and supported ACME clients.
-
-### Local Setup
-
-- Setup `dnsmasq` to resolve `*.haze.test` to your development machine.
-- Generate a wildcard ssl certificate for `*.haze.test` using `mkcert`:
-
-```bash
-# Generate local wildcard certificate
-mkcert -cert-file <path-to-your-certificats>haze.test.crt -key-file <path-to-your-certificats>haze.test.key '*.haze.test'
-```
-
-- Set up a service to run `haze proxy` in the background as your own user. A
-  systemd user service is recommended (see [haze.service](./haze.service) for an
-  example).
-- Either point haze at the certificate directly:
-
-```toml
-[proxy]
-address = "haze.test"
-https = true
-listen = "127.0.0.1:443"
-cert = "<path-to-your-certificats>/haze.test.crt"
-key = "<path-to-your-certificats>/haze.test.key"
-```
-
-Binding to port 443 as a regular user requires either
-`sudo setcap cap_net_bind_service=+ep $(which haze)` or
-`sysctl net.ipv4.ip_unprivileged_port_start=443`.
-
-- Or, if you already have another web server, setup it up to proxy `*.haze.test`
-  and `haze.test` to the `haze proxy`'s socket. Example for Nginx:
-
-```nginx
-upstream haze-handler {
-    server unix:/run/haze/haze.sock;
-}
-
-server {
-    listen 80;
-    listen 443 ssl;
-    http2 on;
-    server_name *.haze.test;
-
-    ssl_certificate     <path-to-your-certificats>/haze.test.crt;
-    ssl_certificate_key <path-to-your-certificats>/haze.test.key;
-
-    location / {
-            proxy_pass http://haze-handler;
-            proxy_set_header Host $host;
-            proxy_set_header X-Real-IP $remote_addr;
-            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-            proxy_set_header X-Forwarded-Proto $scheme;
-    }
-}
-```
-
-### Usage
-
-When the proxy is configured, generated URLs for the instances will use a
-subdomain of the configured domain, e.g. the `rolling-bees` instance will be
-available at `rolling-bees.haze.example.com`. Additionally, `haze.example.com`
-will automatically point to the last created instance.
-
-Additionally, the proxy allows access to the server containers trough either
-`<instance id>-<service id>.haze.example.com` for a specific instance, or
-`<service-id>.haze.example.com` for the last created instance. For example
-`rolling-bees-mail.haze.example.com` will give access to the smtp4dev web
-interface of the `rolling-bees` instance.
-
-## Haze scripts
-
-Haze scripts combine a set of instance options and a script to run in the
-instance.
-
-Haze scripts are intended to way to create automated ways of running more
-complex tests are setting up more complex instances.
-
-A script contains of 3 paths
-
-1. An optional shebang line setting `haze` as the interpreter, e.g.
-   `#! /usr/bin/env -S haze script`
-2. A shebang line setting the options for the instance creation as the
-   interpreter, e.g. `#! haze shell pgsql s3`
-3. The rest that is ran as a script inside the created instance.
-
-The first sheband is set, the script can be ran directly. Else it needs to be
-run with `haze script [path-to-script]`.
-
-For example, the following script will create an instance with `postgresql` and
-`s3` primary storage. Then creates a new file, gets the file id, read the object
-of the file from S3, validate that it contains the expected contents, and
-cleanup the instance.
-
-```bash
-#! #! /usr/bin/env -S haze script
-#! haze shell pgsql s3
-
-echo 'test' | occ file:put '-' /admin/files/test.txt
-FILE_ID=$(occ info:file /admin/files/test.txt | grep fileid: | grep -oE '[0-9]+')
-OBJECT_CONTENTS=$(occ file:object:get urn:oid:$FILE_ID -)
-if [ "$OBJECT_CONTENTS" == 'test' ]; then
-    echo "object contains expected contents"
-else
-    echo "object does not contains expected contents!"
-fi
-```
-
-### Script modes
-
-Scripts can be either `shell` or `start` scripts.
-
-`shell` scripts will automatically remove the created instance once the script
-is done, just like `haze shell` will. The intended use case for this is
-performing some tests in the created instance without leaving state behind.
-
-`start` scripts on the other hand will keep the instance, like `haze start`
-will. The intended use case for this is creating more complex instances without
-having to configure a dedicated preset.
-
-The script mode is determined based on the shebang line. The mode set in a
-script can be overriden by running the script with
-`haze script [shell|start] path-to-script.sh`.
-
-## Nushell scripts
-
-By default, the script contents are executed as either `bash` script, or `nu`
-script based on the extension.
-
-You can overwrite the interpreter used to execute the script by adding an extra
-`#!` line to the script, for example:
-
-```bash
-#! /usr/bin/env -S haze script
-#! haze shell pgsql s3
-#! php -f
-<?php
-print("Hello");
-```
-
-Note that the interpreter used needs to already be available inside the haze
-container.
-
-## Configuration
-
-Configuration is loaded from `~/.config/haze/haze.toml` and has the following
-options
-
-```toml
-sources_root = "/path/to/sources" # path of the nextcloud sources. required
-app_directories = ["/path/to/sources/more_app"] # paths to additional app directories.
-work_dir = "/path/to/temp/dir" # path to temporary directory. optional, defaults to "/tmp/haze"
-worktree_dir = "/path/to/worktrees" # where to create the worktrees of detached instances. optional, defaults to "<work_dir>/worktrees"
-
-[auto_setup] # optional
-enabled = false # whether or not to automatically install nextcloud on `haze start`. enabled by default
-username = "foo" # username for admin user during auto setup. optional, defaults to "admin"
-password = "bar" # password for admin user during auto setup. optional, defaults to "admin"
-enable_apps = ["files_external"] # apps to enable after setup, defaults to []
-disable_apps = ["contacts"] # apps to disable after setup, defaults to []
-post_setup = [# commands to execute after setup, defaults to []
-    "occ group:add test",
-]
-config = { "foo" = "bar" } # configuration options to set before install
-
-[[volume]] # optional
-source = "/tmp/haze-shared"
-target = "/shared"
-create = true
-
-[[volume]]
-source = "/home/me/Downloads"
-target = "/Downloads"
-read_only = true
-
-[proxy] # optional
-address = "haze.example.com" # base domain
-https = true # Whether the instances are reachable over https
-listen = "/run/haze/haze.sock" # either a unix socket path
-#listen = "127.0.0.1:8080"     # or a socket address
-cert = "/path/to/haze.test.crt" # optional - PEM encoded certificate chain
-key = "/path/to/haze.test.key" # optional - PEM encoded private key
-
-# presets allow for easy usage of commonly used setups
-[[preset]]
-name = "groupfolders" # name of the preset
-apps = ["groupfolders"] # app to enable
-commands = ["occ groupfolders:create gf", "occ groupfolders:group 1 admin read write share delete"] # commands to run post-setup
-```
-
-## Xdebug
-
-Haze Xdebug is running in a docker container, you need to tell you IDE how to
-properly map the path. The IDE debugger config usually looks like:
-
-```json
-	{
-		"label": "PHP: Debug server within docker",
-		"adapter": "Xdebug",
-		"request": "launch",
-		"port": 9003,
-		"pathMappings": {
-			"/var/www/html": "<sources_root_configured_in_haze.toml>",
-			"/var/www/html/apps-extra": "<app_directories_configured_in_haze.toml>",
-		},
-	},
-```
-
-This would have to be adapted for detached instances.
-
-To enable Xdebug for all requests:
-
-- Uncomment the lines in `haze <cloud-id> edit /config/php.ini`
-- Then run `haze reload <cloud-id>`
-
-## FrankenPHP (experimental)
-
-You can have Nextcloud run on FrankenPHP.
-
-Caddy's admin metrics are then accessible through
-`http://<cloud-id>-franken-php.haze.test`. With ember you can run:
-
-```bash
-ember  --addr http://<cloud-id>-franken-php.haze.test
-```
+Documentation for haze can be found in the
+[book](https://icewind.codeberg.page/haze/)
diff --git a/book/src/README.md b/book/src/README.md
index 8d340b0..0ebd550 100644
--- a/book/src/README.md
+++ b/book/src/README.md
@@ -5,3 +5,26 @@ Hazy with a chance of clouds.
 `haze` is a tool that provides provides an easy way to set up Nextcloud test
 instances with a choice of php version, database server, optional s3 or ldap
 setup and much more.
+
+## Quickstart
+
+- Grab a binary from the
+  [Codeberg releases](https://codeberg.org/icewind/haze/releases) and place it
+  in your `$PATH`
+
+- Create a file `~/.config/haze/haze.toml` with the following content:
+
+  ```toml
+  sources_root = "/path/to/nextcloud/sources"
+  ```
+
+- Start a basic Nextcloud instance:
+
+  ```bash
+  haze start
+  ```
+
+- Navigate to the address that is provided in the output.
+
+See the [setup](./setup.html), [configuration](./configuration.html) and
+[usage](./usage.html) for a more details.
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index 565c8e4..f771191 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -3,9 +3,13 @@
 [Introduction](README.md)
 
 - [Setup](setup.md)
+- [Usage](usage.md)
 - [Configuration](configuration.md)
 - [Proxy](proxy/README.md)
   - [DNS](proxy/dns.md)
   - [HTTPS](proxy/https.md)
+- [Services](services.md)
+- [Federation](federation.md)
+- [Haze scripts](scripts.md)
 - [Xdebug](xdebug.md)
 - [FrankenPHP (experimental)](frankenphp.md)
diff --git a/book/src/federation.md b/book/src/federation.md
new file mode 100644
index 0000000..20bacd7
--- /dev/null
+++ b/book/src/federation.md
@@ -0,0 +1,13 @@
+# Federation
+
+Multiple instances can reach each other by using their instance name as domain
+name to allow for testing federation between instances.
+
+For example, if you have a `rover-beavers` and `splendid-couch` instance, you
+can create a federated share from the `rover-beavers` instance to
+`http://admin@splendid-couch`.
+
+If the proxy is setup with https, you can use https between the instances by
+using the full proxy urls.
+
+For example sharing to `admin@splendid-couch.haze.example.com`.
diff --git a/book/src/frankenphp.md b/book/src/frankenphp.md
index ad8871f..92f675b 100644
--- a/book/src/frankenphp.md
+++ b/book/src/frankenphp.md
@@ -1 +1,11 @@
 # FrankenPHP (experimental)
+
+You can have Nextcloud run on FrankenPHP by starting the instance with the
+`franken-php` option.
+
+Caddy's admin metrics are then accessible through
+`http://<cloud-id>-franken-php.haze.test`. With ember you can run:
+
+```bash
+ember  --addr http://<cloud-id>-franken-php.haze.test
+```
diff --git a/book/src/scripts.md b/book/src/scripts.md
new file mode 100644
index 0000000..00fa6f8
--- /dev/null
+++ b/book/src/scripts.md
@@ -0,0 +1,72 @@
+# Haze scripts
+
+Haze scripts combine a set of instance options and a script to run in the
+instance.
+
+Haze scripts are intended to way to create automated ways of running more
+complex tests are setting up more complex instances.
+
+A script contains of 3 paths
+
+1. An optional shebang line setting `haze` as the interpreter, e.g.
+   `#! /usr/bin/env -S haze script`
+2. A shebang line setting the options for the instance creation as the
+   interpreter, e.g. `#! haze shell pgsql s3`
+3. The rest that is ran as a script inside the created instance.
+
+The first sheband is set, the script can be ran directly. Else it needs to be
+run with `haze script [path-to-script]`.
+
+For example, the following script will create an instance with `postgresql` and
+`s3` primary storage. Then creates a new file, gets the file id, read the object
+of the file from S3, validate that it contains the expected contents, and
+cleanup the instance.
+
+```bash
+#! #! /usr/bin/env -S haze script
+#! haze shell pgsql s3
+
+echo 'test' | occ file:put '-' /admin/files/test.txt
+FILE_ID=$(occ info:file /admin/files/test.txt | grep fileid: | grep -oE '[0-9]+')
+OBJECT_CONTENTS=$(occ file:object:get urn:oid:$FILE_ID -)
+if [ "$OBJECT_CONTENTS" == 'test' ]; then
+    echo "object contains expected contents"
+else
+    echo "object does not contains expected contents!"
+fi
+```
+
+### Script modes
+
+Scripts can be either `shell` or `start` scripts.
+
+`shell` scripts will automatically remove the created instance once the script
+is done, just like `haze shell` will. The intended use case for this is
+performing some tests in the created instance without leaving state behind.
+
+`start` scripts on the other hand will keep the instance, like `haze start`
+will. The intended use case for this is creating more complex instances without
+having to configure a dedicated preset.
+
+The script mode is determined based on the shebang line. The mode set in a
+script can be overriden by running the script with
+`haze script [shell|start] path-to-script.sh`.
+
+## Using different interpreters
+
+By default, the script contents are executed as either `bash` script, or `nu`
+script based on the extension.
+
+You can overwrite the interpreter used to execute the script by adding an extra
+`#!` line to the script, for example:
+
+```bash
+#! /usr/bin/env -S haze script
+#! haze shell pgsql s3
+#! php -f
+<?php
+print("Hello");
+```
+
+Note that the interpreter used needs to already be available inside the haze
+container.
diff --git a/book/src/services.md b/book/src/services.md
new file mode 100644
index 0000000..42ea93e
--- /dev/null
+++ b/book/src/services.md
@@ -0,0 +1,41 @@
+# Services
+
+The following service options are available:
+
+- `s3`: set up an S3 server and configure to Nextcloud to use it as primary
+  storage.
+  - `s3s`: enable TLS for the S3 setup.
+  - `s3mb`: enable multi-bucket S3 setup.
+  - `s3m`: enable multi-instance S3 setup.
+- `ldap`: set up an LDAP server.
+- `saml`: set up authentik as a SAML IDP.
+- `oidc`: set up authentik as an OIDC IDP.
+- `scim`: set up authentik as a SCIM server.
+- `office`: set up a Nextcloud Office server.
+- `onlyoffice` setup an onlyoffice document server.
+- `push` set up [client push](https://github.com/nextcloud/notify_push).
+- `smb`: set up a samba server for external storage use.
+- `dav`: set up a WebDAV server for external storage use.
+- `sftp`: set up a SFTP server for external storage use.
+- `sftp-key`: set up a SFTP server for external storage use with public key
+  authentication.
+- `kaspersky`: set up a kaspersky scan engine server in http mode. ( Requires
+  [manually setting up the image](https://github.com/icewind1991/kaspersky-docker))
+- `kaspersky-icap`: setup a kaspersky scan engine server in ICAP mode.
+- `clamav`: set up a local clam av scanner in executable mode.
+- `clamav-socket`: set up a clam av scanner in socket mode.
+- `clamav-icap`: set up a clam av scanner in ICAP mode.
+- `clamav-icap-tls`: set up a clam av scanner in ICAP mode with TLS encryption.
+- `oc`: start an ownCloud instance in the same network.
+- `imaginary`: start an Imaginary service and configure it for preview
+  generation.
+- `mail`: start a [smtp4dev](https://github.com/rnwood/smtp4dev) server and
+  configure it the mail server.
+- `webhook` start a
+  [webhook tester](https://github.com/tarampampam/webhook-tester)
+- `redis`: start a separate container for redis.
+- `redis-tls`: connect to redis over TLS.
+- `<path to app.tar.gz>`: by specifying the path to an app package this package
+  will be extracted into the apps. directory of the new instance (overwriting
+  any existing app code). This can be used to quickly test a packaged app.
+- The name of any configured preset.
diff --git a/book/src/setup.md b/book/src/setup.md
index f191167..8ce4385 100644
--- a/book/src/setup.md
+++ b/book/src/setup.md
@@ -4,6 +4,9 @@
 
 - Docker
 
+haze is built around docker containers and manages containers using the docker
+socket. Using podman with docker compatibility might also work, but is untested.
+
 ## Installation
 
 - Grab a binary from the
diff --git a/book/src/usage.md b/book/src/usage.md
new file mode 100644
index 0000000..f8a23f0
--- /dev/null
+++ b/book/src/usage.md
@@ -0,0 +1,230 @@
+# Usage
+
+## Quick examples
+
+- Start a Nextcloud instance with `postgresql`, and `s3` primary storage:
+
+  ```bash
+  haze start pgsql s3
+  ```
+
+- Start a Nextcloud instance with `sqlite`, `php 8.3` and an `smb` external
+  storage:
+
+  ```bash
+  haze start 8.3 smb
+  ```
+
+- Run specific units test against an `oracle` database
+  ```bash
+  haze test oracle apps/dav/tests/unit/Connector/Sabre
+  ```
+
+## Managing instances
+
+### Starting an instance
+
+```bash
+haze start [--name <name>] [--detach] [database] [php-version] [services] [vX.Y.Z]
+```
+
+Where `database` is one of `sqlite`, `mysql`, `mariadb`, `pgsql` or `oracle`
+with an optional version (e.g. `pgsql:12`), defaults to `sqlite`. And
+`php-version` is one of `8.0`, `8.1`, `8.2`, `8.3`, `8.4` or `8.5`, defaults to
+the maximum version support by the current Nextcloud version.
+
+You can specify a version number (e.g. `v32.0.2`) to use the sources from a
+release instead of using the local sources.
+
+Use `--name <name>` to give the instance a specific name instead of a randomly
+generated one. For example:
+
+Use `--detach` to give the instance
+[its own sources](#instances-with-their-own-sources) instead of sharing
+`sources_root` with all other instances.
+
+See the [services documentation](./services.html) for a list of available
+services.
+
+### List running instances
+
+```bash
+haze
+```
+
+or
+
+```bash
+haze list
+```
+
+### Stop an instance
+
+```bash
+haze [match] stop
+```
+
+### Remove all unpinned running instances
+
+```bash
+haze clean
+```
+
+### Pin an instance
+
+```bash
+haze [match] pin
+```
+
+Pinned instances will not be removed by `haze clean`.
+
+### Unpin an instance
+
+```bash
+haze [match] unpin
+```
+
+## Run commands in a temporary instance
+
+```bash
+haze shell [database] [php-version] [services] [cmd]
+```
+
+This will create an instance, run the provided command, and cleanup the
+instance.
+
+If no `cmd` is specified it will launch `bash`
+
+## Run tests in a new instance
+
+```bash
+haze test [database] [php-version] [services] [phpunit version] [path]
+```
+
+Where `path` is a file or folder to run PHPUnit in, relative to the sources
+root.
+
+This will create a fresh instance, run the PHPUnit tests, and clean up the
+created instance.
+
+## Interacting with running instances
+
+The following commands run against the most recently started instance by default
+and allow optionally providing a `match` to select a specific instance by its
+name.
+
+### Open an instance in the browser
+
+```bash
+haze [match] open
+```
+
+### Execute a command on an instance
+
+```bash
+haze [match] [service] [cmd]
+```
+
+If no `cmd` is specified it will launch `bash`
+
+If a service name or `db` is provided, the command will be in the container of
+the service or database.
+
+If no `cmd` is specified it will launch `bash`
+
+### Execute an occ command on an instance
+
+```bash
+haze [match] occ [cmd]
+```
+
+### Connect to the database on an instance
+
+```bash
+haze [match] db
+```
+
+### Show the logs of an instance
+
+```bash
+haze [match] logs
+```
+
+### Edit a file in an instance with the local $EDITOR
+
+```bash
+haze [match] edit <path>
+```
+
+Where `<path>` is the path of a file inside the container, for example
+`config/config.php`.
+
+### Reload the php config of an instance
+
+```bash
+haze [match] reload
+```
+
+The php configuration can edit changed with `haze edit  /config/php.ini`
+
+### Run a command with instance environment variables set
+
+```bash
+haze [match] env <cmd> [args]
+```
+
+Runs the provided command with `NEXTCLOUD_URL`, `DATABASE_URL` and `REDIS_URL`
+environment variables set for the matched instance.
+
+This is intended to run a local
+[push daemon](https://github.com/nextcloud/notify_push) against an instance.
+
+## Git tools
+
+Haze provides a couple of utilities to make working with many git repositories
+for apps easier.
+
+### Checkout a branch for all local apps
+
+```bash
+haze git checkout [branch]
+```
+
+Checks out the branch in all git repositories within the apps folder.
+
+Defaults to the branch matching the current checked out server versions (e.g.
+`master` or `stable33`).
+
+`master` and `main` can be used interchangeably.
+
+### Pull remote changes for all local apps
+
+```bash
+haze git pull
+```
+
+Performs a pull in all git repositories within the apps folder.
+
+## Update the container images
+
+```bash
+haze update
+```
+
+## Instances with their own sources
+
+By default every instance shares the sources configured as `sources_root`, so
+all instances always run the same code. An instance started with `--detach` gets
+its own `git worktree` of `sources_root` instead, created in `worktree_dir`,
+which lets you run several instances on different branches at the same time.
+
+```bash
+haze start --name my-fix --detach
+```
+
+The worktree is checked out with a detached head. Every app in one of the
+`app_directories` that gets enabled during setup receives its own worktree as
+well, other apps keep running from the shared app directory.
+
+The worktrees are removed together with the instance, by `haze stop` or
+`haze clean`.
diff --git a/book/src/xdebug.md b/book/src/xdebug.md
index e0cf5e1..0a36bbe 100644
--- a/book/src/xdebug.md
+++ b/book/src/xdebug.md
@@ -1 +1,31 @@
 # Xdebug
+
+To use Xdebug running in a haze instance with your IDE for debugging, you need
+to tell you IDE how to properly map the path from the container to the host. The
+IDE debugger config usually looks like:
+
+```json
+	{
+		"label": "PHP: Debug server within docker",
+		"adapter": "Xdebug",
+		"request": "launch",
+		"port": 9003,
+		"pathMappings": {
+			"/var/www/html": "<sources_root_configured_in_haze.toml>",
+			"/var/www/html/apps-extra": "<app_directories_configured_in_haze.toml>",
+		},
+	},
+```
+
+This would have to be adapted for detached instances.
+
+### Debugging all requests
+
+By default, xdebug is configured to only run for requests that containing the
+trigger (e.g. from using the xdebug browser extension, or adding
+`?XDEBUG_SESSION_START=1` to the url).
+
+To enable Xdebug for all requests:
+
+- Uncomment the lines in `haze [cloud-id] edit /config/php.ini`
+- Then run `haze reload [cloud-id]`

From 307dba81ec1ac120a388369d014af401f132a4f9 Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Sun, 20 Sep 2026 19:10:02 +0200
Subject: [PATCH 05/21] put quickstart in readme

---
 README.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/README.md b/README.md
index 7e516d0..8cdadbe 100644
--- a/README.md
+++ b/README.md
@@ -13,3 +13,25 @@ php version, database server, optional s3 or ldap setup and more.
 
 Documentation for haze can be found in the
 [book](https://icewind.codeberg.page/haze/)
+
+## Quickstart
+
+- Grab a binary from the
+  [Codeberg releases](https://codeberg.org/icewind/haze/releases) and place it
+  in your `$PATH`
+
+- Create a file `~/.config/haze/haze.toml` with the following content:
+
+  ```toml
+  sources_root = "/path/to/nextcloud/sources"
+  ```
+
+- Start a basic Nextcloud instance:
+
+  ```bash
+  haze start
+  ```
+
+- Navigate to the address that is provided in the output.
+
+See the [book](https://icewind.codeberg.page/haze/) for more details.

From 51d0279c4185ddbbd60456253c91bcd06979d2c4 Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Wed, 23 Sep 2026 15:10:49 +0200
Subject: [PATCH 06/21] spelling fixes in changelog and book

---
 CHANGELOG.md              | 36 +++++++++----------
 README.md                 |  2 +-
 book/README.md            |  9 +++++
 book/src/README.md        |  6 ++--
 book/src/configuration.md | 73 +++++++++++++++++++--------------------
 book/src/federation.md    |  4 +--
 book/src/proxy/README.md  | 16 ++++-----
 book/src/proxy/dns.md     |  8 ++---
 book/src/proxy/https.md   | 20 +++++------
 book/src/scripts.md       |  4 +--
 book/src/services.md      | 16 ++++-----
 book/src/setup.md         |  4 +--
 book/src/usage.md         |  4 +--
 book/src/xdebug.md        | 10 +++---
 14 files changed, 110 insertions(+), 102 deletions(-)
 create mode 100644 book/README.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d3e4fd8..557b232 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,13 +1,13 @@
 ## Unreleased
 
-- Support having a `#!` inside a haze script to specify the interperter to use
+- Support having a `#!` inside a haze script to specify the interpreter to use
 
 ## 2.4.1
 
 - Show database location on start
 - Direct TLS listening support for the proxy
-- Set `SERVER_NAME` for frankenphp
-- Expose Caddy admin endpoints when using frankenphp
+- Set `SERVER_NAME` for FrankenPHP
+- Expose Caddy admin endpoints when using FrankenPHP
 - Use cron for background jobs
 
 ## 2.4.0
@@ -16,34 +16,34 @@
 - Add option to start an instance with a detached worktree
 - Add "haze scripts" that bundle a setup configuration and script to run in the
   instance
-- Allow specifying phpunit version when running tests
-- Add SAML service using authentik
-- Add OIDC service using authentik
-- Add SCIM service using authentik
+- Add option to specify PHPUnit version when running tests
+- Add SAML service using Authentik
+- Add OIDC service using Authentik
+- Add SCIM service using Authentik
 - Fix using a single word as instance name
 - Fixed cleanup not removing some cache files
-- Remove memory and cpu limits from containers
+- Remove memory and CPU limits from containers
 - Fix max upload size not being set correctly
 
 ## 2.3.0
 
-- Allow execing into service containers
-- Add sftp with key authentication service
-- Fix mysql 8 support
+- Add option to `exec` in service containers
+- Add SFTP with key authentication service
+- Fix MySQL 8 support
 
 ## 2.2.2
 
 - parallelize `git pull`
 - add webhook tester
-- automatically configure ldap when enabled
-- improve compatibility with intergration tests
+- automatically configure LDAP when enabled
+- improve compatibility with integration tests
 - add `php-imagick` module
 
 ## 2.1.1
 
-- Add basic [frankenphp](https://github.com/php/frankenphp) support
+- Add basic [FrankenPHP](https://github.com/php/frankenphp) support
 - Allow running integration tests from (some) apps
-- Support federation with proxy and using 127.0.0.1 as proxy ip
+- Support federation with proxy and using 127.0.0.1 as proxy IP
 - Fix office not working
 - Warn when using out-of-date images.
 
@@ -53,8 +53,8 @@
 - Faster stopping of instances, by @provokateurin
 - Support extra app directories
 - Enable appstore
-- Allow setting config options pre-setup
+- Allow setting configuration options pre-setup
 - Improved access to service containers
 - Add S3 with TLS options
-- Updated php 8.0 and 8.1 images
-- Add php 8.5 support
+- Updated PHP 8.0 and 8.1 images
+- Add PHP 8.5 support
diff --git a/README.md b/README.md
index 8cdadbe..6f17bf1 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ Easy setup and management of Nextcloud test instances using docker
 ## What
 
 `haze` provides an easy way to set up Nextcloud test instances with a choice of
-php version, database server, optional s3 or ldap setup and more.
+PHP version, database server, optional s3 or LDAP setup and more.
 
 ## Documentation
 
diff --git a/book/README.md b/book/README.md
new file mode 100644
index 0000000..0f73f56
--- /dev/null
+++ b/book/README.md
@@ -0,0 +1,9 @@
+## Build requirements
+
+- [mdBook](https://github.com/rust-lang/mdBook)
+
+## Development
+
+```
+mdbook serve
+```
diff --git a/book/src/README.md b/book/src/README.md
index 0ebd550..e5ee49c 100644
--- a/book/src/README.md
+++ b/book/src/README.md
@@ -2,9 +2,9 @@
 
 Hazy with a chance of clouds.
 
-`haze` is a tool that provides provides an easy way to set up Nextcloud test
-instances with a choice of php version, database server, optional s3 or ldap
-setup and much more.
+`haze` is a tool that provides an easy way to set up Nextcloud test instances
+with a choice of PHP version, database server, optional s3 or LDAP setup and
+much more.
 
 ## Quickstart
 
diff --git a/book/src/configuration.md b/book/src/configuration.md
index ab42b18..8ec8d8a 100644
--- a/book/src/configuration.md
+++ b/book/src/configuration.md
@@ -7,13 +7,13 @@ The minimum required configuration needed to get started is just the
 
 The full list of supported options is:
 
-### sources_root
+### `sources_root`
 
-The local path of the nextcloud sources. This options is **required**.
+The local path of the Nextcloud sources. This options is **required**.
 
 Type: string
 
-### app_directories
+### `app_directories`
 
 A list of additional app directory paths to look for apps into
 
@@ -21,7 +21,7 @@ Default `[]`
 
 Type: list of strings
 
-### work_dir
+### `work_dir`
 
 The location where haze keeps it's temporary files and caches
 
@@ -29,16 +29,15 @@ Default: `/tmp/haze`
 
 Type: string
 
-### worktree_dir
+### `worktree_dir`
 
-The location to to store git worktrees when using instances with detached
-sources.
+The location to store git worktrees when using instances with detached sources.
 
 Default: `<work_dir>/worktrees`
 
 Type: string
 
-## auto_setup
+## `auto_setup`
 
 Options for automatically setting up the newly created Nextcloud instance.
 
@@ -61,7 +60,7 @@ config = { "enforce_theme" = "dark" }
 enabled = false
 ```
 
-### auto_setup.enabled
+### `auto_setup.enabled`
 
 Whether to automatically setup Nextcloud inside a created instance.
 
@@ -69,7 +68,7 @@ Default: `true`
 
 Type: boolean
 
-### auto_setup.username
+### `auto_setup.username`
 
 The username to use for the admin account during auto setup.
 
@@ -77,7 +76,7 @@ Default: `admin`
 
 Type: string
 
-### auto_setup.password
+### `auto_setup.password`
 
 The password to use for the admin account during auto setup.
 
@@ -85,7 +84,7 @@ Default: `admin`
 
 Type: string
 
-### auto_setup.enabled_apps
+### `auto_setup.enabled_apps`
 
 Extra apps to enable after auto setup
 
@@ -93,7 +92,7 @@ Default: `[]`
 
 Type: list of strings
 
-### auto_setup.disabled_apps
+### `auto_setup.disabled_apps`
 
 Apps to disabled after auto setup
 
@@ -101,7 +100,7 @@ Default: `[]`
 
 Type: list of strings
 
-### auto_setup.post_setup
+### `auto_setup.post_setup`
 
 Commands to execute after auto setup
 
@@ -109,7 +108,7 @@ Default: `[]`
 
 Type: list of strings
 
-### auto_setup.config
+### `auto_setup.config`
 
 System configuration options to set before auto setup
 
@@ -117,7 +116,7 @@ Default: `{}`
 
 Type: Object
 
-## volume
+## `volume`
 
 Additional files or directories to bind-mount into instances.
 
@@ -139,19 +138,19 @@ target = "/Downloads"
 read_only = true
 ```
 
-### volume.source
+### `volume.source`
 
 The source path on the host
 
 Type: string
 
-### volume.target
+### `volume.target`
 
 The target path inside the container
 
 Type: string
 
-### volume.create
+### `volume.create`
 
 Create the source directory on the host if it doesn't exist already.
 
@@ -159,13 +158,13 @@ Default: `false`
 
 Type: boolean
 
-### volume.read_only
+### `volume.read_only`
 
-Whether to mount the file or directory as read read_only
+Whether to mount the file or directory as read only
 
 Default: `false`
 
-Type: boolean
+Type: `boolean`
 
 ### preset
 
@@ -185,14 +184,14 @@ commands = [
 ]
 ```
 
-### preset.name
+### `preset.name`
 
 The name of the preset, this is used when creating instances to select the
 preset.
 
 Type: string without whitespace
 
-### preset.apps
+### `preset.apps`
 
 A list of apps to enable when the preset is used.
 
@@ -200,7 +199,7 @@ Default: `[]`
 
 Type: list of strings
 
-### preset.commands
+### `preset.commands`
 
 A list of commands to run post-setup when the preset is used.
 
@@ -208,7 +207,7 @@ Default: `[]`
 
 Type: list of strings
 
-## proxy
+## `proxy`
 
 Configuration for the haze proxy. Only required when using the proxy.
 
@@ -221,9 +220,9 @@ cert = "/path/to/haze.test.crt"
 key = "/path/to/haze.test.key"
 ```
 
-### proxy.listen
+### `proxy.listen`
 
-The ip and port or unix socket for the proxy to listen on.
+The IP and port or Unix socket for the proxy to listen on.
 
 **Required** when the proxy is enabled.
 
@@ -239,7 +238,7 @@ listen = "/run/haze/haze.sock"
 listen = "127.0.0.1:8080"
 ```
 
-### proxy.address
+### `proxy.address`
 
 The base domain the proxy is accessible on.
 
@@ -247,26 +246,26 @@ The base domain the proxy is accessible on.
 
 Type: string
 
-### proxy.https
+### `proxy.https`
 
-Whether to enable built-in https support for the proxy.
+Whether to enable built-in HTTPS support for the proxy.
 
 Default: `false`
 
 Type: boolean
 
-### proxy.cert
+### `proxy.cert`
 
-The path of the PEM encoded certificate chain to use for https.
+The path of the PEM encoded certificate chain to use for HTTPS.
 
-**Required** if https is enabled for the proxy.
+**Required** if HTTPS is enabled for the proxy.
 
 Type: string.
 
-### proxy.cert
+### `proxy.cert`
 
-The path of the PEM encoded private key to use for https.
+The path of the PEM encoded private key to use for HTTPS.
 
-**Required** if https is enabled for the proxy.
+**Required** if HTTPS is enabled for the proxy.
 
 Type: string.
diff --git a/book/src/federation.md b/book/src/federation.md
index 20bacd7..23bab7a 100644
--- a/book/src/federation.md
+++ b/book/src/federation.md
@@ -7,7 +7,7 @@ For example, if you have a `rover-beavers` and `splendid-couch` instance, you
 can create a federated share from the `rover-beavers` instance to
 `http://admin@splendid-couch`.
 
-If the proxy is setup with https, you can use https between the instances by
-using the full proxy urls.
+If the proxy is setup with HTTP, you can use HTTP between the instances by using
+the full proxy URLs.
 
 For example sharing to `admin@splendid-couch.haze.example.com`.
diff --git a/book/src/proxy/README.md b/book/src/proxy/README.md
index 5be009b..edc643e 100644
--- a/book/src/proxy/README.md
+++ b/book/src/proxy/README.md
@@ -1,7 +1,7 @@
 # Proxy
 
 By default, instances can be accessed by their IP. In order to get more
-memorable URLs and allow supporting https. haze comes with a builtin reverse
+memorable URLs and allow supporting HTTPS. haze comes with a builtin reverse
 proxy to allow using a wildcard domain.
 
 ## Setup
@@ -10,17 +10,17 @@ proxy to allow using a wildcard domain.
   `haze.example.com` pointing to your development machine.
 - Set the `proxy` configuration with your domain and desired listen endpoint.
 - Set up a service to run `haze proxy` in the background as your own user. A
-  systemd user service is recommended (see
+  SystemD user service is recommended (see
   [haze.service](<[./haze.service](https://codeberg.org/icewind/haze/src/branch/main/haze.service)>)
   for an example).
 - If you're already running a reverse proxy, configure your reverse proxy of
   choice to proxy `*.haze.example.com` and `haze.example.com` to the proxy's
   listen endpoint.
-- (Optionally) [setup https](./https.html) for the proxy.
+- (Optionally) [setup HTTPS](./https.html) for the proxy.
 
 ### Configuration
 
-Add the following configuration to the `haze.toml` config file:
+Add the following configuration to the `haze.toml` configuration file:
 
 ```toml
 [proxy]
@@ -34,13 +34,13 @@ listen = "127.0.0.1:8080" # the port+ip to listen on
 If you have no other http(s) servers on your development machine, you can setup
 things without a reverse proxy.
 
-Simply configure the proxy to listen on port `80` (or `443` when using http).
+Simply configure the proxy to listen on port `80` (or `443` when using HTTPS).
 
 Binding to port 80 or443 as a regular user requires either giving the haze
 binary the `net_bind_service` capability with
 `sudo setcap cap_net_bind_service=+ep $(which haze)` (this will have to be done
-every time your upgrade haze) or configure your system to allow unpriviled users
-to bind on the low port numbers. Using
+every time your upgrade haze) or configure your system to allow unprivileged
+users to bind on the low port numbers. Using
 `sysctl net.ipv4.ip_unprivileged_port_start=80` and writing
 
 ```
@@ -56,7 +56,7 @@ probably want to setup a reverse proxy to allow them to all be served on your
 machine.
 
 The setup for this will depend on your reverse proxy of the choice, the
-following example config is for `nginx`.
+following example configuration is for `nginx`.
 
 ```nginx
 upstream haze-handler {
diff --git a/book/src/proxy/dns.md b/book/src/proxy/dns.md
index c0dc85d..eec3413 100644
--- a/book/src/proxy/dns.md
+++ b/book/src/proxy/dns.md
@@ -1,12 +1,12 @@
 # DNS
 
-Since the domain name used for the instance is dynamic, a wildcard dns record is
+Since the domain name used for the instance is dynamic, a wildcard DNS record is
 required.
 
 ## With your domain's DNS provider
 
 If you own a domain you would like to use, you can create a wildcard domain
-withing the DNS settings of your DNS provider. For example creating a record an
+within the DNS settings of your DNS provider. For example creating a record an
 `A` record for `*.haze.example.com` with a value of `127.0.0.1` and a similar
 one for `haze.example.com`.
 
@@ -15,8 +15,8 @@ one for `haze.example.com`.
 If you do not own a "real" domain for using with haze, you can setup `dnsmasq`
 locally to achieve the same goal instead.
 
-How to install and enable `dnsmasq` will depend on your distro of choice and
-should be documented by it's documentation.
+How to install and enable `dnsmasq` will depend on your Linux distribution of
+choice and should be documented by it's documentation.
 
 Once setup, a configuration line like
 
diff --git a/book/src/proxy/https.md b/book/src/proxy/https.md
index 0acd6c1..6369030 100644
--- a/book/src/proxy/https.md
+++ b/book/src/proxy/https.md
@@ -1,10 +1,10 @@
 # HTTPS
 
-The proxy can be setup to enable using https to access the running instances.
-Besides the warm and fuzy feeling of knowing that nobody can snoop on the trafic
-that is happening completely local inside your machine. Accessing the page over
-https is required for some javascript features (such as service workers), as
-they are only available in "secure contexts".
+The proxy can be setup to enable using HTTPS to access the running instances.
+Besides the warm and fuzzy feeling of knowing that nobody can snoop on the
+traffic that is happening completely local inside your machine. Accessing the
+page over HTTPS is required for some JavaScript features (such as service
+workers), as they are only available in "secure contexts".
 
 ## Getting a wildcard certificate
 
@@ -26,18 +26,18 @@ lists some DNS providers and supported ACME clients.
 You can also create a self-signed wildcard certificate using a tool like
 `mkcert`. This certificate will not be trusted by your browser and tools like
 curl, but you can add manually add it to the trusted certificates on your
-system, or bypass the certficate warning in the browser/curl every time.
+system, or bypass the certificates warning in the browser/curl every time.
 
 ```bash
 # Generate local wildcard certificate
-mkcert -cert-file <path-to-your-certificats>haze.example.com.crt -key-file <path-to-your-certificats>haze.example.com.key '*.haze.example.com'
+mkcert -cert-file <path-to-your-certificates>haze.example.com.crt -key-file <path-to-your-certificates>haze.example.com.key '*.haze.example.com'
 ```
 
 ## Using the certificate
 
 ### Without reverse proxy
 
-The haze proxy can serve over https directly, to enable that add the following
+The haze proxy can serve over HTTPS directly, to enable that add the following
 to the `[proxy]` section of your `haze.toml`.
 
 ```toml
@@ -64,8 +64,8 @@ server {
     http2 on;
     server_name *.haze.example.com;
 
-    ssl_certificate     <path-to-your-certificats>/haze.example.com.crt;
-    ssl_certificate_key <path-to-your-certificats>/haze.example.com.key;
+    ssl_certificate     <path-to-your-certificates>/haze.example.com.crt;
+    ssl_certificate_key <path-to-your-certificates>/haze.example.com.key;
 
     location / {
             proxy_pass http://haze-handler;
diff --git a/book/src/scripts.md b/book/src/scripts.md
index 00fa6f8..b32c3c8 100644
--- a/book/src/scripts.md
+++ b/book/src/scripts.md
@@ -14,7 +14,7 @@ A script contains of 3 paths
    interpreter, e.g. `#! haze shell pgsql s3`
 3. The rest that is ran as a script inside the created instance.
 
-The first sheband is set, the script can be ran directly. Else it needs to be
+The first shebang is set, the script can be ran directly. Else it needs to be
 run with `haze script [path-to-script]`.
 
 For example, the following script will create an instance with `postgresql` and
@@ -49,7 +49,7 @@ will. The intended use case for this is creating more complex instances without
 having to configure a dedicated preset.
 
 The script mode is determined based on the shebang line. The mode set in a
-script can be overriden by running the script with
+script can be overridden by running the script with
 `haze script [shell|start] path-to-script.sh`.
 
 ## Using different interpreters
diff --git a/book/src/services.md b/book/src/services.md
index 42ea93e..16c41e8 100644
--- a/book/src/services.md
+++ b/book/src/services.md
@@ -8,20 +8,20 @@ The following service options are available:
   - `s3mb`: enable multi-bucket S3 setup.
   - `s3m`: enable multi-instance S3 setup.
 - `ldap`: set up an LDAP server.
-- `saml`: set up authentik as a SAML IDP.
-- `oidc`: set up authentik as an OIDC IDP.
-- `scim`: set up authentik as a SCIM server.
+- `saml`: set up Authentik as a SAML IDP.
+- `oidc`: set up Authentik as an OIDC IDP.
+- `scim`: set up Authentik as a SCIM server.
 - `office`: set up a Nextcloud Office server.
-- `onlyoffice` setup an onlyoffice document server.
+- `onlyoffice` setup an OnlyOffice document server.
 - `push` set up [client push](https://github.com/nextcloud/notify_push).
 - `smb`: set up a samba server for external storage use.
 - `dav`: set up a WebDAV server for external storage use.
 - `sftp`: set up a SFTP server for external storage use.
 - `sftp-key`: set up a SFTP server for external storage use with public key
   authentication.
-- `kaspersky`: set up a kaspersky scan engine server in http mode. ( Requires
+- `kaspersky`: set up a Kaspersky scan engine server in HTTP mode. ( Requires
   [manually setting up the image](https://github.com/icewind1991/kaspersky-docker))
-- `kaspersky-icap`: setup a kaspersky scan engine server in ICAP mode.
+- `kaspersky-icap`: setup a Kaspersky scan engine server in ICAP mode.
 - `clamav`: set up a local clam av scanner in executable mode.
 - `clamav-socket`: set up a clam av scanner in socket mode.
 - `clamav-icap`: set up a clam av scanner in ICAP mode.
@@ -33,8 +33,8 @@ The following service options are available:
   configure it the mail server.
 - `webhook` start a
   [webhook tester](https://github.com/tarampampam/webhook-tester)
-- `redis`: start a separate container for redis.
-- `redis-tls`: connect to redis over TLS.
+- `redis`: start a separate container for Redis.
+- `redis-tls`: connect to Redis over TLS.
 - `<path to app.tar.gz>`: by specifying the path to an app package this package
   will be extracted into the apps. directory of the new instance (overwriting
   any existing app code). This can be used to quickly test a packaged app.
diff --git a/book/src/setup.md b/book/src/setup.md
index 8ce4385..420eaee 100644
--- a/book/src/setup.md
+++ b/book/src/setup.md
@@ -5,7 +5,7 @@
 - Docker
 
 haze is built around docker containers and manages containers using the docker
-socket. Using podman with docker compatibility might also work, but is untested.
+socket. Using Podman with docker compatibility might also work, but is untested.
 
 ## Installation
 
@@ -13,7 +13,7 @@ socket. Using podman with docker compatibility might also work, but is untested.
   [Codeberg releases](https://codeberg.org/icewind/haze/releases) and place it
   in your `$PATH`
 
-## Config
+## Configuration
 
 Create a file `~/.config/haze/haze.toml` with the following options:
 
diff --git a/book/src/usage.md b/book/src/usage.md
index f8a23f0..063bc47 100644
--- a/book/src/usage.md
+++ b/book/src/usage.md
@@ -159,13 +159,13 @@ haze [match] edit <path>
 Where `<path>` is the path of a file inside the container, for example
 `config/config.php`.
 
-### Reload the php config of an instance
+### Reload the PHP configuration of an instance
 
 ```bash
 haze [match] reload
 ```
 
-The php configuration can edit changed with `haze edit  /config/php.ini`
+The PHP configuration can edit changed with `haze edit  /config/php.ini`
 
 ### Run a command with instance environment variables set
 
diff --git a/book/src/xdebug.md b/book/src/xdebug.md
index 0a36bbe..11a6089 100644
--- a/book/src/xdebug.md
+++ b/book/src/xdebug.md
@@ -2,7 +2,7 @@
 
 To use Xdebug running in a haze instance with your IDE for debugging, you need
 to tell you IDE how to properly map the path from the container to the host. The
-IDE debugger config usually looks like:
+IDE debugger configuration usually looks like:
 
 ```json
 	{
@@ -21,11 +21,11 @@ This would have to be adapted for detached instances.
 
 ### Debugging all requests
 
-By default, xdebug is configured to only run for requests that containing the
-trigger (e.g. from using the xdebug browser extension, or adding
-`?XDEBUG_SESSION_START=1` to the url).
+By default, Xdebug is configured to only run for requests that containing the
+trigger (e.g. from using the Xdebug browser extension, or adding
+`?XDEBUG_SESSION_START=1` to the URL).
 
 To enable Xdebug for all requests:
 
-- Uncomment the lines in `haze [cloud-id] edit /config/php.ini`
+- Un-comment the lines in `haze [cloud-id] edit /config/php.ini`
 - Then run `haze reload [cloud-id]`

From 99c3285f073160810db69182485553373bb6a0c6 Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Wed, 23 Sep 2026 15:10:49 +0200
Subject: [PATCH 07/21] spelling fixes in src

---
 src/args.rs                  |  2 +-
 src/cloud.rs                 | 21 +++++++++++----------
 src/config.rs                |  4 ++--
 src/exec.rs                  |  2 +-
 src/git.rs                   |  4 ++--
 src/mapping.rs               |  2 +-
 src/service.rs               | 30 +++++++++++++++---------------
 src/service/authentik/mod.rs |  2 +-
 src/service/objectstore.rs   | 17 +++--------------
 9 files changed, 37 insertions(+), 47 deletions(-)

diff --git a/src/args.rs b/src/args.rs
index 181db11..7e28603 100644
--- a/src/args.rs
+++ b/src/args.rs
@@ -507,7 +507,7 @@ pub enum HazeCommand {
     /// Edit a file in the instance with $EDITOR on the host
     #[strum(props(Args = "[path] file to edit"))]
     Edit,
-    /// Reload the php configuration in the instance
+    /// Reload the PHP configuration in the instance
     #[strum(props(
         Details = "note: you can overwrite <yellow>php.ini</yellow> settings with <literal>haze</literal> <arg>[filter]</arg> <literal>edit  /config/php.ini</literal>"
     ))]
diff --git a/src/cloud.rs b/src/cloud.rs
index 6932d00..cbb8b5c 100644
--- a/src/cloud.rs
+++ b/src/cloud.rs
@@ -717,9 +717,9 @@ impl Cloud {
                 .await
                 .into_diagnostic()
                 .wrap_err("Failed to remove work directory")
-            {
-                eprintln!("{}", e);
-            }
+        {
+            eprintln!("{}", e);
+        }
 
         remove_worktrees_for_instance(config, &self.id).await?;
 
@@ -808,14 +808,15 @@ impl Cloud {
                 && match filter.as_ref() {
                     Some(filter) => cloud_id.contains(filter),
                     None => true,
-                } {
-                    let entry = containers_by_id.entry(cloud_id.to_string()).or_default();
-                    if labels.get("haze-type").map(String::as_str) == Some("cloud") {
-                        entry.0 = Some(container);
-                    } else {
-                        entry.1.push(container)
-                    }
                 }
+            {
+                let entry = containers_by_id.entry(cloud_id.to_string()).or_default();
+                if labels.get("haze-type").map(String::as_str) == Some("cloud") {
+                    entry.0 = Some(container);
+                } else {
+                    entry.1.push(container)
+                }
+            }
         }
 
         let mut sortable_containers: Vec<_> = containers_by_id
diff --git a/src/config.rs b/src/config.rs
index 8dfd52c..0b6355f 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -7,8 +7,8 @@ use std::convert::TryFrom;
 use std::env::home_dir;
 use std::fs::read_to_string;
 use std::net::IpAddr;
-use toml::map::Map;
 use toml::Value;
+use toml::map::Map;
 
 #[derive(Debug, Deserialize, Default)]
 #[serde(from = "RawHazeConfig")]
@@ -208,7 +208,7 @@ pub struct ProxyConfig {
 }
 
 impl ProxyConfig {
-    /// Get a public address for a service, either with direct ip or through the proxy
+    /// Get a public address for a service, either with direct IP or through the proxy
     pub fn addr(&self, id: &str, ip: IpAddr) -> String {
         let clean_id = id.strip_prefix("haze-").unwrap_or(id);
         match (&self.address, self.https) {
diff --git a/src/exec.rs b/src/exec.rs
index f077329..f206a32 100644
--- a/src/exec.rs
+++ b/src/exec.rs
@@ -75,7 +75,7 @@ pub async fn exec_tty<S1: AsRef<str>, S2: Into<String>, Env: Into<String>>(
             }
         });
 
-        // set stdout in raw mode so we can do tty stuff
+        // set stdout in raw mode so we can do TTY stuff
         let mut stdout = stdout.lock().into_raw_mode().into_diagnostic()?;
 
         // pipe docker exec output into stdout
diff --git a/src/git.rs b/src/git.rs
index 2469de5..53b49b2 100644
--- a/src/git.rs
+++ b/src/git.rs
@@ -1,12 +1,12 @@
-use crate::config::HazeConfig;
 use crate::Result;
+use crate::config::HazeConfig;
 use camino::{Utf8Path, Utf8PathBuf};
 use git2::build::CheckoutBuilder;
 use git2::{Branch, BranchType, Repository, RepositoryState};
 use indicatif::{MultiProgress, ProgressBar, ProgressStyle};
 use miette::{Context, IntoDiagnostic, Report};
-use rayon::iter::{IntoParallelRefIterator, ParallelIterator};
 use rayon::ThreadPoolBuilder;
+use rayon::iter::{IntoParallelRefIterator, ParallelIterator};
 use std::fs::read_dir;
 use std::iter::once;
 use std::path::PathBuf;
diff --git a/src/mapping.rs b/src/mapping.rs
index 6291c53..30b82ef 100644
--- a/src/mapping.rs
+++ b/src/mapping.rs
@@ -107,7 +107,7 @@ impl<'a> Mapping<'a> {
                 .wrap_err("Failed to create source file")?,
         }
 
-        // For worktrees, pre-create mountpoints within /var/www/html to prevent docker from creating them as root.
+        // For worktrees, pre-create mount points within /var/www/html to prevent docker from creating them as root.
         if self.target.starts_with("/var/www/html") {
             let local_target = source_root.join(
                 self.target
diff --git a/src/service.rs b/src/service.rs
index 42646fb..da3377a 100644
--- a/src/service.rs
+++ b/src/service.rs
@@ -206,7 +206,7 @@ pub trait ServiceTrait {
         "bash"
     }
 
-    /// Allow services to delay the completion of the `start` command untill they are fully setup
+    /// Allow services to delay the completion of the `start` command until they are fully setup
     ///
     /// This is not for services which are critical for the running of the instance (use `is_healthy` for that)
     /// But instead for cases where the instance is mostly usable, but might have some missing features
@@ -264,18 +264,18 @@ pub enum ServiceType {
     S3mb,
     /// Azure Primary storage and external storage
     Azure,
-    /// Ldap user backend
+    /// LDAP user backend
     Ldap,
-    /// Ldap admin interface
+    /// LDAP admin interface
     LdapAdmin,
     /// OnlyOffice
     #[strum(serialize = "onlyoffice", serialize = "only-office")]
     OnlyOffice,
-    /// Libre office online
+    /// LibreOffice online
     Office,
     /// notify_push
     Push,
-    /// Smb external storage
+    /// SMB external storage
     Smb,
     /// Database sharding
     #[strum(serialize = "sharding", serialize = "sharded")]
@@ -293,17 +293,17 @@ pub enum ServiceType {
     SingleShard,
     /// WebDav external storage
     Dav,
-    /// Sftp external storage
+    /// SFTP external storage
     Sftp,
-    /// Sftp external storage with public key authentication
+    /// SFTP external storage with public key authentication
     SftpKey,
     /// ownCloud instance for migration
     Oc,
     /// Imaginary for preview generation
     Imaginary,
-    /// Kaspersky antivirus in http mode
+    /// Kaspersky antivirus in HTTP mode
     Kaspersky,
-    /// Kaspersky antivirus in icap mode
+    /// Kaspersky antivirus in ICAP mode
     KasperskyIcap,
     /// Kaspersky antivirus in local binary
     #[strum(serialize = "clamav", serialize = "clam")]
@@ -314,23 +314,23 @@ pub enum ServiceType {
     /// Kaspersky antivirus in local socket mode
     #[strum(serialize = "clamav-socket", serialize = "clam-socket")]
     ClamAvSocket,
-    /// Kaspersky antivirus in icap mode
+    /// Kaspersky antivirus in ICAP mode
     #[strum(serialize = "clamav-icap", serialize = "clam-icap")]
     ClamAvIcap,
-    /// Kaspersky antivirus in icap mode with TLS
+    /// Kaspersky antivirus in ICAP mode with TLS
     #[strum(serialize = "clamav-icap-tls", serialize = "clam-icap-tls")]
     ClamAvIcapTls,
     /// Mail server
     Mail,
-    /// External redis instance
+    /// External Redis instance
     Redis,
-    /// External redis instance with TLS
+    /// External Redis instance with TLS
     RedisTls,
     /// Use FrankenPHP instead of PHP-FPM
     FrankenPhp,
     /// Webhook test listener
     Webhook,
-    /// Enable DB partitioning for mariadb
+    /// Enable DB partitioning for MariaDB
     Partitioning,
     /// Authentik identity provider
     Authentik,
@@ -465,7 +465,7 @@ impl Service {
 }
 
 // Remove duplicate services.
-// Useful for Authentik as it is needed by saml and oidc.
+// Useful for Authentik as it is needed by SAML and OIDC.
 pub fn deduplicate_services(services: impl IntoIterator<Item = Service>) -> Vec<Service> {
     let mut collected = Vec::new();
     for service in services {
diff --git a/src/service/authentik/mod.rs b/src/service/authentik/mod.rs
index 86714f1..0703832 100644
--- a/src/service/authentik/mod.rs
+++ b/src/service/authentik/mod.rs
@@ -122,7 +122,7 @@ async fn spawn_authentik(
     if !config.proxy.address.is_empty() {
         let url = config.proxy.addr_with_port(
             &container_name(cloud_id, "server"),
-            IpAddr::V4(Ipv4Addr::LOCALHOST), // ip arg is unused when a proxy is configured
+            IpAddr::V4(Ipv4Addr::LOCALHOST), // IP argument is unused when a proxy is configured
             AUTHENTIK_PORT,
         );
         env.push(format!("AUTHENTIK_WEB__BASE_URL={url}"));
diff --git a/src/service/objectstore.rs b/src/service/objectstore.rs
index 20e586c..64452c5 100644
--- a/src/service/objectstore.rs
+++ b/src/service/objectstore.rs
@@ -1,14 +1,14 @@
+use crate::Result;
 use crate::cloud::CloudOptions;
 use crate::config::HazeConfig;
 use crate::exec::exec;
 use crate::image::pull_image;
-use crate::service::{split_cmnd, ServiceTrait};
-use crate::Result;
+use crate::service::{ServiceTrait, split_cmnd};
+use bollard::Docker;
 use bollard::models::{
     ContainerCreateBody, ContainerState, EndpointSettings, HostConfig, NetworkingConfig,
 };
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use maplit::hashmap;
 use miette::{IntoDiagnostic, WrapErr};
 use serde_json::Value;
@@ -260,17 +260,6 @@ impl ServiceTrait for ObjectStore {
                 split_cmnd("occ files_external:config 1 secret minio123"),
                 split_cmnd("mc alias set s3 http://s3:9000 minio minio123"),
             ]),
-            // ObjectStore::S3s => Ok(vec![
-            //     "occ files_external:create s3 amazons3 amazons3::accesskey".into(),
-            //     "occ files_external:config 1 bucket ext".into(),
-            //     "occ files_external:config 1 hostname s3".into(),
-            //     "occ files_external:config 1 port 9000".into(),
-            //     "occ files_external:config 1 use_ssl true".into(),
-            //     "occ files_external:config 1 use_path_style true".into(),
-            //     "occ files_external:config 1 key minio".into(),
-            //     "occ files_external:config 1 secret minio123".into(),
-            //     "mc alias set s3 https://s3:9000 minio minio123".into(),
-            // ]),
             _ => Ok(Vec::new()),
         }
     }

From 5bab1b89bb45cd99c5319748b5c5d387c7c0ffe9 Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Wed, 23 Sep 2026 15:10:49 +0200
Subject: [PATCH 08/21] add basic vale config

---
 .gitignore                                |  2 ++
 .vale.ini                                 | 13 ++++++++++++
 .vale/config/vocabularies/haze/accept.txt | 25 +++++++++++++++++++++++
 flake.nix                                 |  1 +
 4 files changed, 41 insertions(+)
 create mode 100644 .vale.ini
 create mode 100644 .vale/config/vocabularies/haze/accept.txt

diff --git a/.gitignore b/.gitignore
index 512d7c7..87a4f44 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,5 @@
 .direnv
 .env
 result
+.vale/*
+!.vale/config
diff --git a/.vale.ini b/.vale.ini
new file mode 100644
index 0000000..1f31616
--- /dev/null
+++ b/.vale.ini
@@ -0,0 +1,13 @@
+StylesPath = .vale
+MinAlertLevel = suggestion
+Vocab = haze
+
+[formats]
+mdx = md
+
+[*]
+BasedOnStyles = Vale
+
+[*.{md,mdx}]
+BasedOnStyles = Vale
+Microsoft.Contractions = NO
diff --git a/.vale/config/vocabularies/haze/accept.txt b/.vale/config/vocabularies/haze/accept.txt
new file mode 100644
index 0000000..4cd11e4
--- /dev/null
+++ b/.vale/config/vocabularies/haze/accept.txt
@@ -0,0 +1,25 @@
+Nextcloud
+ownCloud
+appstore
+Authentik
+Caddy
+cron
+FrankenPHP
+PHPUnit
+mdBook
+boolean
+Codeberg
+Kaspersky
+Redis
+Podman
+Xdebug
+occ
+dnsmasq
+notify_push
+sharding
+tokio
+worktree
+worktrees
+config
+stdin
+stdout
diff --git a/flake.nix b/flake.nix
index b9efaaa..eef5aba 100644
--- a/flake.nix
+++ b/flake.nix
@@ -65,6 +65,7 @@
           skopeo
           dive
           mdbook
+          vale
         ];
 
       homeModules = {

From 029f26bda6194574af8d79cd74fbc8662647f3bc Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Wed, 23 Sep 2026 15:35:55 +0200
Subject: [PATCH 09/21] only run book PR preview if the book changed

---
 .forgejo/workflows/book-pr.yaml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.forgejo/workflows/book-pr.yaml b/.forgejo/workflows/book-pr.yaml
index cde53e6..7f978d1 100644
--- a/.forgejo/workflows/book-pr.yaml
+++ b/.forgejo/workflows/book-pr.yaml
@@ -6,6 +6,9 @@ on:
       - opened
       - reopened
       - synchronize
+    paths:
+      - ".forgejo/workflows/book-pr.yaml"
+      - "book/**"
 
 concurrency:
   group: page-preview

From eac08ac64cb1412ed33361f93e850ddd80562ebf Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Wed, 23 Sep 2026 15:41:05 +0200
Subject: [PATCH 10/21] fmt

---
 src/config.rs | 2 +-
 src/git.rs    | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/config.rs b/src/config.rs
index 0b6355f..64e140d 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -7,8 +7,8 @@ use std::convert::TryFrom;
 use std::env::home_dir;
 use std::fs::read_to_string;
 use std::net::IpAddr;
-use toml::Value;
 use toml::map::Map;
+use toml::Value;
 
 #[derive(Debug, Deserialize, Default)]
 #[serde(from = "RawHazeConfig")]
diff --git a/src/git.rs b/src/git.rs
index 53b49b2..2469de5 100644
--- a/src/git.rs
+++ b/src/git.rs
@@ -1,12 +1,12 @@
-use crate::Result;
 use crate::config::HazeConfig;
+use crate::Result;
 use camino::{Utf8Path, Utf8PathBuf};
 use git2::build::CheckoutBuilder;
 use git2::{Branch, BranchType, Repository, RepositoryState};
 use indicatif::{MultiProgress, ProgressBar, ProgressStyle};
 use miette::{Context, IntoDiagnostic, Report};
-use rayon::ThreadPoolBuilder;
 use rayon::iter::{IntoParallelRefIterator, ParallelIterator};
+use rayon::ThreadPoolBuilder;
 use std::fs::read_dir;
 use std::iter::once;
 use std::path::PathBuf;

From 6d8e026ec4f779ba207b58c5f098656eacf3b2cf Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Wed, 23 Sep 2026 15:41:05 +0200
Subject: [PATCH 11/21] add vale to flake checks

---
 flake.nix | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/flake.nix b/flake.nix
index eef5aba..5308a7a 100644
--- a/flake.nix
+++ b/flake.nix
@@ -68,6 +68,10 @@
           vale
         ];
 
+      checks = {
+        vale = {vale, ...}: "${vale}/bin/vale src/ book/src/ CHANGELOG.md README.md book/README.md";
+      };
+
       homeModules = {
         default = {
           pkgs,

From 0a74daf4fdeea116bbabdf6b954b5ac4a1a22b0f Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Sat, 26 Sep 2026 01:18:47 +0200
Subject: [PATCH 12/21] flake update:

---
 flake.lock | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/flake.lock b/flake.lock
index 1603da3..c08fe28 100644
--- a/flake.lock
+++ b/flake.lock
@@ -38,11 +38,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1789408620,
-        "narHash": "sha256-ZymN+wNsIs0rMw9ydP5Yp5GIUKZoA8b8IDsCnz30VfE=",
+        "lastModified": 1790013821,
+        "narHash": "sha256-0OrPYAGfGF5BGPPtzEzeMNhNcvGyQBWRRfvcE0xY750=",
         "owner": "nix-community",
         "repo": "flakelight",
-        "rev": "1d9163b9abf315129e912f3157e03b265f104838",
+        "rev": "a57b0af9d0da4c5389ccf19e310daf0e5518312a",
         "type": "github"
       },
       "original": {
@@ -80,11 +80,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1788758950,
-        "narHash": "sha256-b3zONUcYXZHeoeYwDZdSDCzMj0s6ubmD6NT3D7sS+jU=",
+        "lastModified": 1790258944,
+        "narHash": "sha256-3bwtAiifsfGXVLIopwhJ/RNIkDABcLg6DxnlbaiE2xc=",
         "owner": "nlewo",
         "repo": "nix2container",
-        "rev": "b6ac40ef110c12ab1651fce5ea563f7837236439",
+        "rev": "08d8889b6d2528acfce6e2616b0cd41983dedb02",
         "type": "github"
       },
       "original": {
@@ -95,11 +95,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1789749394,
-        "narHash": "sha256-cFTsMQz8Hzn8MT49oaeLSHg62tE86NykugCWkeM2ypk=",
+        "lastModified": 1790218706,
+        "narHash": "sha256-6e4Na3z008XpdVyOXgfasXIn1aN+z8AXFG+jXdQSyuI=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "cf9d2fb3e50fa1cd5114c47505ea9177f7ff5f49",
+        "rev": "c508844df6c28fa6dabc1b6af70f3ccbd65c5201",
         "type": "github"
       },
       "original": {
@@ -110,11 +110,11 @@
     },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1788953386,
-        "narHash": "sha256-dIqD4NX3Uldk29CBqKt9dRdSxh/+Ba8lVPu2xEsLTJo=",
+        "lastModified": 1789370336,
+        "narHash": "sha256-6RSEDHIWQtesQKWSu5qRai8L2h4KgCgMEfJHstW99G4=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "19a27817106f9449970edb3a398ab5349666466f",
+        "rev": "c7def046b9a883d46974757852106483d741586f",
         "type": "github"
       },
       "original": {
@@ -130,11 +130,11 @@
         "nixpkgs": "nixpkgs_2"
       },
       "locked": {
-        "lastModified": 1789262846,
-        "narHash": "sha256-IrgEYbj5LY4EskP8lvYRexPp0jI2KBy3NJZBBgSqrpg=",
+        "lastModified": 1790337121,
+        "narHash": "sha256-phqixEWMLjvdlUpo6uBCYbVYuGCk0FjiIoC0zPTCu3c=",
         "owner": "fossar",
         "repo": "nix-phps",
-        "rev": "af15d3f84460bfa8cd15278795347e4661e0a199",
+        "rev": "2a7ca28d4634890d2b07a63847cd6d26da9c2cb4",
         "type": "github"
       },
       "original": {

From 515fc60f490189659b784e5bd8c131831b0575c5 Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Sun, 27 Sep 2026 17:28:59 +0200
Subject: [PATCH 13/21] add database webui

---
 CHANGELOG.md          |   1 +
 src/cloud.rs          |  11 +++-
 src/database.rs       |  39 ++++++++++++-
 src/help.rs           |  16 ++---
 src/main.rs           |   6 +-
 src/proxy.rs          |  19 +++---
 src/service.rs        |  10 ++++
 src/service/dbgate.rs | 133 ++++++++++++++++++++++++++++++++++++++++++
 8 files changed, 213 insertions(+), 22 deletions(-)
 create mode 100644 src/service/dbgate.rs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 557b232..ed38d46 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,7 @@
 ## Unreleased
 
 - Support having a `#!` inside a haze script to specify the interpreter to use
+- Add webui for accessing the database.
 
 ## 2.4.1
 
diff --git a/src/cloud.rs b/src/cloud.rs
index cbb8b5c..0928e33 100644
--- a/src/cloud.rs
+++ b/src/cloud.rs
@@ -4,9 +4,9 @@ use crate::exec::{ExitCode, exec, exec_io, exec_tty};
 use crate::git::{create_worktree, find_app_repo, init_submodules, remove_worktree};
 use crate::mapping::{Mapping, for_config};
 use crate::php::PhpVersion;
-use crate::service::Service;
 use crate::service::ServiceTrait;
 use crate::service::deduplicate_services;
+use crate::service::{DbGate, Service};
 use crate::sources::download_nc;
 use bollard::Docker;
 use bollard::config::NetworkCreateRequest;
@@ -347,6 +347,8 @@ fn test_option_parse() {
     );
 }
 
+static DEFAULT_SERVICES: &[Service] = &[Service::DbGate(DbGate)];
+
 #[derive(Debug, Clone)]
 pub struct Cloud {
     pub id: String,
@@ -539,6 +541,8 @@ impl Cloud {
             options
                 .services
                 .iter()
+                .filter(|service| !service.hidden())
+                .chain(DEFAULT_SERVICES.into_iter())
                 .map(|service| service.spawn(docker, &id, &network, config, &options)),
         )
         .await?;
@@ -970,7 +974,10 @@ impl Cloud {
     }
 
     pub fn services(&self) -> impl Iterator<Item = &Service> {
-        self.options.services.iter()
+        self.options
+            .services
+            .iter()
+            .chain(DEFAULT_SERVICES.into_iter())
     }
 
     pub fn db(&self) -> &Database {
diff --git a/src/database.rs b/src/database.rs
index 7f943bd..a38da00 100644
--- a/src/database.rs
+++ b/src/database.rs
@@ -1,13 +1,13 @@
 use crate::config::HazeConfig;
-use crate::exec::{exec, exec_tty, ExitCode};
+use crate::exec::{ExitCode, exec, exec_tty};
 use crate::image::pull_image;
+use bollard::Docker;
 use bollard::config::ContainerCreateBody;
 use bollard::models::{EndpointSettings, HostConfig, NetworkingConfig};
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use maplit::hashmap;
 use miette::{IntoDiagnostic, Report, Result, WrapErr};
-use std::io::{stdout, Stdout};
+use std::io::{Stdout, stdout};
 use std::net::{IpAddr, Ipv4Addr};
 use std::str::FromStr;
 use std::time::Duration;
@@ -32,6 +32,39 @@ impl DatabaseFamily {
     pub fn name(&self) -> &'static str {
         self.into()
     }
+
+    pub fn db_gate_driver(&self) -> &'static str {
+        match self {
+            DatabaseFamily::Mysql => "mysql@dbgate-plugin-mysql",
+            DatabaseFamily::MariaDB => "mariadb@dbgate-plugin-mysql",
+            DatabaseFamily::Postgres => "postgres@dbgate-plugin-postgres",
+            DatabaseFamily::Oracle => "oracle@dbgate-plugin-oracle",
+            DatabaseFamily::Sqlite => "sqlite@dbgate-plugin-sqlite",
+        }
+    }
+
+    pub fn port(&self) -> u16 {
+        match self {
+            DatabaseFamily::Mysql | DatabaseFamily::MariaDB => 3306,
+            DatabaseFamily::Postgres => 5432,
+            DatabaseFamily::Oracle => 1521,
+            DatabaseFamily::Sqlite => 0,
+        }
+    }
+
+    pub fn username(&self) -> &'static str {
+        match self {
+            DatabaseFamily::Oracle => "system",
+            _ => "haze",
+        }
+    }
+
+    pub fn db(&self) -> &'static str {
+        match self {
+            DatabaseFamily::Oracle => "SYSTEM",
+            _ => "haze",
+        }
+    }
 }
 
 #[derive(Clone, Debug, Eq, PartialEq, Default)]
diff --git a/src/help.rs b/src/help.rs
index 566bff7..29c09ff 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -2,8 +2,8 @@ use crate::args::{HazeCommand, SubCommand};
 use crate::database::DatabaseFamily;
 use crate::php::PhpVersion;
 use crate::service::ServiceType;
-use owo_colors::colors::xterm::Gray;
 use owo_colors::OwoColorize;
+use owo_colors::colors::xterm::Gray;
 use strum::{EnumMessage, EnumProperty, IntoEnumIterator};
 
 pub fn help(command: Option<&dyn SubCommand>) {
@@ -151,12 +151,14 @@ fn subcommand_help(command: &dyn SubCommand) {
         for service in ServiceType::iter() {
             let service: ServiceType = service;
             let service_str: &'static str = service.into();
-            println!(
-                "  {}{}  {}",
-                service.blue(),
-                " ".repeat(max_service_len - service_str.len()),
-                service.get_documentation().unwrap_or_default(),
-            );
+            if let Some(doc) = service.get_documentation() {
+                println!(
+                    "  {}{}  {}",
+                    service.blue(),
+                    " ".repeat(max_service_len - service_str.len()),
+                    doc,
+                );
+            }
         }
         println!();
 
diff --git a/src/main.rs b/src/main.rs
index 2c01ce4..d425a73 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -129,7 +129,11 @@ async fn main() -> Result<ExitCode> {
         HazeArgs::List { filter } => {
             let list = Cloud::list(&docker, filter, &config).await?;
             for cloud in list {
-                let mut services: Vec<_> = cloud.services().map(Service::name).collect();
+                let mut services: Vec<_> = cloud
+                    .services()
+                    .filter(|service| !service.hidden())
+                    .map(Service::name)
+                    .collect();
                 services.push(cloud.db().name());
                 let services = services.join(", ");
                 let pin = if cloud.is_pinned(&docker).await.unwrap_or(false) {
diff --git a/src/proxy.rs b/src/proxy.rs
index 2223299..cc6f6ea 100644
--- a/src/proxy.rs
+++ b/src/proxy.rs
@@ -1,8 +1,8 @@
-use crate::service::{ServiceTrait, ServiceType};
 use crate::Result;
+use crate::service::{ServiceTrait, ServiceType};
 use crate::{Cloud, HazeConfig};
-use axum::http::header::HOST;
 use axum::http::HeaderValue;
+use axum::http::header::HOST;
 use axum::{
     body::Body,
     extract::Request,
@@ -10,13 +10,13 @@ use axum::{
 };
 use bollard::Docker;
 use futures_util::StreamExt;
+use hyper::StatusCode;
 use hyper::body::Incoming;
 use hyper::server::conn::http1;
 use hyper::service::service_fn;
-use hyper::StatusCode;
 use hyper_util::rt::TokioIo;
 use hyper_util::{client::legacy::connect::HttpConnector, rt::TokioExecutor};
-use miette::{miette, IntoDiagnostic};
+use miette::{IntoDiagnostic, miette};
 use std::collections::HashMap;
 use std::convert::Infallible;
 use std::fs::{create_dir_all, set_permissions};
@@ -237,10 +237,11 @@ async fn serve(
     } else {
         let listen: PathBuf = listen.into();
         if let Some(parent) = listen.parent()
-            && !parent.exists() {
-                create_dir_all(parent).into_diagnostic()?;
-                set_permissions(parent, PermissionsExt::from_mode(0o755)).into_diagnostic()?;
-            }
+            && !parent.exists()
+        {
+            create_dir_all(parent).into_diagnostic()?;
+            set_permissions(parent, PermissionsExt::from_mode(0o755)).into_diagnostic()?;
+        }
         let _ = tokio::fs::remove_file(&listen).await;
 
         let listener = UnixListener::bind(&listen).unwrap();
@@ -337,7 +338,7 @@ async fn handler(state: AppState, mut req: Request<Incoming>) -> Result<Response
             return Ok(hyper::Response::builder()
                 .status(StatusCode::BAD_REQUEST)
                 .body(e.into())
-                .unwrap())
+                .unwrap());
         }
     };
 
diff --git a/src/service.rs b/src/service.rs
index da3377a..70f4994 100644
--- a/src/service.rs
+++ b/src/service.rs
@@ -1,6 +1,7 @@
 mod authentik;
 mod clam;
 mod dav;
+mod dbgate;
 mod imaginary;
 mod kaspersky;
 mod ldap;
@@ -22,6 +23,7 @@ use crate::config::{HazeConfig, Preset, ProxyConfig};
 pub use crate::service::authentik::{Authentik, AuthentikOidc, AuthentikSaml, AuthentikScim};
 pub use crate::service::clam::{Clam, ClamIcap, ClamIcapTls, ClamSocket};
 use crate::service::dav::Dav;
+pub use crate::service::dbgate::DbGate;
 use crate::service::imaginary::Imaginary;
 use crate::service::kaspersky::{Kaspersky, KasperskyIcap};
 pub use crate::service::ldap::{Ldap, LdapAdmin};
@@ -59,6 +61,10 @@ pub trait ServiceTrait {
         &[]
     }
 
+    fn hidden(&self) -> bool {
+        false
+    }
+
     async fn spawn(
         &self,
         _docker: &Docker,
@@ -340,6 +346,8 @@ pub enum ServiceType {
     Oidc,
     /// Configure Authentik as a SCIM server for Nextcloud
     Scim,
+    #[strum(serialize = "db", serialize = "db-gate")]
+    DbGate,
 }
 
 #[enum_dispatch]
@@ -377,6 +385,7 @@ pub enum Service {
     AuthentikSaml(AuthentikSaml),
     AuthentikOidc(AuthentikOidc),
     AuthentikScim(AuthentikScim),
+    DbGate(DbGate),
     Preset(PresetService),
 }
 
@@ -436,6 +445,7 @@ impl Service {
                     Service::Authentik(Authentik),
                     Service::AuthentikScim(AuthentikScim),
                 ]),
+                ServiceType::DbGate => Some(vec![Service::DbGate(DbGate)]),
             }
         } else {
             presets
diff --git a/src/service/dbgate.rs b/src/service/dbgate.rs
new file mode 100644
index 0000000..050ec84
--- /dev/null
+++ b/src/service/dbgate.rs
@@ -0,0 +1,133 @@
+use std::io::Stdout;
+
+use crate::Result;
+use crate::cloud::CloudOptions;
+use crate::config::HazeConfig;
+use crate::database::DatabaseFamily;
+use crate::exec::exec;
+use crate::image::pull_image;
+use crate::mapping::Mapping;
+use crate::service::ServiceTrait;
+use bollard::Docker;
+use bollard::models::{ContainerCreateBody, EndpointSettings, HostConfig, NetworkingConfig};
+use bollard::query_parameters::CreateContainerOptions;
+use maplit::hashmap;
+use miette::IntoDiagnostic;
+
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub struct DbGate;
+
+#[async_trait::async_trait]
+impl ServiceTrait for DbGate {
+    fn name(&self) -> &str {
+        "db"
+    }
+
+    fn hidden(&self) -> bool {
+        true
+    }
+
+    async fn spawn(
+        &self,
+        docker: &Docker,
+        cloud_id: &str,
+        network: &str,
+        config: &HazeConfig,
+        options: &CloudOptions,
+    ) -> Result<Vec<String>> {
+        let image = "dbgate/dbgate:7.3.1";
+        pull_image(docker, image).await?;
+        let container_options = Some(CreateContainerOptions {
+            name: self.container_name(cloud_id),
+            ..CreateContainerOptions::default()
+        });
+
+        let db_family = options.db.family();
+
+        let mut env = vec![
+            "CONNECTIONS=con1".into(),
+            "USAGE_ANALYTICS=false".into(),
+            "LOCAL_DBGATE_CLOUD=1".into(),
+            "LABEL_con1=haze".into(),
+            format!("ENGINE_con1={}", db_family.db_gate_driver()),
+        ];
+
+        if db_family == DatabaseFamily::Sqlite {
+            env.extend(["FILE_con1=/haze-data/haze.db".into()]);
+        } else {
+            env.extend([
+                "SERVER_con1=db".into(),
+                format!("USER_con1={}", db_family.username()),
+                format!("PORT_con1={}", db_family.port()),
+                format!("DATABASE_con1={}", db_family.db()),
+                "PASSWORD_con1=haze".into(),
+            ]);
+        }
+
+        if db_family == DatabaseFamily::Oracle {
+            env.push("SERVICE_NAME_con1=xe".into());
+        }
+
+        let mapping = Mapping::new(
+            crate::mapping::MappingSourceType::WorkDir,
+            "data",
+            "/haze-data",
+        );
+
+        let config = ContainerCreateBody {
+            image: Some(image.into()),
+            host_config: Some(HostConfig {
+                network_mode: Some(network.to_string()),
+                binds: Some(vec![
+                    mapping
+                        .get_volume_arg(cloud_id, config, &config.sources_root)
+                        .unwrap(),
+                ]),
+                ..Default::default()
+            }),
+            env: Some(env),
+            labels: Some(hashmap! {
+                "haze-type".into() => self.name().into(),
+                "haze-cloud-id".into() => cloud_id.into(),
+            }),
+            networking_config: Some(NetworkingConfig {
+                endpoints_config: Some(hashmap! {
+                    network.into() => EndpointSettings {
+                        aliases: Some(vec![self.name().to_string()]),
+                        ..Default::default()
+                    }
+                }),
+            }),
+            ..Default::default()
+        };
+        let id = docker
+            .create_container(container_options, config)
+            .await
+            .into_diagnostic()?
+            .id;
+        docker.start_container(&id, None).await.into_diagnostic()?;
+        exec(
+            docker,
+            &id,
+            "root",
+            vec![
+                "sed",
+                "-i",
+                "s/attr(t,`title`,`Upgrade to Premium`)/attr(t,`style`,`display:none`)/",
+                "public/build/bundle.js",
+            ],
+            Vec::<String>::new(),
+            None::<Stdout>,
+        )
+        .await?;
+        Ok(vec![id])
+    }
+
+    fn container_name(&self, cloud_id: &str) -> Option<String> {
+        Some(format!("{}-db-gate", cloud_id))
+    }
+
+    fn proxy_port(&self) -> u16 {
+        3000
+    }
+}

From 6c440952dc82d6607410f55ba4ad2b5a7a550671 Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Sun, 27 Sep 2026 17:28:59 +0200
Subject: [PATCH 14/21] allow opening services with `haze open`

---
 CHANGELOG.md |  1 +
 src/args.rs  | 18 +++++++++++++++++-
 src/main.rs  | 23 +++++++++++++++++++----
 3 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ed38d46..e7ec264 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 - Support having a `#!` inside a haze script to specify the interpreter to use
 - Add webui for accessing the database.
+- Allow opening services with `haze open [service]`
 
 ## 2.4.1
 
diff --git a/src/args.rs b/src/args.rs
index 7e28603..7bec3c1 100644
--- a/src/args.rs
+++ b/src/args.rs
@@ -64,6 +64,7 @@ pub enum HazeArgs {
     },
     Open {
         filter: Option<String>,
+        service: Option<Service>,
     },
     Fmt {
         path: String,
@@ -317,7 +318,21 @@ impl HazeArgs {
                         .into_diagnostic()?,
                 })
             }
-            HazeCommand::Open => Ok(HazeArgs::Open { filter }),
+            HazeCommand::Open => {
+                let mut args = args.peekable();
+                let service = match args.peek() {
+                    Some(arg) => Service::from_type(&[], arg.as_ref())
+                        .into_iter()
+                        .filter_map(|services| services.into_iter().next())
+                        .next()
+                        .map(|service| {
+                            args.next();
+                            service
+                        }),
+                    _ => None,
+                };
+                Ok(HazeArgs::Open { filter, service })
+            }
             HazeCommand::Fmt => {
                 let path = args
                     .next()
@@ -472,6 +487,7 @@ pub enum HazeCommand {
     ))]
     Logs,
     /// Open an instance in the browser
+    #[strum(props(Args = "[service] service to open, instead of the Nextcloud instance"))]
     Open,
     /// Run code formatting from a new instance
     #[strum(props(Args = "[path] path to format"))]
diff --git a/src/main.rs b/src/main.rs
index d425a73..2677db1 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -286,11 +286,26 @@ async fn main() -> Result<ExitCode> {
                     .await?;
             }
         }
-        HazeArgs::Open { filter } => {
+        HazeArgs::Open { filter, service } => {
             let cloud = Cloud::get_by_filter(&docker, filter, &config).await?;
-            match cloud.ip {
-                Some(_) => opener::open(cloud.address).into_diagnostic()?,
-                None => eprintln!("{} is not running", cloud.id),
+            match service {
+                Some(service) => {
+                    let Some(ip) = service.get_ips(&docker, &cloud.id).await?.next() else {
+                        eprintln!(
+                            "Service {} can't be opened as it has no associated IP",
+                            service.name()
+                        );
+                        return Ok(ExitCode::FAILURE);
+                    };
+                    let addr = config
+                        .proxy
+                        .addr(&format!("{}-{}", &cloud.id, service.name()), ip);
+                    opener::open(addr).into_diagnostic()?;
+                }
+                None => match cloud.ip {
+                    Some(_) => opener::open(cloud.address).into_diagnostic()?,
+                    None => eprintln!("{} is not running", cloud.id),
+                },
             }
         }
         HazeArgs::Test { options, mut args } => {

From fb4e65eef4f8d16486719e5480e3e1d02c8259b7 Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Sun, 27 Sep 2026 17:57:58 +0200
Subject: [PATCH 15/21] add database section to book

---
 book/src/SUMMARY.md  |  1 +
 book/src/database.md | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+)
 create mode 100644 book/src/database.md

diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index f771191..b201bc6 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -9,6 +9,7 @@
   - [DNS](proxy/dns.md)
   - [HTTPS](proxy/https.md)
 - [Services](services.md)
+- [Database](database.md)
 - [Federation](federation.md)
 - [Haze scripts](scripts.md)
 - [Xdebug](xdebug.md)
diff --git a/book/src/database.md b/book/src/database.md
new file mode 100644
index 0000000..bf96761
--- /dev/null
+++ b/book/src/database.md
@@ -0,0 +1,33 @@
+# Database
+
+There are 3 ways of accessing the database of a haze instance.
+
+## CLI
+
+```bash
+haze [filter] db [query]
+```
+
+Opens the command line client for the database. If a query is specified, it will
+be executed. If no query is specified, an interactive shell will be started.
+
+Example
+
+```
+haze db 'select fileid, storage, path from oc_filecache'
+```
+
+## WebUI
+
+A web UI (based on [DbGate](https://www.dbgate.io/)) is available with every
+instance.
+
+It can be accessed by using `haze open db`, or, if the proxy is setup at
+`db.haze.example.com`.
+
+## External tools
+
+For usage with external tools, the database connection URL is printed when the
+instance is created.
+
+Details on how to use the connection URL is dependent on the external tool.

From 39b5370818dc90fae06c1bc1c669f2f138678d53 Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Sun, 27 Sep 2026 18:04:09 +0200
Subject: [PATCH 16/21] formatting

---
 src/help.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/help.rs b/src/help.rs
index 29c09ff..fec9415 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -2,8 +2,8 @@ use crate::args::{HazeCommand, SubCommand};
 use crate::database::DatabaseFamily;
 use crate::php::PhpVersion;
 use crate::service::ServiceType;
-use owo_colors::OwoColorize;
 use owo_colors::colors::xterm::Gray;
+use owo_colors::OwoColorize;
 use strum::{EnumMessage, EnumProperty, IntoEnumIterator};
 
 pub fn help(command: Option<&dyn SubCommand>) {

From eefffc32310a9278b09082469cf264d1afb159ee Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Sun, 27 Sep 2026 18:04:09 +0200
Subject: [PATCH 17/21] clippy fixes

---
 src/args.rs  | 3 +--
 src/cloud.rs | 7 ++-----
 src/main.rs  | 2 +-
 3 files changed, 4 insertions(+), 8 deletions(-)

diff --git a/src/args.rs b/src/args.rs
index 7bec3c1..1f13cc2 100644
--- a/src/args.rs
+++ b/src/args.rs
@@ -325,9 +325,8 @@ impl HazeArgs {
                         .into_iter()
                         .filter_map(|services| services.into_iter().next())
                         .next()
-                        .map(|service| {
+                        .inspect(|_| {
                             args.next();
-                            service
                         }),
                     _ => None,
                 };
diff --git a/src/cloud.rs b/src/cloud.rs
index 0928e33..515537f 100644
--- a/src/cloud.rs
+++ b/src/cloud.rs
@@ -542,7 +542,7 @@ impl Cloud {
                 .services
                 .iter()
                 .filter(|service| !service.hidden())
-                .chain(DEFAULT_SERVICES.into_iter())
+                .chain(DEFAULT_SERVICES.iter())
                 .map(|service| service.spawn(docker, &id, &network, config, &options)),
         )
         .await?;
@@ -974,10 +974,7 @@ impl Cloud {
     }
 
     pub fn services(&self) -> impl Iterator<Item = &Service> {
-        self.options
-            .services
-            .iter()
-            .chain(DEFAULT_SERVICES.into_iter())
+        self.options.services.iter().chain(DEFAULT_SERVICES.iter())
     }
 
     pub fn db(&self) -> &Database {
diff --git a/src/main.rs b/src/main.rs
index 2677db1..2271d5c 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -299,7 +299,7 @@ async fn main() -> Result<ExitCode> {
                     };
                     let addr = config
                         .proxy
-                        .addr(&format!("{}-{}", &cloud.id, service.name()), ip);
+                        .addr(&format!("{}-{}", cloud.id, service.name()), ip);
                     opener::open(addr).into_diagnostic()?;
                 }
                 None => match cloud.ip {

From a73f4218b2e0c09cb57a606cb077f68ac31ebd2b Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Sun, 27 Sep 2026 18:04:09 +0200
Subject: [PATCH 18/21] 2.4.2

---
 CHANGELOG.md | 4 ++--
 Cargo.lock   | 2 +-
 Cargo.toml   | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e7ec264..4de8b07 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,7 +1,7 @@
-## Unreleased
+## 2.4.2
 
 - Support having a `#!` inside a haze script to specify the interpreter to use
-- Add webui for accessing the database.
+- Add WebUI for accessing the database.
 - Allow opening services with `haze open [service]`
 
 ## 2.4.1
diff --git a/Cargo.lock b/Cargo.lock
index 97e3e78..bbaba4a 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -899,7 +899,7 @@ checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
 
 [[package]]
 name = "haze"
-version = "2.4.1"
+version = "2.4.2"
 dependencies = [
  "async-trait",
  "atty",
diff --git a/Cargo.toml b/Cargo.toml
index c21a0a4..3968b51 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "haze"
-version = "2.4.1"
+version = "2.4.2"
 edition = "2024"
 description = "Easy setup and management of Nextcloud test instances using docker"
 repository = "https://codeberg.org/icewind/haze"

From 3398027ad2f0ab306e2af9ed6d682476fca05247 Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Sun, 27 Sep 2026 19:01:25 +0200
Subject: [PATCH 19/21] formatting

---
 src/image.rs                |  2 +-
 src/network.rs              |  9 +++++----
 src/php.rs                  | 23 ++++++++++++-----------
 src/service/clam.rs         | 14 +++++++++-----
 src/service/dav.rs          |  6 +++---
 src/service/imaginary.rs    |  6 +++---
 src/service/kaspersky.rs    |  8 ++++----
 src/service/ldap.rs         | 10 ++++++----
 src/service/mail.rs         |  6 +++---
 src/service/oc.rs           |  4 ++--
 src/service/office.rs       |  4 ++--
 src/service/onlyoffice.rs   |  6 +++---
 src/service/partitioning.rs |  2 +-
 src/service/push.rs         |  2 +-
 src/service/redis.rs        |  6 +++---
 src/service/sftp.rs         |  6 +++---
 src/service/sharded.rs      |  4 ++--
 src/service/smb.rs          |  6 +++---
 src/service/webhook.rs      |  4 ++--
 src/sources.rs              |  2 +-
 20 files changed, 69 insertions(+), 61 deletions(-)

diff --git a/src/image.rs b/src/image.rs
index e24abfd..26850d9 100644
--- a/src/image.rs
+++ b/src/image.rs
@@ -1,6 +1,6 @@
+use bollard::Docker;
 use bollard::models::CreateImageInfo;
 use bollard::query_parameters::CreateImageOptions;
-use bollard::Docker;
 use futures_util::StreamExt;
 use indicatif::{MultiProgress, ProgressBar, ProgressStyle};
 use miette::{IntoDiagnostic, Result, WrapErr};
diff --git a/src/network.rs b/src/network.rs
index 386e13c..1ea2050 100644
--- a/src/network.rs
+++ b/src/network.rs
@@ -1,6 +1,6 @@
 use crate::cloud::Cloud;
-use bollard::config::NetworkCreateRequest;
 use bollard::Docker;
+use bollard::config::NetworkCreateRequest;
 use miette::{IntoDiagnostic, Result, WrapErr};
 
 pub async fn clear_networks(docker: &Docker, instances: &[Cloud]) -> Result<()> {
@@ -12,9 +12,10 @@ pub async fn clear_networks(docker: &Docker, instances: &[Cloud]) -> Result<()>
     for network in networks {
         if let Some(name) = network.name.as_deref()
             && let Some(id) = name.strip_prefix("haze-")
-                && !instances.iter().any(|cloud| cloud.id == id) {
-                    docker.remove_network(name).await.ok();
-                }
+            && !instances.iter().any(|cloud| cloud.id == id)
+        {
+            docker.remove_network(name).await.ok();
+        }
     }
     Ok(())
 }
diff --git a/src/php.rs b/src/php.rs
index f0878a5..e56267a 100644
--- a/src/php.rs
+++ b/src/php.rs
@@ -1,13 +1,13 @@
 use crate::config::ProxyConfig;
 use crate::database::Database;
-use crate::image::{image_version, pull_image, ImageVersion};
+use crate::image::{ImageVersion, image_version, pull_image};
 use crate::network::ensure_network_exists;
 use crate::service::Service;
 use crate::service::ServiceTrait;
+use bollard::Docker;
 use bollard::config::{ContainerCreateBody, NetworkConnectRequest, NetworkingConfig};
 use bollard::models::{EndpointSettings, HostConfig};
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use itertools::Itertools;
 use maplit::hashmap;
 use miette::{IntoDiagnostic, Report, Result, WrapErr};
@@ -127,15 +127,16 @@ impl PhpVersion {
         let image_version = image_version(docker, self.image()).await;
         let haze_version = ImageVersion::from_str(env!("CARGO_PKG_VERSION"));
         if let (Some(image_version), Ok(haze_version)) = (image_version, haze_version)
-            && image_version < haze_version {
-                eprintln!(
-                    "{}: image version is out of date, run {} to update.",
-                    "Warning".red(),
-                    "haze update".blue()
-                );
-                eprintln!("         Haze  version: {}", haze_version.bright_yellow());
-                eprintln!("         Image version: {}", image_version.bright_yellow());
-            }
+            && image_version < haze_version
+        {
+            eprintln!(
+                "{}: image version is out of date, run {} to update.",
+                "Warning".red(),
+                "haze update".blue()
+            );
+            eprintln!("         Haze  version: {}", haze_version.bright_yellow());
+            eprintln!("         Image version: {}", image_version.bright_yellow());
+        }
 
         let options = Some(CreateContainerOptions {
             name: Some(id.to_string()),
diff --git a/src/service/clam.rs b/src/service/clam.rs
index 02c72b9..d614ecd 100644
--- a/src/service/clam.rs
+++ b/src/service/clam.rs
@@ -1,12 +1,12 @@
+use crate::Result;
 use crate::cloud::CloudOptions;
 use crate::config::HazeConfig;
 use crate::exec::exec;
 use crate::image::pull_image;
-use crate::service::{split_cmnd, ServiceTrait};
-use crate::Result;
+use crate::service::{ServiceTrait, split_cmnd};
+use bollard::Docker;
 use bollard::models::{ContainerCreateBody, EndpointSettings, HostConfig, NetworkingConfig};
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use maplit::hashmap;
 use miette::{IntoDiagnostic, WrapErr};
 use tokio::fs::write;
@@ -92,7 +92,9 @@ impl ServiceTrait for ClamIcap {
             split_cmnd("occ config:app:set files_antivirus av_host --value=clamav-icap"),
             split_cmnd("occ config:app:set files_antivirus av_port --value=1344"),
             split_cmnd("occ config:app:set files_antivirus av_icap_request_service --value=avscan"),
-            split_cmnd("occ config:app:set files_antivirus av_icap_response_header --value=X-Infection-Found"),
+            split_cmnd(
+                "occ config:app:set files_antivirus av_icap_response_header --value=X-Infection-Found",
+            ),
         ])
     }
 }
@@ -196,7 +198,9 @@ impl ServiceTrait for ClamIcapTls {
             split_cmnd("occ config:app:set files_antivirus av_host --value=clamav-icap-tls"),
             split_cmnd("occ config:app:set files_antivirus av_port --value=1345"),
             split_cmnd("occ config:app:set files_antivirus av_icap_request_service --value=avscan"),
-            split_cmnd("occ config:app:set files_antivirus av_icap_response_header --value=X-Infection-Found"),
+            split_cmnd(
+                "occ config:app:set files_antivirus av_icap_response_header --value=X-Infection-Found",
+            ),
             split_cmnd("occ security:certificates:import data/icap-cert.pem"),
         ])
     }
diff --git a/src/service/dav.rs b/src/service/dav.rs
index e0b20f3..5442b3b 100644
--- a/src/service/dav.rs
+++ b/src/service/dav.rs
@@ -1,12 +1,12 @@
+use crate::Result;
 use crate::cloud::CloudOptions;
 use crate::config::HazeConfig;
 use crate::image::pull_image;
-use crate::service::{split_cmnd, ServiceTrait};
-use crate::Result;
+use crate::service::{ServiceTrait, split_cmnd};
+use bollard::Docker;
 use bollard::config::ContainerCreateBody;
 use bollard::models::{EndpointSettings, HostConfig, NetworkingConfig};
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use maplit::hashmap;
 use miette::IntoDiagnostic;
 
diff --git a/src/service/imaginary.rs b/src/service/imaginary.rs
index 4ec4d96..65325cf 100644
--- a/src/service/imaginary.rs
+++ b/src/service/imaginary.rs
@@ -1,12 +1,12 @@
+use crate::Result;
 use crate::cloud::CloudOptions;
 use crate::config::HazeConfig;
 use crate::image::pull_image;
-use crate::service::{split_cmnd, ServiceTrait};
-use crate::Result;
+use crate::service::{ServiceTrait, split_cmnd};
+use bollard::Docker;
 use bollard::config::NetworkingConfig;
 use bollard::models::{ContainerCreateBody, EndpointSettings, HostConfig};
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use maplit::hashmap;
 use miette::IntoDiagnostic;
 
diff --git a/src/service/kaspersky.rs b/src/service/kaspersky.rs
index 00ec187..af9c654 100644
--- a/src/service/kaspersky.rs
+++ b/src/service/kaspersky.rs
@@ -1,14 +1,14 @@
+use crate::Result;
 use crate::cloud::CloudOptions;
 use crate::config::HazeConfig;
 use crate::exec::exec;
 use crate::image::{image_exists, pull_image};
-use crate::service::{split_cmnd, ServiceTrait};
-use crate::Result;
+use crate::service::{ServiceTrait, split_cmnd};
+use bollard::Docker;
 use bollard::models::{ContainerCreateBody, EndpointSettings, HostConfig, NetworkingConfig};
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use maplit::hashmap;
-use miette::{bail, IntoDiagnostic};
+use miette::{IntoDiagnostic, bail};
 use std::io::Stdout;
 
 #[derive(Debug, Clone, Eq, PartialEq)]
diff --git a/src/service/ldap.rs b/src/service/ldap.rs
index 4f317e6..0514994 100644
--- a/src/service/ldap.rs
+++ b/src/service/ldap.rs
@@ -1,12 +1,12 @@
+use crate::Result;
 use crate::cloud::CloudOptions;
 use crate::config::{HazeConfig, ProxyConfig};
 use crate::image::pull_image;
-use crate::service::{split_cmnd, ServiceTrait};
-use crate::Result;
+use crate::service::{ServiceTrait, split_cmnd};
+use bollard::Docker;
 use bollard::config::NetworkingConfig;
 use bollard::models::{ContainerCreateBody, ContainerState, EndpointSettings, HostConfig};
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use maplit::hashmap;
 use miette::{IntoDiagnostic, Report};
 use std::net::IpAddr;
@@ -102,7 +102,9 @@ impl ServiceTrait for Ldap {
             split_cmnd("occ ldap:set-config s01 ldapBase dc=example,dc=org"),
             split_cmnd("occ ldap:set-config s01 ldapBaseUsers dc=example,dc=org"),
             split_cmnd("occ ldap:set-config s01 ldapBaseGroups dc=example,dc=org"),
-            split_cmnd("occ ldap:set-config s01 ldapLoginFilter (&(&(objectclass=inetOrgPerson))(uid=%uid))"),
+            split_cmnd(
+                "occ ldap:set-config s01 ldapLoginFilter (&(&(objectclass=inetOrgPerson))(uid=%uid))",
+            ),
             split_cmnd("occ ldap:set-config s01 ldapUserFilter ((objectclass=inetOrgPerson))"),
             split_cmnd("occ ldap:set-config s01 ldapUserFilterMode 0"),
             split_cmnd("occ ldap:set-config s01 ldapUserDisplayName sn"),
diff --git a/src/service/mail.rs b/src/service/mail.rs
index 9dfcfcb..7367ffd 100644
--- a/src/service/mail.rs
+++ b/src/service/mail.rs
@@ -1,11 +1,11 @@
+use crate::Result;
 use crate::cloud::CloudOptions;
 use crate::config::HazeConfig;
 use crate::image::pull_image;
-use crate::service::{split_cmnd, ServiceTrait};
-use crate::Result;
+use crate::service::{ServiceTrait, split_cmnd};
+use bollard::Docker;
 use bollard::models::{ContainerCreateBody, EndpointSettings, HostConfig, NetworkingConfig};
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use maplit::hashmap;
 use miette::IntoDiagnostic;
 
diff --git a/src/service/oc.rs b/src/service/oc.rs
index 296b2a5..2baac6e 100644
--- a/src/service/oc.rs
+++ b/src/service/oc.rs
@@ -1,13 +1,13 @@
+use crate::Result;
 use crate::cloud::CloudOptions;
 use crate::config::HazeConfig;
 use crate::exec::exec;
 use crate::image::pull_image;
 use crate::service::ServiceTrait;
-use crate::Result;
+use bollard::Docker;
 use bollard::config::NetworkingConfig;
 use bollard::models::{ContainerCreateBody, EndpointSettings, HostConfig};
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use maplit::hashmap;
 use miette::IntoDiagnostic;
 use std::io::Stdout;
diff --git a/src/service/office.rs b/src/service/office.rs
index e7db10d..8ff59fe 100644
--- a/src/service/office.rs
+++ b/src/service/office.rs
@@ -1,13 +1,13 @@
+use crate::Result;
 use crate::cloud::CloudOptions;
 use crate::config::HazeConfig;
 use crate::image::pull_image;
 use crate::service::ServiceTrait;
-use crate::Result;
+use bollard::Docker;
 use bollard::models::{
     ContainerCreateBody, ContainerState, EndpointSettings, HostConfig, NetworkingConfig,
 };
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use maplit::hashmap;
 use miette::{IntoDiagnostic, Report};
 
diff --git a/src/service/onlyoffice.rs b/src/service/onlyoffice.rs
index fa12c2c..f33251f 100644
--- a/src/service/onlyoffice.rs
+++ b/src/service/onlyoffice.rs
@@ -1,14 +1,14 @@
+use crate::Result;
 use crate::cloud::CloudOptions;
 use crate::config::HazeConfig;
 use crate::exec::exec;
 use crate::image::pull_image;
-use crate::service::{split_cmnd, ServiceTrait};
-use crate::Result;
+use crate::service::{ServiceTrait, split_cmnd};
+use bollard::Docker;
 use bollard::models::{
     ContainerCreateBody, ContainerState, EndpointSettings, HostConfig, NetworkingConfig,
 };
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use maplit::hashmap;
 use miette::{IntoDiagnostic, Report};
 use std::net::Ipv4Addr;
diff --git a/src/service/partitioning.rs b/src/service/partitioning.rs
index f8f20b5..13425e4 100644
--- a/src/service/partitioning.rs
+++ b/src/service/partitioning.rs
@@ -1,11 +1,11 @@
 use std::io::stdout;
 
+use crate::Result;
 use crate::cloud::CloudOptions;
 use crate::config::HazeConfig;
 use crate::database::DatabaseFamily;
 use crate::exec::exec;
 use crate::service::ServiceTrait;
-use crate::Result;
 use bollard::Docker;
 use miette::Report;
 
diff --git a/src/service/push.rs b/src/service/push.rs
index b0bbab2..ff7d7d1 100644
--- a/src/service/push.rs
+++ b/src/service/push.rs
@@ -2,9 +2,9 @@ use crate::cloud::CloudOptions;
 use crate::config::HazeConfig;
 use crate::image::pull_image;
 use crate::service::ServiceTrait;
+use bollard::Docker;
 use bollard::models::{ContainerCreateBody, EndpointSettings, HostConfig, NetworkingConfig};
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use local_ip_address::list_afinet_netifas;
 use maplit::hashmap;
 use miette::{IntoDiagnostic, Result};
diff --git a/src/service/redis.rs b/src/service/redis.rs
index 6d5d5e6..6771999 100644
--- a/src/service/redis.rs
+++ b/src/service/redis.rs
@@ -1,11 +1,11 @@
+use crate::Result;
 use crate::cloud::CloudOptions;
 use crate::config::HazeConfig;
 use crate::image::pull_image;
-use crate::service::{split_cmnd, ServiceTrait};
-use crate::Result;
+use crate::service::{ServiceTrait, split_cmnd};
+use bollard::Docker;
 use bollard::models::{ContainerCreateBody, EndpointSettings, HostConfig, NetworkingConfig};
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use maplit::hashmap;
 use miette::IntoDiagnostic;
 
diff --git a/src/service/sftp.rs b/src/service/sftp.rs
index 1f47a40..8125981 100644
--- a/src/service/sftp.rs
+++ b/src/service/sftp.rs
@@ -1,11 +1,11 @@
+use crate::Result;
 use crate::cloud::CloudOptions;
 use crate::config::HazeConfig;
 use crate::image::pull_image;
-use crate::service::{split_cmnd, ServiceTrait};
-use crate::Result;
+use crate::service::{ServiceTrait, split_cmnd};
+use bollard::Docker;
 use bollard::models::{ContainerCreateBody, EndpointSettings, HostConfig, NetworkingConfig};
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use maplit::hashmap;
 use miette::{Context, IntoDiagnostic};
 use std::fs::{create_dir_all, write};
diff --git a/src/service/sharded.rs b/src/service/sharded.rs
index 8259eeb..df4e8d0 100644
--- a/src/service/sharded.rs
+++ b/src/service/sharded.rs
@@ -1,14 +1,14 @@
+use crate::Result;
 use crate::cloud::CloudOptions;
 use crate::config::HazeConfig;
 use crate::database::DatabaseFamily;
 use crate::service::ServiceTrait;
-use crate::Result;
 use bollard::Docker;
 use futures_util::future::try_join_all;
 use maplit::hashmap;
 use miette::Report;
-use serde_json::json;
 use serde_json::Value;
+use serde_json::json;
 use std::collections::HashMap;
 use std::convert::identity;
 
diff --git a/src/service/smb.rs b/src/service/smb.rs
index 08f69bd..44fafc3 100644
--- a/src/service/smb.rs
+++ b/src/service/smb.rs
@@ -1,11 +1,11 @@
+use crate::Result;
 use crate::cloud::CloudOptions;
 use crate::config::HazeConfig;
 use crate::image::pull_image;
-use crate::service::{split_cmnd, ServiceTrait};
-use crate::Result;
+use crate::service::{ServiceTrait, split_cmnd};
+use bollard::Docker;
 use bollard::models::{ContainerCreateBody, EndpointSettings, HostConfig, NetworkingConfig};
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use maplit::hashmap;
 use miette::IntoDiagnostic;
 
diff --git a/src/service/webhook.rs b/src/service/webhook.rs
index e7ebae0..8903b88 100644
--- a/src/service/webhook.rs
+++ b/src/service/webhook.rs
@@ -1,11 +1,11 @@
+use crate::Result;
 use crate::cloud::CloudOptions;
 use crate::config::HazeConfig;
 use crate::image::pull_image;
 use crate::service::ServiceTrait;
-use crate::Result;
+use bollard::Docker;
 use bollard::models::{ContainerCreateBody, EndpointSettings, HostConfig, NetworkingConfig};
 use bollard::query_parameters::CreateContainerOptions;
-use bollard::Docker;
 use maplit::hashmap;
 use miette::IntoDiagnostic;
 
diff --git a/src/sources.rs b/src/sources.rs
index ccfe564..0471a76 100644
--- a/src/sources.rs
+++ b/src/sources.rs
@@ -10,8 +10,8 @@ use std::io::Cursor;
 use std::path::{Path, PathBuf};
 use std::time::Duration;
 use tokio::fs::create_dir_all;
-use zip::read::root_dir_common_filter;
 use zip::ZipArchive;
+use zip::read::root_dir_common_filter;
 
 pub struct Sources {
     #[allow(dead_code)]

From d973bca0b3ce46ed62076b882b5e538b0e9f2af1 Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Sun, 27 Sep 2026 19:01:25 +0200
Subject: [PATCH 20/21] add some developer documentation

---
 .vale/config/vocabularies/haze/accept.txt |  1 +
 DEVELOPING.md                             | 80 +++++++++++++++++++++++
 README.md                                 |  4 ++
 flake.nix                                 |  2 +-
 4 files changed, 86 insertions(+), 1 deletion(-)
 create mode 100644 DEVELOPING.md

diff --git a/.vale/config/vocabularies/haze/accept.txt b/.vale/config/vocabularies/haze/accept.txt
index 4cd11e4..925d628 100644
--- a/.vale/config/vocabularies/haze/accept.txt
+++ b/.vale/config/vocabularies/haze/accept.txt
@@ -23,3 +23,4 @@ worktrees
 config
 stdin
 stdout
+direnv
diff --git a/DEVELOPING.md b/DEVELOPING.md
new file mode 100644
index 0000000..d7f9f65
--- /dev/null
+++ b/DEVELOPING.md
@@ -0,0 +1,80 @@
+# Developing
+
+## Setup
+
+### Nix based development environment
+
+The recommended way to setup the development environment is to use
+[Lix](https://lix.systems/install/)/[Nix](https://nixos.org/download/).
+
+Once installed, you can enter the development shell using `nix develop` or,
+setup [direnv](https://direnv.net/) to automatically enter the development shell
+when you enter the folder.
+
+The development shell provides all necessary tooling to develop haze.
+
+### Without Nix
+
+The fooling tools need to be setup to develop without using Nix to manage the
+development setup:
+
+- [`cargo`](https://doc.rust-lang.org/cargo/getting-started/installation.html) -
+  For building the program
+- [`mdbook`](https://github.com/rust-lang/mdBook) - For building the
+  documentation
+- [`prettier`](https://prettier.io/) - For formatting the non-rust files
+- [`vale`](https://vale.sh/) - For checking documentation
+
+## Building
+
+```bash
+cargo build
+```
+
+The binary can then be found at `target/debug/haze`.
+
+## Formatting
+
+### With Nix
+
+```bash
+nix fmt
+```
+
+### Without Nix
+
+#### Rust code
+
+```bash
+cargo fmt
+```
+
+#### Documentation
+
+```bash
+prettier --write '**/*.md'
+```
+
+### Building documentation
+
+```bash
+mdbook serve
+```
+
+### Checking documentation
+
+```bash
+vale src/ book/src/ book/README.md *.md
+```
+
+### Run all checks
+
+```bash
+nix flake check
+```
+
+### Building docker images
+
+```bash
+nix run .#'"haze-image-php-8.4"'.copyToDockerDaemon
+```
diff --git a/README.md b/README.md
index 6f17bf1..33aee03 100644
--- a/README.md
+++ b/README.md
@@ -35,3 +35,7 @@ Documentation for haze can be found in the
 - Navigate to the address that is provided in the output.
 
 See the [book](https://icewind.codeberg.page/haze/) for more details.
+
+## Developing
+
+See [DEVELOPING.md](./DEVELOPING.md) for information on how to work on `haze`.
diff --git a/flake.nix b/flake.nix
index 5308a7a..d4c9127 100644
--- a/flake.nix
+++ b/flake.nix
@@ -69,7 +69,7 @@
         ];
 
       checks = {
-        vale = {vale, ...}: "${vale}/bin/vale src/ book/src/ CHANGELOG.md README.md book/README.md";
+        vale = {vale, ...}: "${vale}/bin/vale src/ book/src/ book/README.md *.md";
       };
 
       homeModules = {

From 1e2e826817587fe0da4c1a760854708a2e30a077 Mon Sep 17 00:00:00 2001
From: Robin Appelman <robin@icewind.nl>
Date: Sun, 27 Sep 2026 22:52:04 +0200
Subject: [PATCH 21/21] book: mention where xdebug output files are

---
 book/src/xdebug.md | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/book/src/xdebug.md b/book/src/xdebug.md
index 11a6089..58079ca 100644
--- a/book/src/xdebug.md
+++ b/book/src/xdebug.md
@@ -19,7 +19,7 @@ IDE debugger configuration usually looks like:
 
 This would have to be adapted for detached instances.
 
-### Debugging all requests
+## Debugging all requests
 
 By default, Xdebug is configured to only run for requests that containing the
 trigger (e.g. from using the Xdebug browser extension, or adding
@@ -29,3 +29,8 @@ To enable Xdebug for all requests:
 
 - Un-comment the lines in `haze [cloud-id] edit /config/php.ini`
 - Then run `haze reload [cloud-id]`
+
+## Xdebug profile and trace files
+
+When enabling Xdebug trace or profile mode, the generated files can be found in
+`<work-dir>/<instance id>/xdebug`.