robin/haze
1
0
Fork 0
mirror of https://codeberg.org/icewind/haze.git synced 2026-10-01 00:34:09 +02:00
Code Issues Projects Releases Wiki Activity

spelling fixes in changelog and book

Browse source
This commit is contained in:
Robin Appelman 2026-09-23 15:10:49 +02:00
commit 51d0279c41
14 changed files with 110 additions and 102 deletions
Download patch file Download diff file Expand all files Collapse all files

36
CHANGELOG.md
View file

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

2
README.md
View file

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

9
book/README.md Normal file
View file

@ -0,0 +1,9 @@
## Build requirements
- [mdBook](https://github.com/rust-lang/mdBook)
## Development
```
mdbook serve
```

6
book/src/README.md
View file

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

73
book/src/configuration.md
View file

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

4
book/src/federation.md
View file

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

16
book/src/proxy/README.md
View file

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

8
book/src/proxy/dns.md
View file

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

20
book/src/proxy/https.md
View file

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

4
book/src/scripts.md
View file

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

16
book/src/services.md
View file

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

4
book/src/setup.md
View file

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

4
book/src/usage.md
View file

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

10
book/src/xdebug.md
View file

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