Skip to content

Commit 6a41fa1

Browse files
ByteOtterByteOtter
authored
[Docs:] Update Documentation (#146)
* Update User docs with example workflows * Update Release Workflow doc with WebUI Release Creation checklist
2 parents 07598e3 + 9594083 commit 6a41fa1

File tree

7 files changed

+226
-16
lines changed

7 files changed

+226
-16
lines changed

‎docs/src/SUMMARY.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@
1515
- [Release Workflow](./maintainers/release_workflow.md)
1616
- [API Update Workflow](./maintainers/api_update_workflow.md)
1717
- [User Documentation](./users/index.md)
18-
- [Installation Instructions](./users/installation.md)
18+
- [Install](./users/install.md)
1919
- [Configuration](./users/configuration.md)
20+
- [Registering a Device or VM](./users/registration.md)
21+
- [Updating a Device or VM](./users/update.md)
2022
- [The Plugin System](./users/plugins.md)

‎docs/src/intro.md‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,8 @@
77
Nazara is a Rust tool used to automate the registration and update process of machines and VMs in the
88
IPAM tool [NetBox](https://netboxlabs.com/docs/netbox/).
99

10-
```admonish info
11-
Nazara is currently in it's Beta stage. Bugs are bound to happen.
12-
```
13-
14-
```admonish tip
15-
Found a bug or a typo? [Open an issue on GitHub](https://github.com/The-Nazara-Project/Nazara/issues/new/choose)
10+
```admonish bug title="Found a bug?"
11+
Please [Open an issue on GitHub](https://github.com/The-Nazara-Project/Nazara/issues/new/choose).
1612
```
1713

1814
## Compatibility

‎docs/src/maintainers/release_workflow.md‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,21 @@ In order to be able to publish new versions, you must be given permissions to do
5858
If the publishing fails, please reach out to the Project Owner.
5959
~~~
6060

61-
## 4. Updating Distribution Packages
61+
## 4. Create a New Release
62+
63+
The next step includes creating a new Release via the VC Web UI.
64+
65+
To do so, follow these steps:
66+
67+
- [ ] Select latest tag
68+
- [ ] Select previous tag (if not already done automatically)
69+
- [ ] Press "Generate Release Notes" and split into `Added`, `Fixed`, `Removed` sections
70+
as it seems fitting
71+
- [ ] Describe the core changes of this release in a short `What's new?` section at the top
72+
- [ ] Manually build a `.deb` package using `cargo deb` and attach that and the release
73+
binary to the Release for people who want to manually download it
74+
- [ ] Hit "Create Release"
75+
76+
## 5. Updating Distribution Packages
6277

6378
-- Coming Soon --

‎docs/src/users/install.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Installing Nazara
2+
3+
You can install Nazara in a bunch of different ways.
4+
Our recommended solutions is to either get it from [`crates.io`](https://crates.io/crates/nazara), or
5+
build the latest release from source yourself.
6+
7+
8+
~~~ admonish info title="Native Packages"
9+
We are currently hard at work to build distribution packages in the future with the first one being
10+
targeted at openSUSE Tumbleweed, Slowroll, Leap and SLES16.
11+
12+
If you would like to build a package for your distribution, please [refer to our packager's guide](../contributors/becoming_packager.md).
13+
~~~
14+
15+
## Installing via `crates.io`
16+
17+
To install Nazara via Rust's package index, make sure you have `cargo` and a current Rust toolchain installed.
18+
19+
Then in your Terminal, run
20+
21+
```bash
22+
cargo install --locked nazara
23+
```
24+
25+
After installation you should be able to run Nazara just like you would any other program. If it doesn't work, it is likely
26+
that cargo's bin directory is not in your path. Refer to cargo's documentation for help with that problem.
27+
28+
## Building from Source
29+
30+
For this, please make sure you have cargo, `libopenssl` and a current Rust toolchain installed. (The last of which should be
31+
compatible with Rust edition `2024`).
32+
33+
Simply clone the repository and run `cargo build` to build it yourself.
34+
35+
```bash
36+
git clone https://github.com/The-Nazara-Project/Nazara && cd Nazara
37+
cargo build --release
38+
```
39+
40+
This process may take a while, mainly thanks to our API client library
41+
[thanix_client](https://github.com/The-Nazara-Project/thanix_client).
42+
43+
Once completed you have a portable binary at `./target/release/nazara`.

‎docs/src/users/installation.md‎

Lines changed: 0 additions & 8 deletions
This file was deleted.

‎docs/src/users/registration.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Registering a Device or VM
2+
3+
Registering a device with Nazara is as straight forward as
4+
[setting up the config file](./configuration.md) and running
5+
a simple command.
6+
7+
~~~admonish info
8+
Please make sure you have `sudo` privileges on the machine or VM you want to register, otherwise
9+
DMI information collection **will fail**.
10+
~~~
11+
12+
## Example Registration Workflow (Physical Device)
13+
14+
On a physical device, a example registration workflow may look like this:
15+
16+
### 1. Set up Configuration
17+
18+
The user wrote a configuration file at `/root/.config/nazara/config.toml`
19+
20+
~~~admonish example title="Example: Device Config" collapsible=true
21+
```toml
22+
# Configuration parameters for the NetBox connection
23+
[netbox]
24+
netbox_api_token = "XXXXXXXX"
25+
netbox_uri = "https://netbox.organisation.com"
26+
27+
# Common settings that always have to be provided
28+
[common]
29+
# The name of the device/VM
30+
name = "user@"
31+
description = ""
32+
# A comment left by Nazara if anything gets modified by it.
33+
comments = "Automatically registered by Nazara."
34+
# The current status of the device/VM
35+
status = "active"
36+
primary_ip4 = "192.168.0.1"
37+
primary_ip6 = ""
38+
39+
# ---------------------------------------------------------------
40+
# Use [device] for devices, or [vm] if this is a virtual machine.
41+
# ---------------------------------------------------------------
42+
43+
[device]
44+
device_type = 1
45+
role = 1
46+
site = 1
47+
```
48+
49+
The configuration file for a VM looks quite similarly. For a list
50+
of allowed config parameters, please refer to our [template](https://github.com/The-Nazara-Project/Nazara/blob/main/src/configuration/config_template.toml).
51+
52+
You can verify the integrity of your config by running `nazara check-config`.
53+
~~~
54+
55+
### 2. Run `nazara register`
56+
57+
To register your device, simply run
58+
59+
```bash
60+
nazara register
61+
```
62+
63+
### Common Issues
64+
65+
#### TOML Deserialization Error
66+
67+
This is most likely an issue with your config file.
68+
Make sure it has correct TOML syntax and all the fields
69+
specified in the template are present in your example.
70+
71+
#### Unexpected Response
72+
73+
We know this output is ugly but please bear with us we are on it.
74+
Check the output for a status code:
75+
76+
- **400 - Bad Request**:
77+
This usually means that Nazara's payload was rejected by NetBox. Most commonly
78+
this means that you want to assign this device to a role, device type or site
79+
that does not exist (invalid ID). It can also mean that the device already exists
80+
so check if a device with the configured name has already been registered.
81+
82+
#### File OP error
83+
84+
This usually indicates that Nazara cannot open the config file at `/root/.config/nazara/config.toml`
85+
it's either missing, or you forgot to run Nazara as root.
86+
87+
~~~admonish bug title="Any missing?"
88+
You have issues with registering your device and don't know how to proceed?
89+
90+
This could be a bug! Please [report it](http://github.com/The-Nazara-Project/Nazara/issues).
91+
~~~

‎docs/src/users/update.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Updating a Device or VM
2+
3+
If you have already registered you Device or VM
4+
in NetBox, you can update the entry using the
5+
`nazara update` command.
6+
7+
For this, you need to check if your configuration is still valid and
8+
up-to-date. Use the `write-config` command to change the info
9+
you want to update.
10+
11+
~~~admonish info
12+
This process **also requires `sudo` privileges**, please
13+
make sure you have them before attempting an update.
14+
15+
This command will try to update **any information**
16+
that has been changed in a PATCH request.
17+
Information that has not changed will not be touched.
18+
~~~
19+
20+
## Example Updating Workflow (Physical Device)
21+
22+
### 1. Update Configuration File
23+
24+
Make sure your config file at `/root/.config/nazara/config.toml`
25+
is up to date.
26+
27+
If you want to change any parameter you can do so by using the
28+
`write-config` command.
29+
30+
For example, we want to switch the device's site from `id=1` to `id=2`.
31+
32+
```bash
33+
sudo nazara write-config --site 2
34+
```
35+
36+
This will update the entry in the configuration file.
37+
38+
### 2. Update the Entry
39+
40+
Now, to update the entry, go and get the entry's ID from NetBox.
41+
You can see it in the URL of your browser. In our case:
42+
`http://localhost:8000/dcim/devices/57/` (device id: 57)
43+
44+
Then simply run
45+
46+
```
47+
sudo nazara update --id 57
48+
```
49+
50+
This will then update the entry for you.
51+
52+
### Common Issues
53+
54+
#### IP "X.X.X.X" has not been registered in NetBox
55+
56+
This is a common issue with environments that use DHCP
57+
with frequently changing IP addresses. In this case the new IP address
58+
has not been registered with NetBox beforehand, so there is no IP entry to update.
59+
60+
In this case, you must register that new IP manually in NetBox
61+
as the update process is forbidden from doing so.
62+
63+
Alternatively, you can delete and re-register the device.¹
64+
65+
We are actively working on a managed mode that forbids Nazara's
66+
IP management alltogether in cases where you have a different source
67+
of truth for them.
68+
69+
<small>
70+
¹ Not recommended if you touch your device entries manually.
71+
</small>

0 commit comments

Comments
 (0)