Merge pull request #608 from stgraber/doc

Improve packaging section and add 3rd party tools section

doc/.wordlist.txt

@@ -57,6 +57,7 @@ DHCP
 DHCPv
 Diátaxis
 Diffie
+Distrobuilder
 DNS
 DNSSEC
 DoS
@@ -76,6 +77,7 @@ failover
 FQDNs
 Furo
 gapped
+GARM
 GARP
 GbE
 Gbit
@@ -84,6 +86,7 @@ GiB
 Gibit
 GID
 GIDs
+Github
 Golang
 goroutines
 GPUs
@@ -169,6 +172,7 @@ OpenID
 OpenMetrics
 OpenSSL
 OpenSUSE
+OpenTofu
 OSD
 overcommit
 overcommitting
@@ -261,6 +265,7 @@ syslog
 Tbit
 TCP
 Telegraf
+Terraform
 TiB
 Tibit
 TLS

doc/external_resources.md

@@ -5,4 +5,5 @@
 
 Project repository <https://github.com/lxc/incus>
 Image server <https://images.linuxcontainers.org>
+Third party tools </third_party>
 ```

doc/packaging.md

@@ -62,3 +62,20 @@ To do that, the `INCUS_AGENT_PATH` environment variable should be set for the `i
 
 Those builds should be named after the operating system name and architecture.
 For example `incus-agent.linux.x86_64`, `incus-agent.linux.i686` or `incus-agent.linux.aarch64`.
+
+## Documentation
+### Web documentation
+Incus can serve its own documentation when the network listener is enabled (`core.https_address`).
+
+For that to work, the documentation provided in the release tarball
+should be shipped as part of the package and its path be passed to Incus
+through the `INCUS_DOCUMENTATION` environment variable.
+
+### Manual pages
+While we don't specifically write full `manpage` entries for Incus, it is possible to generate those from the CLI.
+
+Running `incus manpage --all --format=man /target/path` will generate a separate page for each command/sub-command.
+
+This is effectively the same as what's otherwise made available through `--help`,
+so unless a distribution packaging policy requires all binaries have `manpages`,
+it's usually best to rely on `--help` and `help` sub-commands.

doc/third_party.md

@@ -0,0 +1,35 @@
+# Third party tools and integrations
+Below are a list of common operations tools which feature Incus support, either natively or through a plugin.
+
+## Terraform / OpenTofu
+[Terraform](https://www.terraform.io) and [OpenTofu](https://opentofu.org) are infrastructure as code tools which focus on creating the infrastructure itself.
+For Incus, this means the ability to create projects, profiles, networks, storage volumes and of course instances.
+
+In most cases, one will then use Ansible to deploy the workloads
+themselves once the instances and everything else they need as been put in place.
+
+The integration with Incus is done through a [dedicated provider](https://github.com/lxc/terraform-provider-incus).
+
+## Ansible
+[Ansible](https://www.ansible.com) is an infrastructure as code tool with particular focus on software provisioning and configuration management.
+It does most of its work by first connecting to the system that it's deploying software on.
+
+To do that, it can connect over SSH and a variety of other protocols, one of which is [Incus](https://docs.ansible.com/ansible/latest/collections/community/general/incus_connection.html).
+
+That allows for easily deploying software inside of Incus instances without needing to first setup SSH.
+
+## Packer
+[Packer](https://www.packer.io) is a tool to generate custom OS images across a wide variety of platforms.
+
+A [plugin](https://developer.hashicorp.com/packer/integrations/bketelsen/incus) exists that allows Packer to generate Incus images directly.
+
+## Distrobuilder
+[Distrobuilder](https://github.com/lxc/distrobuilder) is an image building tool most known for producing the official LXC and Incus images.
+It consumes YAML definitions for its images and generates LXC container images as well as Incus container and VM images.
+
+The focus of Distrobuilder is in producing clean images from scratch, as opposed to repacking existing images.
+
+## GARM
+[GARM](https://github.com/cloudbase/garm) is the Github Actions Runner Manager which allows for running self-hosted Github runners.
+
+It supports a variety of providers for those runners, including [Incus](https://github.com/cloudbase/garm-provider-incus).