From e52f978bea399b1b3236c8397aa1273d61a55703 Mon Sep 17 00:00:00 2001 From: Robin Appelman Date: Wed, 23 Sep 2026 15:10:49 +0200 Subject: [PATCH] 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: `/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 haze.example.com.crt -key-file haze.example.com.key '*.haze.example.com' +mkcert -cert-file haze.example.com.crt -key-file 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 /haze.example.com.crt; - ssl_certificate_key /haze.example.com.key; + ssl_certificate /haze.example.com.crt; + ssl_certificate_key /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. - ``: 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 Where `` 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]`