move the rest of the docs over

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.

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)

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

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

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.

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.

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

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

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