Docs: Update Documentation

docs/src/SUMMARY.md

@@ -15,6 +15,8 @@
     - [Release Workflow](./maintainers/release_workflow.md)
     - [API Update Workflow](./maintainers/api_update_workflow.md)
 - [User Documentation](./users/index.md)
-    - [Installation Instructions](./users/installation.md)
+    - [Install](./users/install.md)
     - [Configuration](./users/configuration.md)
+    - [Registering a Device or VM](./users/registration.md)
+    - [Updating a Device or VM](./users/update.md)
     - [The Plugin System](./users/plugins.md)

docs/src/intro.md

@@ -7,12 +7,8 @@
 Nazara is a Rust tool used to automate the registration and update process of machines and VMs in the
 IPAM tool [NetBox](https://netboxlabs.com/docs/netbox/).
 
-```admonish info
-Nazara is currently in it's Beta stage. Bugs are bound to happen.
-```
-
-```admonish tip
-Found a bug or a typo? [Open an issue on GitHub](https://github.com/The-Nazara-Project/Nazara/issues/new/choose)
+```admonish bug title="Found a bug?" 
+Please [Open an issue on GitHub](https://github.com/The-Nazara-Project/Nazara/issues/new/choose).
 ```
 
 ## Compatibility

docs/src/maintainers/release_workflow.md

@@ -58,6 +58,21 @@ In order to be able to publish new versions, you must be given permissions to do
 If the publishing fails, please reach out to the Project Owner.
 ~~~
 
-## 4. Updating Distribution Packages
+## 4. Create a New Release
+
+The next step includes creating a new Release via the VC Web UI.
+
+To do so, follow these steps:
+
+- [ ] Select latest tag
+- [ ] Select previous tag (if not already done automatically)
+- [ ] Press "Generate Release Notes" and split into `Added`, `Fixed`, `Removed` sections
+      as it seems fitting
+- [ ] Describe the core changes of this release in a short `What's new?` section at the top
+- [ ] Manually build a `.deb` package using `cargo deb` and attach that and the release
+      binary to the Release for people who want to manually download it
+- [ ] Hit "Create Release"
+
+## 5. Updating Distribution Packages
 
 -- Coming Soon --

docs/src/users/install.md

@@ -0,0 +1,43 @@
+# Installing Nazara
+
+You can install Nazara in a bunch of different ways.
+Our recommended solutions is to either get it from [`crates.io`](https://crates.io/crates/nazara), or
+build the latest release from source yourself.
+
+
+~~~ admonish info title="Native Packages"
+We are currently hard at work to build distribution packages in the future with the first one being
+targeted at openSUSE Tumbleweed, Slowroll, Leap and SLES16.
+
+If you would like to build a package for your distribution, please [refer to our packager's guide](../contributors/becoming_packager.md).
+~~~
+
+## Installing via `crates.io`
+
+To install Nazara via Rust's package index, make sure you have `cargo` and a current Rust toolchain installed.
+
+Then in your Terminal, run
+
+```bash
+cargo install --locked nazara
+```
+
+After installation you should be able to run Nazara just like you would any other program. If it doesn't work, it is likely
+that cargo's bin directory is not in your path. Refer to cargo's documentation for help with that problem.
+
+## Building from Source
+
+For this, please make sure you have cargo, `libopenssl` and a current Rust toolchain installed. (The last of which should be 
+compatible with Rust edition `2024`).
+
+Simply clone the repository and run `cargo build` to build it yourself.
+
+```bash
+git clone https://github.com/The-Nazara-Project/Nazara && cd Nazara
+cargo build --release
+```
+
+This process may take a while, mainly thanks to our API client library
+[thanix_client](https://github.com/The-Nazara-Project/thanix_client).
+
+Once completed you have a portable binary at `./target/release/nazara`.

docs/src/users/registration.md

@@ -0,0 +1,91 @@
+# Registering a Device or VM
+
+Registering a device with Nazara is as straight forward as
+[setting up the config file](./configuration.md) and running
+a simple command.
+
+~~~admonish info 
+Please make sure you have `sudo` privileges on the machine or VM you want to register, otherwise
+DMI information collection **will fail**.
+~~~
+
+## Example Registration Workflow (Physical Device)
+
+On a physical device, a example registration workflow may look like this:
+
+### 1. Set up Configuration
+
+The user wrote a configuration file at `/root/.config/nazara/config.toml`
+
+~~~admonish example title="Example: Device Config" collapsible=true
+```toml
+# Configuration parameters for the NetBox connection
+[netbox]
+netbox_api_token = "XXXXXXXX"
+netbox_uri = "https://netbox.organisation.com"
+
+# Common settings that always have to be provided
+[common]
+# The name of the device/VM
+name = "user@"
+description = ""
+# A comment left by Nazara if anything gets modified by it.
+comments = "Automatically registered by Nazara."
+# The current status of the device/VM
+status = "active"
+primary_ip4 = "192.168.0.1"
+primary_ip6 = ""
+
+# ---------------------------------------------------------------
+# Use [device] for devices, or [vm] if this is a virtual machine.
+# ---------------------------------------------------------------
+
+[device]
+device_type = 1
+role = 1
+site = 1
+```
+
+The configuration file for a VM looks quite similarly. For a list
+of allowed config parameters, please refer to our [template](https://github.com/The-Nazara-Project/Nazara/blob/main/src/configuration/config_template.toml).
+
+You can verify the integrity of your config by running `nazara check-config`.
+~~~
+
+### 2. Run `nazara register`
+
+To register your device, simply run
+
+```bash
+nazara register
+```
+
+### Common Issues
+
+#### TOML Deserialization Error
+
+This is most likely an issue with your config file.
+Make sure it has correct TOML syntax and all the fields
+specified in the template are present in your example.
+
+#### Unexpected Response
+
+We know this output is ugly but please bear with us we are on it.
+Check the output for a status code:
+
+- **400 - Bad Request**:
+  This usually means that Nazara's payload was rejected by NetBox. Most commonly
+  this means that you want to assign this device to a role, device type or site
+  that does not exist (invalid ID). It can also mean that the device already exists
+  so check if a device with the configured name has already been registered.
+
+#### File OP error
+
+This usually indicates that Nazara cannot open the config file at `/root/.config/nazara/config.toml`
+it's either missing, or you forgot to run Nazara as root.
+
+~~~admonish bug title="Any missing?"
+You have issues with registering your device and don't know how to proceed?
+
+This could be a bug! Please [report it](http://github.com/The-Nazara-Project/Nazara/issues).
+~~~

docs/src/users/update.md

@@ -0,0 +1,71 @@
+# Updating a Device or VM
+
+If you have already registered you Device or VM
+in NetBox, you can update the entry using the
+`nazara update` command.
+
+For this, you need to check if your configuration is still valid and
+up-to-date. Use the `write-config` command to change the info
+you want to update.
+
+~~~admonish info
+This process **also requires `sudo` privileges**, please
+make sure you have them before attempting an update.
+
+This command will try to update **any information**
+that has been changed in a PATCH request.
+Information that has not changed will not be touched.
+~~~
+
+## Example Updating Workflow (Physical Device)
+
+### 1. Update Configuration File
+
+Make sure your config file at `/root/.config/nazara/config.toml`
+is up to date.
+
+If you want to change any parameter you can do so by using the
+`write-config` command.
+
+For example, we want to switch the device's site from `id=1` to `id=2`.
+
+```bash
+sudo nazara write-config --site 2
+```
+
+This will update the entry in the configuration file.
+
+### 2. Update the Entry
+
+Now, to update the entry, go and get the entry's ID from NetBox.
+You can see it in the URL of your browser. In our case:
+`http://localhost:8000/dcim/devices/57/` (device id: 57)
+
+Then simply run
+
+```
+sudo nazara update --id 57
+```
+
+This will then update the entry for you.
+
+### Common Issues
+
+#### IP "X.X.X.X" has not been registered in NetBox
+
+This is a common issue with environments that use DHCP
+with frequently changing IP addresses. In this case the new IP address
+has not been registered with NetBox beforehand, so there is no IP entry to update.
+
+In this case, you must register that new IP manually in NetBox
+as the update process is forbidden from doing so.
+
+Alternatively, you can delete and re-register the device.¹
+
+We are actively working on a managed mode that forbids Nazara's
+IP management alltogether in cases where you have a different source
+of truth for them.
+
+<small>
+¹ Not recommended if you touch your device entries manually.
+</small>