book: mention where xdebug output files are

.vale/config/vocabularies/haze/accept.txt

@@ -23,3 +23,4 @@ worktrees
 config
 stdin
 stdout
+direnv

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

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

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

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

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

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,7 +12,8 @@ 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) {
+            && !instances.iter().any(|cloud| cloud.id == id)
+        {
             docker.remove_network(name).await.ok();
         }
     }

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,7 +127,8 @@ 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 {
+            && image_version < haze_version
+        {
             eprintln!(
                 "{}: image version is out of date, run {} to update.",
                 "Warning".red(),

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::service::{ServiceTrait, split_cmnd};
-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, 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"),
         ])
     }

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::service::{ServiceTrait, split_cmnd};
-use crate::Result;
+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;
 

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::service::{ServiceTrait, split_cmnd};
-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;
 

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::service::{ServiceTrait, split_cmnd};
-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::{bail, IntoDiagnostic};
+use miette::{IntoDiagnostic, bail};
 use std::io::Stdout;
 
 #[derive(Debug, Clone, Eq, PartialEq)]

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::service::{ServiceTrait, split_cmnd};
-use crate::Result;
+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"),

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::service::{ServiceTrait, split_cmnd};
-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;
 

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;

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

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::service::{ServiceTrait, split_cmnd};
-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};
 use std::net::Ipv4Addr;

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;
 

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

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::service::{ServiceTrait, split_cmnd};
-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;
 

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::service::{ServiceTrait, split_cmnd};
-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::{Context, IntoDiagnostic};
 use std::fs::{create_dir_all, write};

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;
 

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::service::{ServiceTrait, split_cmnd};
-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;
 

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;
 

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