Nasqueron Agora - User contributions [en]

User:Dereckson/Arcane Grove/BlueDrake

2026-08-05T01:57:11Z

Dereckson: /* Components */

'''BlueDrake''' is the name of the hybrid productivity-gaming workstation.

== Hardware ==
=== Components ===
{| class="wikitable sortable"
|+ BlueDrake parts
|-
! Category !! Brand !! Model !! Links
|-
| Case || Lian Li || [https://lian-li.com/product/lancool-iii/ Lancool III] || [https://drive.google.com/file/d/1kd9ku_raF2uXWeLD7voGfT4ZZ10XOizy/view?usp=sharing 📖]
|-
| Motherboard || Asus || [https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/ ROG Strix B650E-E Gaming WiFi] || [https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/helpdesk_manual/ 📖] [https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/helpdesk_download/ 📥]
|-
| CPU || AMD || [https://www.amd.com/en/products/processors/desktops/ryzen/7000-series/amd-ryzen-9-7900x.html Ryzen 9 7900X] || [https://www.amd.com/en/support/downloads/drivers.html/processors/ryzen/ryzen-7000-series/amd-ryzen-9-7900x.html 📥]
|-
| CPU Cooler || Noctua || [https://noctua.at/en/nh-d15s NH-D15S] || [https://noctua.at/en/nh-d15s/manuals 📖]
|-
| GPU || Sapphire / AMD || PURE Radeon RX 7700 XT 12GB || [https://www.sapphiretech.com/en/consumer/pure-radeon-rx-7700-xt-12g-gddr6-frostpunk2 📖]
|-
| RAM || G.Skill || Trident Z Neo DDR5 96 GB (2×48 GB) || [https://www.gskill.com/product/165/374/1682577390/F5-5600J4040D48GX2-TZ5RK 📖]
|-
| Storage || Kingston || Fury Renegade 2 TB NVMe M.2 (×2) || [https://www.kingston.com/en/ssd/gaming/fury-renegade-nvme-pcie-ssd 📖]
|-
| PSU || Seasonic || Core GX-750 || [https://seasonic.com/core-gx#specification 📖]
|-
| Screen || Alienware || AW3425DWM || [https://dl.dell.com/content/manual56809116-alienware-34-gaming-monitor-aw3425dwm-quick-start-guide.pdf?language=en-us 📖]
|}

== Software ==
=== FreeBSD ===
Things to check for GPU:
* Ollama on FreeBSD -> https://www.reddit.com/r/freebsd/comments/1d3hmmz/comment/lqiulx9/ / https://github.com/ollama/ollama/pull/4172 (<code>pkg install go122 cmake vulkan-headers vulkan-loader</code>)
* GPU passthrough with bhyve -> https://wiki.freebsd.org/bhyve/pci_passthru

User:Dereckson/Arcane Grove/BlueDrake

2026-08-05T01:54:47Z

Dereckson: /* Components */

'''BlueDrake''' is the name of the hybrid productivity-gaming workstation.

== Hardware ==
=== Components ===
{| class="wikitable sortable"
|+ BlueDrake parts
|-
! Category !! Brand !! Model !! Links
|-
| Case || Lian Li || [https://lian-li.com/product/lancool-iii/ Lancool III] || [https://drive.google.com/file/d/1kd9ku_raF2uXWeLD7voGfT4ZZ10XOizy/view?usp=sharing 📖]
|-
| Motherboard || Asus || [https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/ ROG Strix B650E-E Gaming WiFi] || [https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/helpdesk_manual/ 📖] [https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/helpdesk_download/ 📥]
|-
| CPU || AMD || Ryzen 9 7900X || [https://www.amd.com/en/products/cpu/amd-ryzen-9-7900x 📖]
|-
| CPU Cooler || Noctua || [https://noctua.at/en/nh-d15s NH-D15S] || [https://noctua.at/en/nh-d15s/manuals 📖]
|-
| GPU || Sapphire / AMD || PURE Radeon RX 7700 XT 12GB || [https://www.sapphiretech.com/en/consumer/pure-radeon-rx-7700-xt-12g-gddr6-frostpunk2 📖]
|-
| RAM || G.Skill || Trident Z Neo DDR5 96 GB (2×48 GB) || [https://www.gskill.com/product/165/374/1682577390/F5-5600J4040D48GX2-TZ5RK 📖]
|-
| Storage || Kingston || Fury Renegade 2 TB NVMe M.2 (×2) || [https://www.kingston.com/en/ssd/gaming/fury-renegade-nvme-pcie-ssd 📖]
|-
| PSU || Seasonic || Core GX-750 || [https://seasonic.com/core-gx#specification 📖]
|-
| Screen || AOC || C27G1 || [https://aoc.com/be-fr/gaming/products/monitors/c27g1/downloads 📥]
|-
| Screen || Alienware || AW3425DWM || [https://dl.dell.com/content/manual56809116-alienware-34-gaming-monitor-aw3425dwm-quick-start-guide.pdf?language=en-us 📖]
|}

== Software ==
=== FreeBSD ===
Things to check for GPU:
* Ollama on FreeBSD -> https://www.reddit.com/r/freebsd/comments/1d3hmmz/comment/lqiulx9/ / https://github.com/ollama/ollama/pull/4172 (<code>pkg install go122 cmake vulkan-headers vulkan-loader</code>)
* GPU passthrough with bhyve -> https://wiki.freebsd.org/bhyve/pci_passthru

User:Dereckson/Arcane Grove/BlueDrake

2026-08-05T01:54:09Z

Dereckson: /* Components */

'''BlueDrake''' is the name of the hybrid productivity-gaming workstation.

== Hardware ==
=== Components ===
{| class="wikitable sortable"
|+ BlueDrake parts
|-
! Category !! Brand !! Model !! Links
|-
| Case || Lian Li || [https://lian-li.com/product/lancool-iii/ Lancool III] || [https://drive.google.com/file/d/1kd9ku_raF2uXWeLD7voGfT4ZZ10XOizy/view?usp=sharing 📖]
|-
| Motherboard || Asus || [https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/ ROG Strix B650E-E Gaming WiFi] || [https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/helpdesk_manual/ 📖] [https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/helpdesk_download/ 📥]
|-
| CPU || AMD || Ryzen 9 7900X || [https://www.amd.com/en/products/cpu/amd-ryzen-9-7900x 📖]
|-
| CPU Cooler || Noctua || NH-D15S || [https://noctua.at/en/nh-d15s 📝] [https://noctua.at/en/nh-d15s/manuals 📖]
|-
| GPU || Sapphire / AMD || PURE Radeon RX 7700 XT 12GB || [https://www.sapphiretech.com/en/consumer/pure-radeon-rx-7700-xt-12g-gddr6-frostpunk2 📖]
|-
| RAM || G.Skill || Trident Z Neo DDR5 96 GB (2×48 GB) || [https://www.gskill.com/product/165/374/1682577390/F5-5600J4040D48GX2-TZ5RK 📖]
|-
| Storage || Kingston || Fury Renegade 2 TB NVMe M.2 (×2) || [https://www.kingston.com/en/ssd/gaming/fury-renegade-nvme-pcie-ssd 📖]
|-
| PSU || Seasonic || Core GX-750 || [https://seasonic.com/core-gx#specification 📖]
|-
| Screen || AOC || C27G1 || [https://aoc.com/be-fr/gaming/products/monitors/c27g1/downloads 📥]
|-
| Screen || Alienware || AW3425DWM || [https://dl.dell.com/content/manual56809116-alienware-34-gaming-monitor-aw3425dwm-quick-start-guide.pdf?language=en-us 📖]
|}

== Software ==
=== FreeBSD ===
Things to check for GPU:
* Ollama on FreeBSD -> https://www.reddit.com/r/freebsd/comments/1d3hmmz/comment/lqiulx9/ / https://github.com/ollama/ollama/pull/4172 (<code>pkg install go122 cmake vulkan-headers vulkan-loader</code>)
* GPU passthrough with bhyve -> https://wiki.freebsd.org/bhyve/pci_passthru

User:Dereckson/Arcane Grove/BlueDrake

2026-08-05T01:53:04Z

Dereckson: /* Components */

'''BlueDrake''' is the name of the hybrid productivity-gaming workstation.

== Hardware ==
=== Components ===
{| class="wikitable sortable"
|+ BlueDrake parts
|-
! Category !! Brand !! Model !! Links
|-
| Case || Lian Li || [https://lian-li.com/product/lancool-iii/ Lancool III] || [https://drive.google.com/file/d/1kd9ku_raF2uXWeLD7voGfT4ZZ10XOizy/view?usp=sharing 📖]
|-
| Motherboard || Asus || [https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/ ROG Strix B650E-E Gaming WiFi] || [https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/helpdesk_manual/ 📖] [https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/helpdesk_download/ 📥]
|-
| CPU || AMD || Ryzen 9 7900X || [https://www.amd.com/en/products/cpu/amd-ryzen-9-7900x 📖]
|-
| CPU Cooler || Noctua || NH-D15S || [https://noctua.at/en/nh-d15s 📖] [https://noctua.at/en/nh-d15s/manuals
|-
| GPU || Sapphire / AMD || PURE Radeon RX 7700 XT 12GB || [https://www.sapphiretech.com/en/consumer/pure-radeon-rx-7700-xt-12g-gddr6-frostpunk2 📖]
|-
| RAM || G.Skill || Trident Z Neo DDR5 96 GB (2×48 GB) || [https://www.gskill.com/product/165/374/1682577390/F5-5600J4040D48GX2-TZ5RK 📖]
|-
| Storage || Kingston || Fury Renegade 2 TB NVMe M.2 (×2) || [https://www.kingston.com/en/ssd/gaming/fury-renegade-nvme-pcie-ssd 📖]
|-
| PSU || Seasonic || Core GX-750 || [https://seasonic.com/core-gx#specification 📖]
|-
| Screen || AOC || C27G1 || [https://aoc.com/be-fr/gaming/products/monitors/c27g1/downloads 📥]
|-
| Screen || Alienware || AW3425DWM || [https://dl.dell.com/content/manual56809116-alienware-34-gaming-monitor-aw3425dwm-quick-start-guide.pdf?language=en-us 📖]
|}

== Software ==
=== FreeBSD ===
Things to check for GPU:
* Ollama on FreeBSD -> https://www.reddit.com/r/freebsd/comments/1d3hmmz/comment/lqiulx9/ / https://github.com/ollama/ollama/pull/4172 (<code>pkg install go122 cmake vulkan-headers vulkan-loader</code>)
* GPU passthrough with bhyve -> https://wiki.freebsd.org/bhyve/pci_passthru

Operations grimoire/Deploy with Terraform

2026-07-23T13:19:56Z

Dereckson: /* Troubleshoot */ Document tofu state rm

== Where to work? ==
We deploy from [[Complector]] using <code>/opt/salt/nasqueron-operations</code> as our local copy of rOPS, authoritative for both Salt and Terraform

You need to belong to the <code>ops</code> group to be able to have access and have write-rights on the repository

It's important to work from there to save a shared Terraform state.

== Specific deployment notes ==
=== Vault / OpenBao ===
==== General notes ====
;OpenTofu support
As of 2026-02-07, the Vault provider isn't compiled for FreeBSD. You need to use Terraform instead.

;Vault
You need a Vault token to allow the provider to connect.

You also need to set VAULT_ADDR to https://172.27.27.7:8200 as Vault doesn't listen on 127.0.0.1

<syntaxhighlight lang="shell">
$ export VAULT_ADDR=https://172.27.27.7:8200
$ sudo /opt/salt/nasqueron-operations/utils/vault/issue-admin-token.py > ~/.vault-token

$ cd /opt/salt/nasqueron-operations/terraform/openbao
$ terraform init # if you've a new entry requiring a module, it needs to be installed
$ terraform plan
$ terraform apply
</syntaxhighlight>

It could be interesting to maintain an alternative policy to admin for the Terraform provider, restricted to the current actions. Note benefits would be limited as those include policies management.

==== Propagate secrets (DRP) ====
;No automatic secret rotation
Secrets rotation is disabled with a lifecycle management <code>ignore_changes = [ secret_id, ]</code>.

To rotate a secret, it needs first to be destroyed from terraform state:
<code>terraform destroy -target=module.viperserv_approle.vault_approle_auth_backend_role_secret_id.this</code>

;Full procedure
Once the AppRole have been created in Vault, they need to be provisioned to the relevant configuration files.

<syntaxhighlight lang="shell">
$ cd /opt/salt/nasqueron-operations/terraform/openbao
$ terraform init # if you've a new entry requiring a module, it needs to be installed
$ terraform plan
$ terraform apply

$ cd /opt/salt/nasqueron-operations
$ salt windriver state.sls_id /usr/local/etc/secrets/rhyne-wyse.yaml roles/reports/rhyne-wyse/config
$ salt windriver state.sls_id /srv/viperserv/.credentials roles/viperserv/eggdrop/config
# Missing for router
</syntaxhighlight>

<div class="alert">Important. Each time you'll reprovision the secrets, they will change.

Don't forget to always apply this full procedure.
</div>

=== CARP OVH secrets usage ===

The OVH credentials used by the CARP failover script are stored in Vault at:

'''apps/network/carp-hyper-001-switch'''

These credentials are accessed by router-002 and router-003. They are then used by a script triggered by devd to update the OVH failover IP MAC address depending on the CARP state (MASTER/BACKUP). The script authenticates to Vault using AppRole (via secretsmith) to retrieve them.

The AppRole credentials (role_id and secret_id) used by the script are stored in:

'''ops/secrets/network/router/vault'''

Vault secrets are provisioned using Terraform (openbao module), and must be propagated to the routers using Salt.

The Vault Secrets may need to be rotated, so we need a simple way to propagate
updated credentials to routers. This is enabled by the mechanism
introduced in D4026.

== Table of Terraform states ==

{| class="wikitable"
|+ Terraform and OpenBao states
|-
! Configuration !! State back-end !! Path !! Software to use
|-
| openbao || On disk || /opt/salt/nasqueron-operations/terraform/openbao/terraform.tfstate || Terraform
|}

On disk paths are stored in Complector.

== Troubleshoot ==
=== Error: Module not installed ===

You need to run <code>tofu init</code> to prepare for any new provider.

<syntaxhighlight lang="shell">
$ tofu plan

│ Error: Module not installed
│
│ on rhyne_wyse.tf line 23:
│ 23: module "rhyne_wyse_approle" {
│
│ This module is not yet installed. Run "tofu init" to install all modules required by this configuration.
</syntaxhighlight>

=== Error: Incompatible provider version ===

<syntaxhighlight lang="shell">
$ tofu init

Initializing the backend...
Initializing modules...
- rhyne_wyse_approle in modules/app_credentials

Initializing provider plugins...
- Finding hashicorp/vault versions matching "5.3.0"...
╷
│ Error: Incompatible provider version
│
│ Provider registry.opentofu.org/hashicorp/vault v5.3.0 does not have a package available for your current platform, freebsd_amd64.
│
│ Provider releases are separate from OpenTofu CLI releases, so not all providers are available for all platforms. Other versions of this provider may have different platforms supported.
</syntaxhighlight>

On OpenTofu, some modules are only compiled for Linux, not for FreeBSD.
Switch to Terraform pending a solution to help the OpenTofu builds.

=== State rollback ===

When declaring new Terraform resources, it's possible to remove from the state an item, without actually destroying it at infrastructure level:

$ tofu state rm <state name>
Removed ….…
Successfully removed 1 resource instance(s).

[[Category:Operations grimoire]]
[[Category:Terraform]]

Operations grimoire/Operations repository

2026-07-18T20:43:06Z

Dereckson: /* Python dependencies */ Works on Linux too

Our configuration as code is stores in the operations (rOPS) repository.

== Repository layout ==
{| class="wikitable sortable"
|+ Content of rOPS
|-
! Path !! Description
|-
| _modules || Custom execution modules
|-
| _states || Custom states modules
|-
| _tests || Unit tests for custom modules, scripts, tests for repo
|-
| hotfixes || Fixes you need to run to solve a problem on the servers
|-
| pillar || Configuration data structures to use in the states
|-
| roles || The states to deploy, divided in roles and then in units
|-
| utils || Helper scripts to maintain the repository
|-
| terraform || OpenTofu / Terraform infrastructure configuration
|-
| map.jinja || As we deploy on several OS and distros, mapping of packages names or directories
|-
| top.sls || topfile: what we deploy where?
|-
| PORTS || Documentation of the ports used in the configuration
|-
| UIDs || Documentation of the users used in the configuration
|-
| GIDs || Documentation of the groups used in the configuration
|}

== Contributions howto ==
=== Repository source ===
You'll find the Operations repository at https://devcentral.nasqueron.org/source/operations/

If DevCentral isn't available, a mirror of the repository can be found at https://github.com/nasqueron/operations.

=== Workflow of contributions ===
We follow the general workflow is described at [[How to contribute code]].

Before committing a change to the main branch, you can test a deployment on a server.
In that case, merge in main immediately after the deployment as the repository is the source of truth for the server state.

Log what you do on #nasqueron-ops, so it will be included at https://infra.nasqueron.org/servers-log/

=== Code conventions ===
''See also: [[Code conventions]].''

* Python code: run `black` before committing
* YAML: indent with two spaces, including list bullets

<syntaxhighlight lang="yaml">
id:
method:
- somekey: value
- otherkey: value
</syntaxhighlight>

== Environment setup ==

Use of WindRiver is recommended if you wish to get an environment already installed for your contributions.

=== Everywhere setup ===
This section cover topics needed both on our development servers or in your laptop.

==== Python dependencies ====

Create a virtual environment, then install dependencies from {{Ops file|requirements.txt}}:

mkdir -p $HOME/dev/python/ops
python3 -m venv $HOME/dev/python/ops
source $HOME/dev/python/ops/bin/activate
pip install -r requirements.txt

As of July 2026, it seems possible to also install Salt in the virtual environment and run tests:

pip install salt==3006.26
make test

(tested on WindRiver: with FreeBSD 15.1, Python 3.12.13, Salt 3006.26)
(tested on local workstation BlueDrake: with Fedora 42 Python 3.13.13, Salt 3006.26)

==== Datacube ====

If you're in the ops group, you'll need sometimes to deploy from branches. As our deployment server Complector doesn't have PHP installed (so no arc), you need to exchange branches through our datacube.

On WindRiver:

git remote add datacube /datacube/git/operations.git

Anywhere else:

git remote add datacube ssh://windriver.nasqueron.org/datacube/git/operations.git

If you aren't in the ops groups, and have access to our devserver, you'll still be able to clone or pull from that directory, but not to write there (ie push branches).

=== Local computer setup ===

This section cover topics NOT needed on our development servers.

==== macOS ====

To run tests properly, install first:

brew install bats
brew install python3.13

You can now setup the virtual environment per everywhere setup instructions.

Salt behaves correctly on macOS, so you can install it safely in the virtual environment:

pip install salt==3006.26

Check the version on WindRiver or Complector with <code>salt --versions</code>.

Finally, to run the tests, you need a recent version of make, but the BSD make currently shipped, as of Tahoe 26.5, isn't up-to-date:

brew install gmake
(cd _tests && gmake)

==== Arcanist ====

To use arc with the operations repository, our collection of patches is needed.

If arcanist isn't installed through Git repository, best is to do like on devserver role:

mkdir /opt/phabricator && cd /opt/phabricator
git clone https://github.com/nasqueron/arcanist.git
(cd arcanist && git checkout production)
ln -s /opt/phabricator/arcanist/bin/arc /usr/local/bin/
git clone https://devcentral.nasqueron.org/source/shellcheck-linter.git

If you've already cloned Arcanist repository, switch to our branch production:

git remote add nasqueron git@github.com:nasqueron/arcanist.git
git fetch --all
git checkout production

As of August 2024, there is no plan to make that repository available on DevCentral.

You'll also need shellcheck library-linter library, normally at the same level than your arcanist repository.

==== IDE configuration ====
[[File:PyCharm-TemplateLanguages.png|thumb|right|Screenshot of correctly configured template languages]]
The states .sls file are Jinja2 templates producing YAML files, or "jinja2+yaml". If this case can't be handled by your IDE, it works best to use YAML syntax highlighting.

If you use PyCharm or IntelliJ IDEA Ultimate, you can configure this scheme:

* Allow YAML files to be Jinja2 templates
** Go to Settings > Languages & Frameworks > Template Languages
** Select Jinja2 as template language
** Add YAML in the list
* Open SLS as YAML

== Linting ==

=== pre-commit ===
You can use '''pre-commit''' you can install with <code>make</code> to get a hook running Python code to lint the repository before a commit.

Beware if you use <code>arc diff</code> without a commit first: your message will be lost if pre-commit raises an error, always use <code>git commit</code> first.

On FreeBSD, there is an issue to build with clang 16+ the ruamel yaml clib library. You can build the FreeBSD port devel/py-ruamel.yaml.clib and copy the .whl to a stable path, then install it in your virtual environment.

On WindRiver, the .whl is available in /opt/python/py311, so you can:

$ python3 -m venv /path/to/your/virtualenv
$ source /path/to/your/virtualenv/bin/activate
$ pip install /opt/python/py311/ruamel.yaml.clib-0.2.8-cp311-cp311-freebsd_14_0_release_p3_amd64.whl
$ pip install pre-commit
$ make
pre-commit install
pre-commit installed at .git/hooks/pre-commit
$ rehash
$ pre-commit

== Refactoring ==

=== Rename a lot of files ===

To move a directory and rename the ''Source file'' headers:

git mv roles/webserver-legacy/nginx/files roles/webserver-alkane/nginx/
cd roles/webserver-alkane/nginx/
find . -type f -name '*.conf' | xargs gsed -i s/webserver-legacy/webserver-alkane/g

== See also ==
* [[/FAQ]] - Frequently asked questions about the Operations repository
* [[How to contribute code]]
* [[Devserver reference]]

Operations grimoire/Operations repository

2026-07-18T20:40:18Z

Dereckson: /* Python dependencies */

Our configuration as code is stores in the operations (rOPS) repository.

== Repository layout ==
{| class="wikitable sortable"
|+ Content of rOPS
|-
! Path !! Description
|-
| _modules || Custom execution modules
|-
| _states || Custom states modules
|-
| _tests || Unit tests for custom modules, scripts, tests for repo
|-
| hotfixes || Fixes you need to run to solve a problem on the servers
|-
| pillar || Configuration data structures to use in the states
|-
| roles || The states to deploy, divided in roles and then in units
|-
| utils || Helper scripts to maintain the repository
|-
| terraform || OpenTofu / Terraform infrastructure configuration
|-
| map.jinja || As we deploy on several OS and distros, mapping of packages names or directories
|-
| top.sls || topfile: what we deploy where?
|-
| PORTS || Documentation of the ports used in the configuration
|-
| UIDs || Documentation of the users used in the configuration
|-
| GIDs || Documentation of the groups used in the configuration
|}

== Contributions howto ==
=== Repository source ===
You'll find the Operations repository at https://devcentral.nasqueron.org/source/operations/

If DevCentral isn't available, a mirror of the repository can be found at https://github.com/nasqueron/operations.

=== Workflow of contributions ===
We follow the general workflow is described at [[How to contribute code]].

Before committing a change to the main branch, you can test a deployment on a server.
In that case, merge in main immediately after the deployment as the repository is the source of truth for the server state.

Log what you do on #nasqueron-ops, so it will be included at https://infra.nasqueron.org/servers-log/

=== Code conventions ===
''See also: [[Code conventions]].''

* Python code: run `black` before committing
* YAML: indent with two spaces, including list bullets

<syntaxhighlight lang="yaml">
id:
method:
- somekey: value
- otherkey: value
</syntaxhighlight>

== Environment setup ==

Use of WindRiver is recommended if you wish to get an environment already installed for your contributions.

=== Everywhere setup ===
This section cover topics needed both on our development servers or in your laptop.

==== Python dependencies ====

Create a virtual environment, then install dependencies from {{Ops file|requirements.txt}}:

mkdir -p $HOME/dev/python/ops
python3 -m venv $HOME/dev/python/ops
source $HOME/dev/python/ops/bin/activate
pip install -r requirements.txt

As of July 2026, it seems possible to also install Salt in the virtual environment and run tests:

pip install salt==3006.26
make test

(tested on WindRiver, so with FreeBSD 15.1, Python 3.12.13, Salt 3006.26)

==== Datacube ====

If you're in the ops group, you'll need sometimes to deploy from branches. As our deployment server Complector doesn't have PHP installed (so no arc), you need to exchange branches through our datacube.

On WindRiver:

git remote add datacube /datacube/git/operations.git

Anywhere else:

git remote add datacube ssh://windriver.nasqueron.org/datacube/git/operations.git

If you aren't in the ops groups, and have access to our devserver, you'll still be able to clone or pull from that directory, but not to write there (ie push branches).

=== Local computer setup ===

This section cover topics NOT needed on our development servers.

==== macOS ====

To run tests properly, install first:

brew install bats
brew install python3.13

You can now setup the virtual environment per everywhere setup instructions.

Salt behaves correctly on macOS, so you can install it safely in the virtual environment:

pip install salt==3006.26

Check the version on WindRiver or Complector with <code>salt --versions</code>.

Finally, to run the tests, you need a recent version of make, but the BSD make currently shipped, as of Tahoe 26.5, isn't up-to-date:

brew install gmake
(cd _tests && gmake)

==== Arcanist ====

To use arc with the operations repository, our collection of patches is needed.

If arcanist isn't installed through Git repository, best is to do like on devserver role:

mkdir /opt/phabricator && cd /opt/phabricator
git clone https://github.com/nasqueron/arcanist.git
(cd arcanist && git checkout production)
ln -s /opt/phabricator/arcanist/bin/arc /usr/local/bin/
git clone https://devcentral.nasqueron.org/source/shellcheck-linter.git

If you've already cloned Arcanist repository, switch to our branch production:

git remote add nasqueron git@github.com:nasqueron/arcanist.git
git fetch --all
git checkout production

As of August 2024, there is no plan to make that repository available on DevCentral.

You'll also need shellcheck library-linter library, normally at the same level than your arcanist repository.

==== IDE configuration ====
[[File:PyCharm-TemplateLanguages.png|thumb|right|Screenshot of correctly configured template languages]]
The states .sls file are Jinja2 templates producing YAML files, or "jinja2+yaml". If this case can't be handled by your IDE, it works best to use YAML syntax highlighting.

If you use PyCharm or IntelliJ IDEA Ultimate, you can configure this scheme:

* Allow YAML files to be Jinja2 templates
** Go to Settings > Languages & Frameworks > Template Languages
** Select Jinja2 as template language
** Add YAML in the list
* Open SLS as YAML

== Linting ==

=== pre-commit ===
You can use '''pre-commit''' you can install with <code>make</code> to get a hook running Python code to lint the repository before a commit.

Beware if you use <code>arc diff</code> without a commit first: your message will be lost if pre-commit raises an error, always use <code>git commit</code> first.

On FreeBSD, there is an issue to build with clang 16+ the ruamel yaml clib library. You can build the FreeBSD port devel/py-ruamel.yaml.clib and copy the .whl to a stable path, then install it in your virtual environment.

On WindRiver, the .whl is available in /opt/python/py311, so you can:

$ python3 -m venv /path/to/your/virtualenv
$ source /path/to/your/virtualenv/bin/activate
$ pip install /opt/python/py311/ruamel.yaml.clib-0.2.8-cp311-cp311-freebsd_14_0_release_p3_amd64.whl
$ pip install pre-commit
$ make
pre-commit install
pre-commit installed at .git/hooks/pre-commit
$ rehash
$ pre-commit

== Refactoring ==

=== Rename a lot of files ===

To move a directory and rename the ''Source file'' headers:

git mv roles/webserver-legacy/nginx/files roles/webserver-alkane/nginx/
cd roles/webserver-alkane/nginx/
find . -type f -name '*.conf' | xargs gsed -i s/webserver-legacy/webserver-alkane/g

== See also ==
* [[/FAQ]] - Frequently asked questions about the Operations repository
* [[How to contribute code]]
* [[Devserver reference]]

Operations grimoire/Operations repository

2026-07-18T20:38:54Z

Dereckson: /* macOS */ -> .26

Our configuration as code is stores in the operations (rOPS) repository.

== Repository layout ==
{| class="wikitable sortable"
|+ Content of rOPS
|-
! Path !! Description
|-
| _modules || Custom execution modules
|-
| _states || Custom states modules
|-
| _tests || Unit tests for custom modules, scripts, tests for repo
|-
| hotfixes || Fixes you need to run to solve a problem on the servers
|-
| pillar || Configuration data structures to use in the states
|-
| roles || The states to deploy, divided in roles and then in units
|-
| utils || Helper scripts to maintain the repository
|-
| terraform || OpenTofu / Terraform infrastructure configuration
|-
| map.jinja || As we deploy on several OS and distros, mapping of packages names or directories
|-
| top.sls || topfile: what we deploy where?
|-
| PORTS || Documentation of the ports used in the configuration
|-
| UIDs || Documentation of the users used in the configuration
|-
| GIDs || Documentation of the groups used in the configuration
|}

== Contributions howto ==
=== Repository source ===
You'll find the Operations repository at https://devcentral.nasqueron.org/source/operations/

If DevCentral isn't available, a mirror of the repository can be found at https://github.com/nasqueron/operations.

=== Workflow of contributions ===
We follow the general workflow is described at [[How to contribute code]].

Before committing a change to the main branch, you can test a deployment on a server.
In that case, merge in main immediately after the deployment as the repository is the source of truth for the server state.

Log what you do on #nasqueron-ops, so it will be included at https://infra.nasqueron.org/servers-log/

=== Code conventions ===
''See also: [[Code conventions]].''

* Python code: run `black` before committing
* YAML: indent with two spaces, including list bullets

<syntaxhighlight lang="yaml">
id:
method:
- somekey: value
- otherkey: value
</syntaxhighlight>

== Environment setup ==

Use of WindRiver is recommended if you wish to get an environment already installed for your contributions.

=== Everywhere setup ===
This section cover topics needed both on our development servers or in your laptop.

==== Python dependencies ====

Create a virtual environment, then install dependencies from {{Ops file|requirements.txt}}:

mkdir -p $HOME/dev/python/ops
python3 -m venv $HOME/dev/python/ops
source $HOME/dev/python/ops/bin/activate
pip install -r requirements.txt

==== Datacube ====

If you're in the ops group, you'll need sometimes to deploy from branches. As our deployment server Complector doesn't have PHP installed (so no arc), you need to exchange branches through our datacube.

On WindRiver:

git remote add datacube /datacube/git/operations.git

Anywhere else:

git remote add datacube ssh://windriver.nasqueron.org/datacube/git/operations.git

If you aren't in the ops groups, and have access to our devserver, you'll still be able to clone or pull from that directory, but not to write there (ie push branches).

=== Local computer setup ===

This section cover topics NOT needed on our development servers.

==== macOS ====

To run tests properly, install first:

brew install bats
brew install python3.13

You can now setup the virtual environment per everywhere setup instructions.

Salt behaves correctly on macOS, so you can install it safely in the virtual environment:

pip install salt==3006.26

Check the version on WindRiver or Complector with <code>salt --versions</code>.

Finally, to run the tests, you need a recent version of make, but the BSD make currently shipped, as of Tahoe 26.5, isn't up-to-date:

brew install gmake
(cd _tests && gmake)

==== Arcanist ====

To use arc with the operations repository, our collection of patches is needed.

If arcanist isn't installed through Git repository, best is to do like on devserver role:

mkdir /opt/phabricator && cd /opt/phabricator
git clone https://github.com/nasqueron/arcanist.git
(cd arcanist && git checkout production)
ln -s /opt/phabricator/arcanist/bin/arc /usr/local/bin/
git clone https://devcentral.nasqueron.org/source/shellcheck-linter.git

If you've already cloned Arcanist repository, switch to our branch production:

git remote add nasqueron git@github.com:nasqueron/arcanist.git
git fetch --all
git checkout production

As of August 2024, there is no plan to make that repository available on DevCentral.

You'll also need shellcheck library-linter library, normally at the same level than your arcanist repository.

==== IDE configuration ====
[[File:PyCharm-TemplateLanguages.png|thumb|right|Screenshot of correctly configured template languages]]
The states .sls file are Jinja2 templates producing YAML files, or "jinja2+yaml". If this case can't be handled by your IDE, it works best to use YAML syntax highlighting.

If you use PyCharm or IntelliJ IDEA Ultimate, you can configure this scheme:

* Allow YAML files to be Jinja2 templates
** Go to Settings > Languages & Frameworks > Template Languages
** Select Jinja2 as template language
** Add YAML in the list
* Open SLS as YAML

== Linting ==

=== pre-commit ===
You can use '''pre-commit''' you can install with <code>make</code> to get a hook running Python code to lint the repository before a commit.

Beware if you use <code>arc diff</code> without a commit first: your message will be lost if pre-commit raises an error, always use <code>git commit</code> first.

On FreeBSD, there is an issue to build with clang 16+ the ruamel yaml clib library. You can build the FreeBSD port devel/py-ruamel.yaml.clib and copy the .whl to a stable path, then install it in your virtual environment.

On WindRiver, the .whl is available in /opt/python/py311, so you can:

$ python3 -m venv /path/to/your/virtualenv
$ source /path/to/your/virtualenv/bin/activate
$ pip install /opt/python/py311/ruamel.yaml.clib-0.2.8-cp311-cp311-freebsd_14_0_release_p3_amd64.whl
$ pip install pre-commit
$ make
pre-commit install
pre-commit installed at .git/hooks/pre-commit
$ rehash
$ pre-commit

== Refactoring ==

=== Rename a lot of files ===

To move a directory and rename the ''Source file'' headers:

git mv roles/webserver-legacy/nginx/files roles/webserver-alkane/nginx/
cd roles/webserver-alkane/nginx/
find . -type f -name '*.conf' | xargs gsed -i s/webserver-legacy/webserver-alkane/g

== See also ==
* [[/FAQ]] - Frequently asked questions about the Operations repository
* [[How to contribute code]]
* [[Devserver reference]]

Operations grimoire/External services

2026-07-05T13:16:15Z

Dereckson: /* JetBrains */

== Amazon Web Services (AWS) ==
S3, account managed by Sandlayth.

== Docker Hub ==
Organization account, administrative access by Sandlayth and Dereckson.

2021-09-12: request for open source as part of the https://www.docker.com/blog/expanded-support-for-open-source-software-projects done, mainly as automated builds have been disabled in the free team plan.

== GeoLite2 ==
Account at MaxMind for GeoLite2 databases, created by Dereckson.

Account credentials stored in Vault under <code>ops/infra/maxmind</code>.
There aren't the API credentials, for example Sentry ones are stored at <code>ops/secrets/nasqueron/sentry/geoipupdate</code>.

== Gandi ==
Some domains names:
* eglide.org, account managed by Sandlayth
* ook.space, account managed by Dereckson

== GitHub ==
;Organization account
:Administrative access by Sandlayth and Dereckson
:''Some OAuth could be on Dereckson account. When found, should be switched to Nasqueron (see [https://devcentral.nasqueron.org/T1109 T1109]).''

;Alken-Orin
:As automated agent, there is an '''Alken-Orin''' account to link GitHub to CI/CD.
:This account is also used to fetch code from GitHub through the `staging_private_repository` Salt state. To that end, the Salt deploy SSH key is added to this account.
:Credentials at [https://devcentral.nasqueron.org/K53 K53].

== Google ==
OAuth for DevCentral, account managed by Dereckson (under espace-win.org Google Apps organization)

== Hurricane Electric ==
IPv6 connectivity, DNS for nasqueron.org: account 'nasqueron'.

'''Note:''' DNS for some other domains are currently handled on the 'dereckson' account, they'll be moved to 'nasqueron' account when defined as secondary.

== instances.mastodon.xyz ==
Credentials for this account are stored in [https://devcentral.nasqueron.org/K103 K103].

== JetBrains ==
Licenses for open-source contributions in the nasqueron organization.

Have access as org admins: Dereckson, Dorian.

== Mailgun ==
Account managed by Dereckson.

2020-02-28: account upgraded to Flex, as it's not possible anymore to add custom domains to the free plan. From July, mails will cost 0.80$ / 1000. To avoid any financial abuse, (i) a 1000 mail accounts limit is currently in (we can update it in account settings) (ii) the credit card associated for this account is limited to 5 € / month.

== Microsoft ==
=== Reporting for mail sent to Outlook.com ===
For mail reporting, Outlook.com offers a "[https://sendersupport.olc.protection.outlook.com/ Smart Network Data Service]" to report statistics about abused IP.

Any op can subscribe with their own Microsoft account on https://sendersupport.olc.protection.outlook.com/snds/addnetwork.aspx / authorization request should ideally be sent to postmaster for tracking.

It's also configured to send report about mails marked as spam by Outlook users to postmaster.

== Mural ==
Mural non-profit plan for Wolfplex Hackerspace ASBL, Sébastien has access.

Personal notes:
* We have 10 seats
* To add an user: [https://app.mural.co/t/nasqueron8788/settings/members workspace > settings > members]
* Mail about access requests go to Wolfplex mail

== PURL ==
/NET/Nasqueron is managed by the Dereckson Internet Archive account.

== Online / Scaleway ==
;Online
* [[Ysul]], account managed by Dereckson, billed to Dereckson
* [[WindRiver]], account managed by Dereckson, billed to Trantorium
;Scaleway
* [[Eglide]], account managed by Sandlayth, billed to Sandlayth
** Following organization account introduction, Dereckson has now access too.

== OVH / SoYouStart ==
Servers:
* [[hyper-001]], account managed by Dereckson, billed to ?
* [[CloudHugger]], account managed by Dereckson, billed to Trantorium

Registrar for nasqueron.org and nasqueron-user-content.org

== Sendgrid ==
Account managed by Dereckson.

== Wikimedia ==
OAuth authentication, managed by Dereckson

Operations grimoire/External services

2026-07-05T13:16:08Z

Dereckson: /* JetBrains */

== Amazon Web Services (AWS) ==
S3, account managed by Sandlayth.

== Docker Hub ==
Organization account, administrative access by Sandlayth and Dereckson.

2021-09-12: request for open source as part of the https://www.docker.com/blog/expanded-support-for-open-source-software-projects done, mainly as automated builds have been disabled in the free team plan.

== GeoLite2 ==
Account at MaxMind for GeoLite2 databases, created by Dereckson.

Account credentials stored in Vault under <code>ops/infra/maxmind</code>.
There aren't the API credentials, for example Sentry ones are stored at <code>ops/secrets/nasqueron/sentry/geoipupdate</code>.

== Gandi ==
Some domains names:
* eglide.org, account managed by Sandlayth
* ook.space, account managed by Dereckson

== GitHub ==
;Organization account
:Administrative access by Sandlayth and Dereckson
:''Some OAuth could be on Dereckson account. When found, should be switched to Nasqueron (see [https://devcentral.nasqueron.org/T1109 T1109]).''

;Alken-Orin
:As automated agent, there is an '''Alken-Orin''' account to link GitHub to CI/CD.
:This account is also used to fetch code from GitHub through the `staging_private_repository` Salt state. To that end, the Salt deploy SSH key is added to this account.
:Credentials at [https://devcentral.nasqueron.org/K53 K53].

== Google ==
OAuth for DevCentral, account managed by Dereckson (under espace-win.org Google Apps organization)

== Hurricane Electric ==
IPv6 connectivity, DNS for nasqueron.org: account 'nasqueron'.

'''Note:''' DNS for some other domains are currently handled on the 'dereckson' account, they'll be moved to 'nasqueron' account when defined as secondary.

== instances.mastodon.xyz ==
Credentials for this account are stored in [https://devcentral.nasqueron.org/K103 K103].

== JetBrains ==
Licenses for open-source contributions in the nasqueron organization.

Have access: Dereckson, Dorian.

== Mailgun ==
Account managed by Dereckson.

2020-02-28: account upgraded to Flex, as it's not possible anymore to add custom domains to the free plan. From July, mails will cost 0.80$ / 1000. To avoid any financial abuse, (i) a 1000 mail accounts limit is currently in (we can update it in account settings) (ii) the credit card associated for this account is limited to 5 € / month.

== Microsoft ==
=== Reporting for mail sent to Outlook.com ===
For mail reporting, Outlook.com offers a "[https://sendersupport.olc.protection.outlook.com/ Smart Network Data Service]" to report statistics about abused IP.

Any op can subscribe with their own Microsoft account on https://sendersupport.olc.protection.outlook.com/snds/addnetwork.aspx / authorization request should ideally be sent to postmaster for tracking.

It's also configured to send report about mails marked as spam by Outlook users to postmaster.

== Mural ==
Mural non-profit plan for Wolfplex Hackerspace ASBL, Sébastien has access.

Personal notes:
* We have 10 seats
* To add an user: [https://app.mural.co/t/nasqueron8788/settings/members workspace > settings > members]
* Mail about access requests go to Wolfplex mail

== PURL ==
/NET/Nasqueron is managed by the Dereckson Internet Archive account.

== Online / Scaleway ==
;Online
* [[Ysul]], account managed by Dereckson, billed to Dereckson
* [[WindRiver]], account managed by Dereckson, billed to Trantorium
;Scaleway
* [[Eglide]], account managed by Sandlayth, billed to Sandlayth
** Following organization account introduction, Dereckson has now access too.

== OVH / SoYouStart ==
Servers:
* [[hyper-001]], account managed by Dereckson, billed to ?
* [[CloudHugger]], account managed by Dereckson, billed to Trantorium

Registrar for nasqueron.org and nasqueron-user-content.org

== Sendgrid ==
Account managed by Dereckson.

== Wikimedia ==
OAuth authentication, managed by Dereckson

Dev zone/JetBrains licenses

2026-07-05T13:14:56Z

Dereckson:

JetBrains "supports non-commercial open source projects" with access to all IDE in an all product pack license, restricted to open source contributions. More information are available at https://jb.gg/OpenSourceSupport.

== How to get a license? ==

'''We currently need to renew a license request, so you can't get one now, but please let us know if you're interested.'''

You can contact [[User:Dereckson|Dereckson]] for a license. According JetBrains conditions, licenses are available for "regular contributions to the project for at least a few months".

There is no minimal threshold of contributions, we welcome any contributions rhythm.

Licenses can be used for any IDE, IntelliJ IDEA or a specific one like PhpStorm, WebStorm or PyCharm.

[[Category:Contributor guide]]

Operations grimoire/PostgreSQL

2026-07-05T12:57:35Z

Dereckson: /* Upgrade */

PostgreSQL is available as a standalone role and can also be enabled on devserver.

Applications on the Docker PaaS can use our PostgreSQL infrastructure (Airflow, datasources) or have their own container (Sentry, with custom wal2json extension). This resource documents our own db- servers.

== Howto ==

=== Open a console ===
Use peer authentication from the postgres user: <code>sudo -u postgres psql</code>

=== Run queries against database ===
The important things are:

# prepare the operation with a .sql file
# put that SQL file to a task
# avoid data destruction and allow rollback
## if a table needs to be dropped, we can rename it to _unused
## if an application doesn't use a column anymore, we can rename it from foo to foo_unused so we can rollback by renaming back
## actual deletion can be done some weeks later

Recommend procedure:

# Create a task on DevCentral or reuse an existing deployment task
# Upload the .sql file on DevCentral or to a repository:
## One-shot maintenance can go to https://devcentral.nasqueron.org/paste/ or sent with <code>cat foo.sql | arc paste --title foo.sql --</code>
## Regular queries can go to the [https://devcentral.nasqueron.org/source/reports/browse/main/sql/ reports repository]
# Link it in the task
# Run it

To run foo.sql against acme database:

# upload the foo.sql file to the relevant server (for example db-A-001 for db-A cluster)
# <code>sudo -u postgres psql acme < foo.sql</code>

=== Create a new database or user ===

It's a simple two steps process:

# Edit the relevant pillar file, for example pillar/dbserver/cluster-A.sls in rOPS
# Deploy the change: <code>salt db-A-001 state.apply roles/dbserver-pgsql</code>

You generally need:

* an user block in dbserver_postgresql.users
** block title is the username
** a password needs to be set in Flow, key is under ops/secrets/
* a database block
* a connection triplet db, user, ips (use /32 for an unique IP)

By default, external connections are NOT enabled for any user and database, an entry for pg_hba.conf MUST be added in connections part.

Servers don't have a public ICANN IP, so you can only connect from other Nasqueron servers.

=== Grant privileges to an user ===

Some applications don't set privileges, even if they own the database. That's for example the case of Orbeon Forms DDL.

To determine if acme has already the rights on the database:

SELECT grantor, grantee, table_schema, table_name, privilege_type
FROM information_schema.table_privileges
WHERE grantee = 'acme';

If not:

GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO acme;

This set of privileges can be handled directly by Salt in cluster privileges definition:

privileges:
- database: <database name>
scope: table
schema: public
tables:
- ALL
privileges:
- ALL

See {{D|3252}} or {{D|3253}} for an example.

As a known issue, this query will ALWAYS be executed by Salt.

; Sequences privileges

Sequences aren't included in that GRANT ALL PRIVILEGES. We can generate GRANT queries for them:

SELECT 'GRANT USAGE ON SEQUENCE ' || sequence_schema || '.' || sequence_name || ' TO "acme";'
FROM information_schema.sequences
WHERE sequence_schema NOT LIKE 'pg_%'
AND sequence_schema != 'information_schema';

=== What to do after an update of PostgreSQL servers? ===

The following services need their connection to explicitly be restarted:

{| class="wikitable"
|+ Services to tweak
|-
! Cluster !! Service !! Procedure
|-
| A || Airflow > airflow_triggerer || On Dwellers, docker restart airflow_triggerer
|-
| A || Airflow > airflow_scheduler || On Dwellers, docker restart airflow_scheduler
|}

== Upgrade ==
=== PostgreSQL package ===
When upgrading PostgreSQL the following checks must be done:

* Do we have the postgres -contrib port installed too for the pg_trgm module for FANTOIR?
* Do we have XML support for Orbeon?

There are several methods to upgrade a server:
* the pg_dumpall method has been successfully tested on WindRiver for 15 -> 16
* the pg_upgrade method has been used for 16 -> 17 and 17 -> 18

=== pg_upgrade ===

This procedure describes an in-place upgrade of PostgreSQL using pg_upgrade on FreeBSD with ZFS available.

The example below upgrades PostgreSQL 17 to PostgreSQL 18, while preserving the old cluster for rollback. Tested on WindRiver.

;Preconditions
* PostgreSQL 17 cluster is located at: <code>/var/db/postgres/data17</code>
* A new ZFS dataset will be created for PostgreSQL 18 at <code>arcology/postgresql/data18</code>
* PostgreSQL 17 package is available in cache in <code>/var/cache/pkg/</code>
* PostgreSQL service will need to be stopped before starting the actual upgrade procedure

; Create new data directory
<syntaxhighlight lang="sh">
$ pkg install postgresql18-server postgresql18-client postgresql18-contrib
$ zfs create \
-o mountpoint=/var/db/postgres/data18 \
-o compression=lz4 \
-o atime=off \
-o recordsize=8K \
arcology/postgresql/data18
$ chown postgres:postgres /data18
$ chmod 700 /data18
$ sudo -u postgres initdb --no-data-checksums -D /var/db/postgres/data18
</syntaxhighlight>

; Extract old version packages and do a dry-run
<syntaxhighlight lang="sh">
$ rm -rf /tmp/pg-upgrade && mkdir /tmp/pg-upgrade
$ cd /var/cache/pkg
$ tar xf postgresql17-server-17.10.pkg -C /tmp/pg-upgrade
$ tar xf postgresql17-contrib-17.10.pkg -C /tmp/pg-upgrade
$ /tmp/pg-upgrade/usr/local/bin/postgres --version
postgres (PostgreSQL) 17.10
$ sudo -u postgres pg_upgrade \
--check \
-b /tmp/pg-upgrade/usr/local/bin \
-B /usr/local/bin \
-d /var/db/postgres/data17 \
-D /var/db/postgres/data18
</syntaxhighlight>

At this stage, it's needed to resolve issues reported by pg_upgrade.

; Upgrade
<syntaxhighlight>
$ service postgresql stop
$ sudo -u postgres pg_upgrade \
-b /tmp/pg-upgrade/usr/local/bin \
-B /usr/local/bin \
-d /var/db/postgres/data17 \
-D /var/db/postgres/data18
$ cd /var/db/postgres
$ rm data
$ ln -s data18 data
$ service postgresql start
</syntaxhighlight>

; Post-upgrade maintenance
<syntaxhighlight lang="sh">
$ sudo -u postgres vacuumdb --all --analyze-in-stages --missing-stats-only
$ sudo -u postgres vacuumdb --all --analyze-only
</syntaxhighlight>

If a file update_extensions.sql has been created, run it to update extensions schema.

=== Rollback procedure for pg_upgrade ===

# Remove current version packages
# Reinstall old version packages
# Stop server
# Resymlink the old data directory as /var/db/postgres/data
# Start server

== Clusters ==

Letters can be discontinuous: for example, B will be a MySQL cluster.

=== Cluster A ===
A is the general cluster, for Nasqueron services. It currently has one server, db-A-001.

{| class="wikitable"
|+ Databases
|-
! Database !! Managed by !! Description
|-
| airflow || Nasqueron Ops || Workflows runner, used by datasources
|-
| fantoir || Datasources || PostgreSQL version of FANTOIR for geocoding
|}

== Troubleshoot ==
=== An application stops to work correctly with PostgreSQL ===
Issues with queries are logged to /var/log/messages:

$ tail -n100 -f /var/log/messages | grep postgres

For example, {{T|1943}} issue was found with this line:

Jan 14 23:13:58 db-A-001 postgres[35351]: [8-1] 2024-01-14 23:13:58.081 UTC [35351] ERROR: unsupported XML feature

=== Unsupported XML feature ===
For Orbeon, XML support is required. That's not by default the case on FreeBSD, the port needs to be built manually. That's the case when provisioning a new server through {{Ops file|roles/dbserver-pgsql/server/build.sls}} but upgrade can break this port.

If so, rebuild the package. For that, you can follow the instructions of [[Operations grimoire/FreeBSD]], section PostgreSQL.

=== Some postgres_privileges.present are always changed by Salt ===

Some ON ALL TABLE privilege queries are always run by the Salt PostgreSQL execution module. For example:

ID: dbserver_pgsql_user_orbeon_privilege_2_ALL
Function: postgres_privileges.present
Name: orbeon
Result: True
Comment: The privilege(s): ALL have been granted to orbeon
Started: 21:54:53.656120
Duration: 284.394 ms
Changes:
----------
orbeon:
Present

Those statements aren't idempotent. This is a known issue, and doesn't affect deployment.

Operations grimoire/NetBox

2026-07-05T10:01:36Z

Dereckson: /* Python */

NetBox is the current source of truth for the network. It's available at [https://netbox.nasqueron.org NetBox].

== Integration with Salt ==
Ongoing integration projects are in work to serve NetBox data as part of Salt pillar for configuration as code.

It should serve:
* /etc/hosts data for Drake network machines
* the same information available at pillar/nodes/nodes.sls, so we won't need to maintain that anymore

== Integration with IRC ==
Export to a database for [[Odderon]] is discussed at [https://devcentral.nasqueron.org/T1868 T1868].

That should allow the following workflow:

17:13:59 < Dereckson> 172.27.27.6
17:14:00 < Odderon> (Dereckson): 172.27.27.6/28 docker-001.nasqueron.org / Decommissioned address for docker-001.nasqueron.org / Drake [deprecated]

Source code of the translation code is available at https://devcentral.nasqueron.org/source/netbox-darkbot-db/

== Backup ==
To backup the PostgreSQL database:

sudo -u postgres pg_dump netbox | gzip > netbox-$(date +"%Y-%m-%d").gz

Database is currently hosted on WindRiver, not on DB-A, even if a user exists there and an outdated copy exists.

== Upgrade ==
=== NetBox ===
To upgrade NetBox:
# Backup database on WindRiver
# Install the new version
# Copy configuration
# Update Python dependencies
# Shutdown the service: <code>service netbox stop</code> or if pid is wrong <code>killall netbox</code>
# Symlink the directory in /srv/netbox
# Run the database migrations and regenerate static resources, etc. as documented in upgrade.sh
# Start the service

An example for upgrade to 3.7.0:

sudo -u postgres pg_dump netbox | gzip > netbox-$(date +"%Y-%m-%d").gz
cd /srv/netbox
wget https://github.com/netbox-community/netbox/archive/refs/tags/v3.7.0.tar.gz
tar xzf v3.7.0.tar.gz
cp /srv/netbox/netbox/netbox/netbox/configuration.py netbox-3.7.0/netbox/netbox/
source venv/bin/activate
pip install -r netbox-3.7.0/requirements.txt
killall -u netbox
rm netbox
ln -s netbox-3.7.0 netbox
cd /srv/netbox/netbox
mkdocs build
cd /srv/netbox/netbox/netbox
python3 manage.py migrate
python3 manage.py collectstatic
python3 manage.py remove_stale_contenttypes
python3 manage.py reindex --lazy
python3 manage.py clearsessions
service netbox start

To track configuration changes, you can use https://github.com/netbox-community/netbox/commits/develop/netbox/netbox/configuration_example.py

If psycopg can't build, you can build it with <code>pip install "psycopg[c]"</code>. That requires development headers for PostgreSQL, available on all FreeBSD servers where PostgreSQL is installed ; for a Docker image based on Linux, search for a libpq-dev or libpq-devel package for that purpose.

Documentation needs to be generated before collectstatic. If not, run again the collectstatic command to copy docs from project-static to static directory.

=== Python ===

''This procedure only applies when we do major interpreter change (e.g. Python 3.11 to 3.12) at OS level.'''

To recreate the virtual environment with a new Python interpreter, recreate as root an empty venv directory:

rm -rf /srv/netbox/venv
mkdir /srv/netbox/venv
chown netbox:netbox /srv/netbox/venv

Then, as netbox user, recreate it:

python3 -m venv /srv/netbox/venv
source /srv/netbox/venv/bin/activate
pip install --upgrade pip
pip install -r /srv/netbox/netbox/requirements.txt

If you've any issue with psycopg, you can build them from FreeBSD ports and copy the .whl to /opt/python/py312 or your version folder.

$ ls /opt/python/py312
psycopg_c-3.2.13-cp312-cp312-freebsd_15_1_release_p1_amd64.whl psycopg_pool-3.3.1-py3-none-any.whl psycopg-3.2.13-py3-none-any.whl
$ pip install /opt/python/py312/psycopg*

To easily find and copy the .whl from your port folder:

cp $(find . -type f -name '*.whl') /opt/python/py312/

== Troubleshoot ==
=== Grafana ===

Use [https://grafana.nasqueron.org/d/O6v4rMpizda/netbox?orgId=1&refresh=10s Grafana dashboard] to check statistics.

As of 2024-08-04, all the rates are erroneous and (a lot) over-evaluated.

=== 500 after server reboot ===
After the server is restarted, NetBox needs PostgreSQL and Redis to work.

* If PostgreSQL is down, we don't have any message on the web UI, it serves directly a 500 error code
* If PostgreSQL up, Redis down, an explicit error message tells us it can't connect to Redis
* When both services are up, site should work again

== Conventions ==
=== Devices ===
==== Device role colors ====
* Network appliances and assimilated (e.g. machines with router role): gray
* Devices for human to connect to and work from (e.g. shellserver, devserver): purple
* Devices hosting services (e.g. dbserver, paas-docker): pink

Operations grimoire/NetBox

2026-07-05T09:51:09Z

Dereckson: /* Python */

NetBox is the current source of truth for the network. It's available at [https://netbox.nasqueron.org NetBox].

== Integration with Salt ==
Ongoing integration projects are in work to serve NetBox data as part of Salt pillar for configuration as code.

It should serve:
* /etc/hosts data for Drake network machines
* the same information available at pillar/nodes/nodes.sls, so we won't need to maintain that anymore

== Integration with IRC ==
Export to a database for [[Odderon]] is discussed at [https://devcentral.nasqueron.org/T1868 T1868].

That should allow the following workflow:

17:13:59 < Dereckson> 172.27.27.6
17:14:00 < Odderon> (Dereckson): 172.27.27.6/28 docker-001.nasqueron.org / Decommissioned address for docker-001.nasqueron.org / Drake [deprecated]

Source code of the translation code is available at https://devcentral.nasqueron.org/source/netbox-darkbot-db/

== Backup ==
To backup the PostgreSQL database:

sudo -u postgres pg_dump netbox | gzip > netbox-$(date +"%Y-%m-%d").gz

Database is currently hosted on WindRiver, not on DB-A, even if a user exists there and an outdated copy exists.

== Upgrade ==
=== NetBox ===
To upgrade NetBox:
# Backup database on WindRiver
# Install the new version
# Copy configuration
# Update Python dependencies
# Shutdown the service: <code>service netbox stop</code> or if pid is wrong <code>killall netbox</code>
# Symlink the directory in /srv/netbox
# Run the database migrations and regenerate static resources, etc. as documented in upgrade.sh
# Start the service

An example for upgrade to 3.7.0:

sudo -u postgres pg_dump netbox | gzip > netbox-$(date +"%Y-%m-%d").gz
cd /srv/netbox
wget https://github.com/netbox-community/netbox/archive/refs/tags/v3.7.0.tar.gz
tar xzf v3.7.0.tar.gz
cp /srv/netbox/netbox/netbox/netbox/configuration.py netbox-3.7.0/netbox/netbox/
source venv/bin/activate
pip install -r netbox-3.7.0/requirements.txt
killall -u netbox
rm netbox
ln -s netbox-3.7.0 netbox
cd /srv/netbox/netbox
mkdocs build
cd /srv/netbox/netbox/netbox
python3 manage.py migrate
python3 manage.py collectstatic
python3 manage.py remove_stale_contenttypes
python3 manage.py reindex --lazy
python3 manage.py clearsessions
service netbox start

To track configuration changes, you can use https://github.com/netbox-community/netbox/commits/develop/netbox/netbox/configuration_example.py

If psycopg can't build, you can build it with <code>pip install "psycopg[c]"</code>. That requires development headers for PostgreSQL, available on all FreeBSD servers where PostgreSQL is installed ; for a Docker image based on Linux, search for a libpq-dev or libpq-devel package for that purpose.

Documentation needs to be generated before collectstatic. If not, run again the collectstatic command to copy docs from project-static to static directory.

=== Python ===

''This procedure only applies when we do major interpreter change (e.g. Python 3.11 to 3.12) at OS level.'''

To recreate the virtual environment with a new Python interpreter, recreate as root an empty venv directory:

rm -rf /srv/netbox/venv
mkdir /srv/netbox/venv
chown netbox:netbox /srv/netbox/venv

Then, as netbox user, recreate it:

python3 -m venv /srv/netbox/venv
source /srv/netbox/venv/bin/activate
pip install --upgrade pip
pip install -r /srv/netbox/netbox/requirements.txt

== Troubleshoot ==
=== Grafana ===

Use [https://grafana.nasqueron.org/d/O6v4rMpizda/netbox?orgId=1&refresh=10s Grafana dashboard] to check statistics.

As of 2024-08-04, all the rates are erroneous and (a lot) over-evaluated.

=== 500 after server reboot ===
After the server is restarted, NetBox needs PostgreSQL and Redis to work.

* If PostgreSQL is down, we don't have any message on the web UI, it serves directly a 500 error code
* If PostgreSQL up, Redis down, an explicit error message tells us it can't connect to Redis
* When both services are up, site should work again

== Conventions ==
=== Devices ===
==== Device role colors ====
* Network appliances and assimilated (e.g. machines with router role): gray
* Devices for human to connect to and work from (e.g. shellserver, devserver): purple
* Devices hosting services (e.g. dbserver, paas-docker): pink

Operations grimoire/NetBox

2026-07-05T09:50:28Z

Dereckson: /* Upgrade */

NetBox is the current source of truth for the network. It's available at [https://netbox.nasqueron.org NetBox].

== Integration with Salt ==
Ongoing integration projects are in work to serve NetBox data as part of Salt pillar for configuration as code.

It should serve:
* /etc/hosts data for Drake network machines
* the same information available at pillar/nodes/nodes.sls, so we won't need to maintain that anymore

== Integration with IRC ==
Export to a database for [[Odderon]] is discussed at [https://devcentral.nasqueron.org/T1868 T1868].

That should allow the following workflow:

17:13:59 < Dereckson> 172.27.27.6
17:14:00 < Odderon> (Dereckson): 172.27.27.6/28 docker-001.nasqueron.org / Decommissioned address for docker-001.nasqueron.org / Drake [deprecated]

Source code of the translation code is available at https://devcentral.nasqueron.org/source/netbox-darkbot-db/

== Backup ==
To backup the PostgreSQL database:

sudo -u postgres pg_dump netbox | gzip > netbox-$(date +"%Y-%m-%d").gz

Database is currently hosted on WindRiver, not on DB-A, even if a user exists there and an outdated copy exists.

== Upgrade ==
=== NetBox ===
To upgrade NetBox:
# Backup database on WindRiver
# Install the new version
# Copy configuration
# Update Python dependencies
# Shutdown the service: <code>service netbox stop</code> or if pid is wrong <code>killall netbox</code>
# Symlink the directory in /srv/netbox
# Run the database migrations and regenerate static resources, etc. as documented in upgrade.sh
# Start the service

An example for upgrade to 3.7.0:

sudo -u postgres pg_dump netbox | gzip > netbox-$(date +"%Y-%m-%d").gz
cd /srv/netbox
wget https://github.com/netbox-community/netbox/archive/refs/tags/v3.7.0.tar.gz
tar xzf v3.7.0.tar.gz
cp /srv/netbox/netbox/netbox/netbox/configuration.py netbox-3.7.0/netbox/netbox/
source venv/bin/activate
pip install -r netbox-3.7.0/requirements.txt
killall -u netbox
rm netbox
ln -s netbox-3.7.0 netbox
cd /srv/netbox/netbox
mkdocs build
cd /srv/netbox/netbox/netbox
python3 manage.py migrate
python3 manage.py collectstatic
python3 manage.py remove_stale_contenttypes
python3 manage.py reindex --lazy
python3 manage.py clearsessions
service netbox start

To track configuration changes, you can use https://github.com/netbox-community/netbox/commits/develop/netbox/netbox/configuration_example.py

If psycopg can't build, you can build it with <code>pip install "psycopg[c]"</code>. That requires development headers for PostgreSQL, available on all FreeBSD servers where PostgreSQL is installed ; for a Docker image based on Linux, search for a libpq-dev or libpq-devel package for that purpose.

Documentation needs to be generated before collectstatic. If not, run again the collectstatic command to copy docs from project-static to static directory.

=== Python ===

To recreate the virtual environment with a new Python interpreter, recreate as root an empty venv directory:

rm -rf /srv/netbox/venv
mkdir /srv/netbox/venv
chown netbox:netbox /srv/netbox/venv

Then, as netbox user, recreate it:

python3 -m venv /srv/netbox/venv
source /srv/netbox/venv/bin/activate
pip install --upgrade pip
pip install -r /srv/netbox/netbox/requirements.txt

== Troubleshoot ==
=== Grafana ===

Use [https://grafana.nasqueron.org/d/O6v4rMpizda/netbox?orgId=1&refresh=10s Grafana dashboard] to check statistics.

As of 2024-08-04, all the rates are erroneous and (a lot) over-evaluated.

=== 500 after server reboot ===
After the server is restarted, NetBox needs PostgreSQL and Redis to work.

* If PostgreSQL is down, we don't have any message on the web UI, it serves directly a 500 error code
* If PostgreSQL up, Redis down, an explicit error message tells us it can't connect to Redis
* When both services are up, site should work again

== Conventions ==
=== Devices ===
==== Device role colors ====
* Network appliances and assimilated (e.g. machines with router role): gray
* Devices for human to connect to and work from (e.g. shellserver, devserver): purple
* Devices hosting services (e.g. dbserver, paas-docker): pink

WindRiver

2026-07-05T09:34:21Z

Dereckson:

WindRiver is an FreeBSD 15 bare metal server for Nasqueron general-purpose development.

It supersedes [[Ysul]].

Upgrade is planned in September 2027, per [[Operations grimoire/Servers lifecycle]].

Documentation: [[Devserver reference]]

== Basic information ==
* '''IP:'''
** 195.154.30.15 <strike>51.159.17.168 since 2023-06-14. Previously 51.159.18.59.</strike>
** 2a02:578:4f0d:0:30d0:7b22:6cde:a52e (native, still to migrate)
** 2001:bc8:6005:5:aa1e:84ff:fef3:5d9c (future through HE)
* '''Hostname:''' windriver.nasqueron.org
* '''Homepage:''' https://windriver.nasqueron.org/
* '''Configuration:''' <strike>64 Gb RAM, Xeon E3 1240 V6, 2x 500 GB SSD ("Pro-6-S")</strike> 96 Gb. RAM, Xeon E5-1650 v3, 3x 500 GB SSD ("Pro-4-L")
* '''ISP:''' [http://www.online.net Online] (FR)
* '''Network:''' Illiad (FR)
* '''Policy:''' Access for any Nasqueron project and for infrastructure operations task.
* '''Started:''' 2019-11-21

== Ports ==

Ports for services managed automatically through Salt are available on {{Ops file|PORTS}}

{| class="wikitable"
|+ Reserved ports - IRC server range
|-
! Port !! User account !! Description
|-
| 6901 || dereckson || irssi proxy
|-
| 6902 || dereckson || irssi proxy
|}

== Troubleshoot ==

=== To check after reboot ===

* Network
** IPv4 - ICANN
** IPv6 - main + viperserv alias
** IPv6 - can we reach something with IPv6
** IPv4 - Drake: tunnel + route + ping any server
* Services
** Alkane HTTP server
** API exec HTTP server
** Bitlbee
** Eggdrops: Dæghrefn + Wearg
** Grafana
** MariaDB
** NetBox
** nginx
** Node exporter for Prometheus
** oidentd
** php-fpm
** PostgreSQL
** Prometheus
** Redis
** Salt minion
** SSH server
* Vault connectivity

WindRiver

2026-07-05T09:34:13Z

Dereckson:

WindRiver is an FreeBSD 14 bare metal server for Nasqueron general-purpose development.

It supersedes [[Ysul]].

Upgrade is planned in September 2027, per [[Operations grimoire/Servers lifecycle]].

Documentation: [[Devserver reference]]

== Basic information ==
* '''IP:'''
** 195.154.30.15 <strike>51.159.17.168 since 2023-06-14. Previously 51.159.18.59.</strike>
** 2a02:578:4f0d:0:30d0:7b22:6cde:a52e (native, still to migrate)
** 2001:bc8:6005:5:aa1e:84ff:fef3:5d9c (future through HE)
* '''Hostname:''' windriver.nasqueron.org
* '''Homepage:''' https://windriver.nasqueron.org/
* '''Configuration:''' <strike>64 Gb RAM, Xeon E3 1240 V6, 2x 500 GB SSD ("Pro-6-S")</strike> 96 Gb. RAM, Xeon E5-1650 v3, 3x 500 GB SSD ("Pro-4-L")
* '''ISP:''' [http://www.online.net Online] (FR)
* '''Network:''' Illiad (FR)
* '''Policy:''' Access for any Nasqueron project and for infrastructure operations task.
* '''Started:''' 2019-11-21

== Ports ==

Ports for services managed automatically through Salt are available on {{Ops file|PORTS}}

{| class="wikitable"
|+ Reserved ports - IRC server range
|-
! Port !! User account !! Description
|-
| 6901 || dereckson || irssi proxy
|-
| 6902 || dereckson || irssi proxy
|}

== Troubleshoot ==

=== To check after reboot ===

* Network
** IPv4 - ICANN
** IPv6 - main + viperserv alias
** IPv6 - can we reach something with IPv6
** IPv4 - Drake: tunnel + route + ping any server
* Services
** Alkane HTTP server
** API exec HTTP server
** Bitlbee
** Eggdrops: Dæghrefn + Wearg
** Grafana
** MariaDB
** NetBox
** nginx
** Node exporter for Prometheus
** oidentd
** php-fpm
** PostgreSQL
** Prometheus
** Redis
** Salt minion
** SSH server
* Vault connectivity

Operations grimoire/Servers lifecycle

2026-07-05T09:33:29Z

Dereckson: Created page with "This resource tracks the servers lifecycle, when we've to plan rollout and decom. == Contracts == {| class="wikitable" |+ Servers with engagement contract |- ! Server name !! Provider !! Start date !! End date !! Conditions !! Current decision |- | WindRiver || Scaleway || 2024-09-12 || 2027-09-12 || -20% || Upgrade to another server with faster CPU |}"

This resource tracks the servers lifecycle, when we've to plan rollout and decom.

== Contracts ==

{| class="wikitable"
|+ Servers with engagement contract
|-
! Server name !! Provider !! Start date !! End date !! Conditions !! Current decision
|-
| [[WindRiver]] || Scaleway || 2024-09-12 || 2027-09-12 || -20% || Upgrade to another server with faster CPU
|}

Operations grimoire

2026-07-05T09:30:44Z

Dereckson: /* Infrastructure */

[[File:Nasqueron Operations Grimoire.jpg|thumb|320px|right|The Nasqueron operations grimoire tries to document the more arcane aspects of our complex infrastructure.]]

Welcome to the Nasqueron operations grimoire (NOG).

This grimoire is a reference about our infrastructure and services hosted with procedures we follow to build, maintain and deploy.

Our infrastructure is open, mainly documented in {{repo|operations}} repository, and we actively encourage contributions from the community.

== Infrastructure ==
* [[/Environments]]
* [[/Kubernetes]]
* [[/Docker engine]]
* [[/Salt]]
* [[/Servers lifecycle]]

=== OS-specific ===
;By OS
* [[/FreeBSD]]
* [[/RHEL]]

;All OSes
* [[/NTP]]
* [[/Packages repository]]
* [[/Services]]: systemd, runit and rc

=== Storage ===
* [[/ZFS]]

=== Observability ===
* [[/Grafana]]
* [[/Logs]]
* [[/Prometheus]]

=== Network ===
* [[/Network]]
* [[/DNS]]
* [[/Firewall]]
* [[/Router]]
* [[/IPv6]]
* [https://netbox.nasqueron.org/ NetBox]

== Services ==
=== Core services ===
; Messages queues
* [[/Kafka]]
* [[/RabbitMQ]]

; Databases
* [[/MySQL]]
* [[/PostgreSQL]]

; Ops
* [[/NetBox]]

=== Identity management ===
* [[/Login]] (Auth Grove)

=== Collaborative tools ===
* [[/DevCentral]] (Phabricator)
* [[/Etherpad]]
* [[/Mumble]]
* [[/Mastodon]] (social.nasqueron.org)
* [[/Openfire]] (XMPP)

=== IRC bots ===
* [[/Dæghrefn]] (eggdrop)
* [[/Odderon]] (darkbot)

=== Mail ===
* [[/Mail]]
* [[/Mail/DKIM]]
* [[/Mail/Sympa]]

=== Web ===
; Common documentation for all webserver roles
* [[/Web/Headers]]

; Where to host?
* [[/Docker engine]] for Docker containers front-end
* [[/Alkane]] for PHP and static sites

; SaaS for common applications
* [[MediaWiki SaaS]]
* [[/WordPress]]

; Other sites
* [[/Sites on Eglide]]
* [[/Sites on Ysul]] (currently migrating to Alkane)

; Services for web applications
* [[/Anubis]] if you need to protect from LLM scraping traffic
* [[/Orbeon]] if you're in need of a form

=== CI/CD ===
* [[/Broker]]
* [[/Docker registry]]
* [[/Jenkins]]
* [[/Notifications center]]
* [[/Sentry]]
* [[/Vault]]

=== Shellserver ===
* [[/Eglide/Vault]]

== Services configuration ==
''This section contains general information not related to a specific service.''
* [[/TLS certificates]] (Let's encrypt / letsencrypt)

== Checklists ==
=== SSH ===
* [[/Recommended SSH configuration]]

=== Infrastructure ===
* [[/How to add a server to the Nasqueron servers pool]]
* [[/How to attach a new virtual disk]]
* [[/Reboot checklist]]

=== Network ===
* [[/Checklist router post-restart]]

=== Docker ===
* [[/Restart a Docker engine]]
* [[/Dwellers to DevCentral]]
* [[/Git operations in production containers]]
* [[/Add a service to Docker PaaS]]
* [[/Docker Hub]]

=== Salt ===
* [[/Operations repository]]
* [[/Deploy with Salt]]
* [[/Create and revoke user accounts on Salt servers]]
* [[/Provision user homefiles]]

=== Terraform / OpenTofu ===
* [[/Deploy with Terraform]]

== SIG ==
* [[/Onboarding]]

== Appendices ==
* [[/Changelog]]
* [[/Contacts]]
* [[/Configuration files]]
* [[/Contribute]]
* [[/Decom]]
* [[/Evaluated products]]
* [[/External services]]
* [[/Incidents]]
* [[/Legacy archive]]
* [[/OID]]
* [[/Old content report]]
* [[/Policies]]
* [[/Who]]

[[Category:Operations grimoire|*]]
[[Category:Reference]]

User:Dereckson/Arcane Grove/BlueDrake

2026-06-28T21:49:00Z

Dereckson: /* Components */

'''BlueDrake''' is the name of the hybrid productivity-gaming workstation.

== Hardware ==
=== Components ===
{| class="wikitable sortable"
|+ BlueDrake parts
|-
! Category !! Brand !! Model !! Links
|-
| Case || Lian Li || [https://lian-li.com/product/lancool-iii/ Lancool III] || [https://drive.google.com/file/d/1kd9ku_raF2uXWeLD7voGfT4ZZ10XOizy/view?usp=sharing 📖]
|-
| Motherboard || Asus || [https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/ ROG Strix B650E-E Gaming WiFi] || [https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/helpdesk_manual/ 📖] [https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/helpdesk_download/ 📥]
|-
| CPU || AMD || Ryzen 9 7900X || [https://www.amd.com/en/products/cpu/amd-ryzen-9-7900x 📖]
|-
| CPU Cooler || Noctua || NH-D15S || [https://noctua.at/en/nh-d15s 📖] [https://noctua.at/en/nh-d15s/manuals 📥]
|-
| GPU || Sapphire / AMD || PURE Radeon RX 7700 XT 12GB || [https://www.sapphiretech.com/en/consumer/pure-radeon-rx-7700-xt-12g-gddr6-frostpunk2 📖]
|-
| RAM || G.Skill || Trident Z Neo DDR5 96 GB (2×48 GB) || [https://www.gskill.com/product/165/374/1682577390/F5-5600J4040D48GX2-TZ5RK 📖]
|-
| Storage || Kingston || Fury Renegade 2 TB NVMe M.2 (×2) || [https://www.kingston.com/en/ssd/gaming/fury-renegade-nvme-pcie-ssd 📖]
|-
| PSU || Seasonic || Core GX-750 || [https://seasonic.com/core-gx#specification 📖]
|-
| Screen || AOC || C27G1 || [https://aoc.com/be-fr/gaming/products/monitors/c27g1/downloads 📥]
|-
| Screen || Alienware || AW3425DWM || [https://dl.dell.com/content/manual56809116-alienware-34-gaming-monitor-aw3425dwm-quick-start-guide.pdf?language=en-us 📖]
|}

'''Note:''' Alienware screen ordered, still to be shipped and installed.

== Software ==
=== FreeBSD ===
Things to check for GPU:
* Ollama on FreeBSD -> https://www.reddit.com/r/freebsd/comments/1d3hmmz/comment/lqiulx9/ / https://github.com/ollama/ollama/pull/4172 (<code>pkg install go122 cmake vulkan-headers vulkan-loader</code>)
* GPU passthrough with bhyve -> https://wiki.freebsd.org/bhyve/pci_passthru

User talk:Dereckson/Arcane Grove/BlueDrake

2026-06-23T19:28:36Z

Dereckson: Created page with "== Version in YAML to use with LLM == <syntaxhighlight lang="yaml"> components: - category: Case brand: Lian Li model: Lancool III links: manual: https://drive.google.com/file/d/1kd9ku_raF2uXWeLD7voGfT4ZZ10XOizy/view?usp=sharing - category: Motherboard brand: Asus model: ROG Strix B650E-E Gaming WiFi links: product: https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/ manual: https://rog.asus.com..."

== Version in YAML to use with LLM ==

<syntaxhighlight lang="yaml">
components:
- category: Case
brand: Lian Li
model: Lancool III
links:
manual: https://drive.google.com/file/d/1kd9ku_raF2uXWeLD7voGfT4ZZ10XOizy/view?usp=sharing

- category: Motherboard
brand: Asus
model: ROG Strix B650E-E Gaming WiFi
links:
product: https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/
manual: https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/helpdesk_manual/
downloads: https://rog.asus.com/motherboards/rog-strix/rog-strix-b650e-e-gaming-wifi-model/helpdesk_download/

- category: CPU
brand: AMD
model: Ryzen 9 7900X
links:
product: https://www.amd.com/en/products/cpu/amd-ryzen-9-7900x

- category: CPU Cooler
brand: Noctua
model: NH-D15S
links:
product: https://noctua.at/en/nh-d15s
manuals: https://noctua.at/en/nh-d15s/manuals

- category: GPU
brand: Sapphire / AMD
model: PURE Radeon RX 7700 XT 12GB
links:
product: https://www.sapphiretech.com/en/consumer/pure-radeon-rx-7700-xt-12g-gddr6-frostpunk2

- category: RAM
brand: G.Skill
model: Trident Z Neo DDR5 96 GB (2×48 GB)
links:
product: https://www.gskill.com/product/165/374/1682577390/F5-5600J4040D48GX2-TZ5RK

- category: Storage
brand: Kingston
model: Fury Renegade 2 TB NVMe M.2 (x2)
links:
product: https://www.kingston.com/en/ssd/gaming/fury-renegade-nvme-pcie-ssd

- category: PSU
brand: Seasonic
model: Core GX-750
links:
product: https://seasonic.com/core-gx#specification

- category: Screen
brand: AOC
model: C27G1
links:
downloads: https://aoc.com/be-fr/gaming/products/monitors/c27g1/downloads
</syntaxhighlight>

Operations grimoire/Operations repository

2026-06-07T11:32:13Z

Dereckson: /* macOS */

Our configuration as code is stores in the operations (rOPS) repository.

== Repository layout ==
{| class="wikitable sortable"
|+ Content of rOPS
|-
! Path !! Description
|-
| _modules || Custom execution modules
|-
| _states || Custom states modules
|-
| _tests || Unit tests for custom modules, scripts, tests for repo
|-
| hotfixes || Fixes you need to run to solve a problem on the servers
|-
| pillar || Configuration data structures to use in the states
|-
| roles || The states to deploy, divided in roles and then in units
|-
| utils || Helper scripts to maintain the repository
|-
| terraform || OpenTofu / Terraform infrastructure configuration
|-
| map.jinja || As we deploy on several OS and distros, mapping of packages names or directories
|-
| top.sls || topfile: what we deploy where?
|-
| PORTS || Documentation of the ports used in the configuration
|-
| UIDs || Documentation of the users used in the configuration
|-
| GIDs || Documentation of the groups used in the configuration
|}

== Contributions howto ==
=== Repository source ===
You'll find the Operations repository at https://devcentral.nasqueron.org/source/operations/

If DevCentral isn't available, a mirror of the repository can be found at https://github.com/nasqueron/operations.

=== Workflow of contributions ===
We follow the general workflow is described at [[How to contribute code]].

Before committing a change to the main branch, you can test a deployment on a server.
In that case, merge in main immediately after the deployment as the repository is the source of truth for the server state.

Log what you do on #nasqueron-ops, so it will be included at https://infra.nasqueron.org/servers-log/

=== Code conventions ===
''See also: [[Code conventions]].''

* Python code: run `black` before committing
* YAML: indent with two spaces, including list bullets

<syntaxhighlight lang="yaml">
id:
method:
- somekey: value
- otherkey: value
</syntaxhighlight>

== Environment setup ==

Use of WindRiver is recommended if you wish to get an environment already installed for your contributions.

=== Everywhere setup ===
This section cover topics needed both on our development servers or in your laptop.

==== Python dependencies ====

Create a virtual environment, then install dependencies from {{Ops file|requirements.txt}}:

mkdir -p $HOME/dev/python/ops
python3 -m venv $HOME/dev/python/ops
source $HOME/dev/python/ops/bin/activate
pip install -r requirements.txt

==== Datacube ====

If you're in the ops group, you'll need sometimes to deploy from branches. As our deployment server Complector doesn't have PHP installed (so no arc), you need to exchange branches through our datacube.

On WindRiver:

git remote add datacube /datacube/git/operations.git

Anywhere else:

git remote add datacube ssh://windriver.nasqueron.org/datacube/git/operations.git

If you aren't in the ops groups, and have access to our devserver, you'll still be able to clone or pull from that directory, but not to write there (ie push branches).

=== Local computer setup ===

This section cover topics NOT needed on our development servers.

==== macOS ====

To run tests properly, install first:

brew install bats
brew install python3.13

You can now setup the virtual environment per everywhere setup instructions.

Salt behaves correctly on macOS, so you can install it safely in the virtual environment:

pip install salt==3006.25

Check the version on WindRiver or Complector with <code>salt --versions</code>.

Finally, to run the tests, you need a recent version of make, but the BSD make currently shipped, as of Tahoe 26.5, isn't up-to-date:

brew install gmake
(cd _tests && gmake)

==== Arcanist ====

To use arc with the operations repository, our collection of patches is needed.

If arcanist isn't installed through Git repository, best is to do like on devserver role:

mkdir /opt/phabricator && cd /opt/phabricator
git clone https://github.com/nasqueron/arcanist.git
(cd arcanist && git checkout production)
ln -s /opt/phabricator/arcanist/bin/arc /usr/local/bin/
git clone https://devcentral.nasqueron.org/source/shellcheck-linter.git

If you've already cloned Arcanist repository, switch to our branch production:

git remote add nasqueron git@github.com:nasqueron/arcanist.git
git fetch --all
git checkout production

As of August 2024, there is no plan to make that repository available on DevCentral.

You'll also need shellcheck library-linter library, normally at the same level than your arcanist repository.

==== IDE configuration ====
[[File:PyCharm-TemplateLanguages.png|thumb|right|Screenshot of correctly configured template languages]]
The states .sls file are Jinja2 templates producing YAML files, or "jinja2+yaml". If this case can't be handled by your IDE, it works best to use YAML syntax highlighting.

If you use PyCharm or IntelliJ IDEA Ultimate, you can configure this scheme:

* Allow YAML files to be Jinja2 templates
** Go to Settings > Languages & Frameworks > Template Languages
** Select Jinja2 as template language
** Add YAML in the list
* Open SLS as YAML

== Linting ==

=== pre-commit ===
You can use '''pre-commit''' you can install with <code>make</code> to get a hook running Python code to lint the repository before a commit.

Beware if you use <code>arc diff</code> without a commit first: your message will be lost if pre-commit raises an error, always use <code>git commit</code> first.

On FreeBSD, there is an issue to build with clang 16+ the ruamel yaml clib library. You can build the FreeBSD port devel/py-ruamel.yaml.clib and copy the .whl to a stable path, then install it in your virtual environment.

On WindRiver, the .whl is available in /opt/python/py311, so you can:

$ python3 -m venv /path/to/your/virtualenv
$ source /path/to/your/virtualenv/bin/activate
$ pip install /opt/python/py311/ruamel.yaml.clib-0.2.8-cp311-cp311-freebsd_14_0_release_p3_amd64.whl
$ pip install pre-commit
$ make
pre-commit install
pre-commit installed at .git/hooks/pre-commit
$ rehash
$ pre-commit

== Refactoring ==

=== Rename a lot of files ===

To move a directory and rename the ''Source file'' headers:

git mv roles/webserver-legacy/nginx/files roles/webserver-alkane/nginx/
cd roles/webserver-alkane/nginx/
find . -type f -name '*.conf' | xargs gsed -i s/webserver-legacy/webserver-alkane/g

== See also ==
* [[/FAQ]] - Frequently asked questions about the Operations repository
* [[How to contribute code]]
* [[Devserver reference]]

Operations grimoire/Operations repository

2026-06-07T11:31:03Z

Dereckson: /* Local computer setup */ Notes for macOS

Our configuration as code is stores in the operations (rOPS) repository.

== Repository layout ==
{| class="wikitable sortable"
|+ Content of rOPS
|-
! Path !! Description
|-
| _modules || Custom execution modules
|-
| _states || Custom states modules
|-
| _tests || Unit tests for custom modules, scripts, tests for repo
|-
| hotfixes || Fixes you need to run to solve a problem on the servers
|-
| pillar || Configuration data structures to use in the states
|-
| roles || The states to deploy, divided in roles and then in units
|-
| utils || Helper scripts to maintain the repository
|-
| terraform || OpenTofu / Terraform infrastructure configuration
|-
| map.jinja || As we deploy on several OS and distros, mapping of packages names or directories
|-
| top.sls || topfile: what we deploy where?
|-
| PORTS || Documentation of the ports used in the configuration
|-
| UIDs || Documentation of the users used in the configuration
|-
| GIDs || Documentation of the groups used in the configuration
|}

== Contributions howto ==
=== Repository source ===
You'll find the Operations repository at https://devcentral.nasqueron.org/source/operations/

If DevCentral isn't available, a mirror of the repository can be found at https://github.com/nasqueron/operations.

=== Workflow of contributions ===
We follow the general workflow is described at [[How to contribute code]].

Before committing a change to the main branch, you can test a deployment on a server.
In that case, merge in main immediately after the deployment as the repository is the source of truth for the server state.

Log what you do on #nasqueron-ops, so it will be included at https://infra.nasqueron.org/servers-log/

=== Code conventions ===
''See also: [[Code conventions]].''

* Python code: run `black` before committing
* YAML: indent with two spaces, including list bullets

<syntaxhighlight lang="yaml">
id:
method:
- somekey: value
- otherkey: value
</syntaxhighlight>

== Environment setup ==

Use of WindRiver is recommended if you wish to get an environment already installed for your contributions.

=== Everywhere setup ===
This section cover topics needed both on our development servers or in your laptop.

==== Python dependencies ====

Create a virtual environment, then install dependencies from {{Ops file|requirements.txt}}:

mkdir -p $HOME/dev/python/ops
python3 -m venv $HOME/dev/python/ops
source $HOME/dev/python/ops/bin/activate
pip install -r requirements.txt

==== Datacube ====

If you're in the ops group, you'll need sometimes to deploy from branches. As our deployment server Complector doesn't have PHP installed (so no arc), you need to exchange branches through our datacube.

On WindRiver:

git remote add datacube /datacube/git/operations.git

Anywhere else:

git remote add datacube ssh://windriver.nasqueron.org/datacube/git/operations.git

If you aren't in the ops groups, and have access to our devserver, you'll still be able to clone or pull from that directory, but not to write there (ie push branches).

=== Local computer setup ===

This section cover topics NOT needed on our development servers.

==== macOS ====

To run tests properly, install first:

brew install bats
brew install python3.13

After loading the virtual environment (see everywhere setup), you can install Salt:

pip install salt==3006.25

Check the version on WindRiver or Complector with <code>salt --versions</code>.

Finally, to run the tests, you need a recent version of make, but the BSD make currently shipped, as of Tahoe 26.5, isn't up-to-date:

brew install gmake
(cd _tests && gmake)

==== Arcanist ====

To use arc with the operations repository, our collection of patches is needed.

If arcanist isn't installed through Git repository, best is to do like on devserver role:

mkdir /opt/phabricator && cd /opt/phabricator
git clone https://github.com/nasqueron/arcanist.git
(cd arcanist && git checkout production)
ln -s /opt/phabricator/arcanist/bin/arc /usr/local/bin/
git clone https://devcentral.nasqueron.org/source/shellcheck-linter.git

If you've already cloned Arcanist repository, switch to our branch production:

git remote add nasqueron git@github.com:nasqueron/arcanist.git
git fetch --all
git checkout production

As of August 2024, there is no plan to make that repository available on DevCentral.

You'll also need shellcheck library-linter library, normally at the same level than your arcanist repository.

==== IDE configuration ====
[[File:PyCharm-TemplateLanguages.png|thumb|right|Screenshot of correctly configured template languages]]
The states .sls file are Jinja2 templates producing YAML files, or "jinja2+yaml". If this case can't be handled by your IDE, it works best to use YAML syntax highlighting.

If you use PyCharm or IntelliJ IDEA Ultimate, you can configure this scheme:

* Allow YAML files to be Jinja2 templates
** Go to Settings > Languages & Frameworks > Template Languages
** Select Jinja2 as template language
** Add YAML in the list
* Open SLS as YAML

== Linting ==

=== pre-commit ===
You can use '''pre-commit''' you can install with <code>make</code> to get a hook running Python code to lint the repository before a commit.

Beware if you use <code>arc diff</code> without a commit first: your message will be lost if pre-commit raises an error, always use <code>git commit</code> first.

On FreeBSD, there is an issue to build with clang 16+ the ruamel yaml clib library. You can build the FreeBSD port devel/py-ruamel.yaml.clib and copy the .whl to a stable path, then install it in your virtual environment.

On WindRiver, the .whl is available in /opt/python/py311, so you can:

$ python3 -m venv /path/to/your/virtualenv
$ source /path/to/your/virtualenv/bin/activate
$ pip install /opt/python/py311/ruamel.yaml.clib-0.2.8-cp311-cp311-freebsd_14_0_release_p3_amd64.whl
$ pip install pre-commit
$ make
pre-commit install
pre-commit installed at .git/hooks/pre-commit
$ rehash
$ pre-commit

== Refactoring ==

=== Rename a lot of files ===

To move a directory and rename the ''Source file'' headers:

git mv roles/webserver-legacy/nginx/files roles/webserver-alkane/nginx/
cd roles/webserver-alkane/nginx/
find . -type f -name '*.conf' | xargs gsed -i s/webserver-legacy/webserver-alkane/g

== See also ==
* [[/FAQ]] - Frequently asked questions about the Operations repository
* [[How to contribute code]]
* [[Devserver reference]]

Keruald

2026-04-19T10:15:01Z

Dereckson: /* Troubleshoot */ +arc unit

'''Keruald''' is a set of libraries to build PHP applications.

== Libraries ==

{| class="wikitable"
|+ List of libraries
|-
! Package name !! Description
|-
| keruald/omnitools || General purpose library
|-
| keruald/globalfunctions || Wrapper to replace our old old sites "core.php" by calls to omnitools
|-
| keruald/commands || Create simple CLI application
|-
| keruald/report || Reporting library
|-
| keruald/health || Site health check
|-
| keruald/dockerhub || Docker Hub, managing payload signatures
|-
| keruald/github || GitHub payloads for webhooks - managing payload signatures, class representations
|-
| keruald/mailgun || Mailgun API client
|-
| keruald/database || Database abstraction layer
|-
| keruald/broker || Wrapper around brokers like RabbitMQ
|}

== Developer guide ==
=== Contribution workflow ===

You'll find the general contribution guide at [[How to contribute code]]. Here some pointers specific for Keruald libraries.

We use a '''monorepo''': clone the rKERUALD repository on DevCentral, you'll find your library as a direct subdirectory on it.

Each subdirectory matches:
* a resource folder, not included in packages, if starting by an underscore _ or a dot .
* a name of a package if starting by a letter, e.g. keruald/commands for commands/

==== New version of a library ====

''This should be automated through Jenkins.''

To publish a new version of a library:
* Create a new tag using library/version format, e.g. foo/1.2.3
* Run <code>./_utils/repo/export-commits-to-manyrepo.sh foo</code>
* Tag with versions the new commits in the library repository (tags propagation isn't currently automated)
** compare <code>git log</code> from monorepo and library repo
** Add tag without any prefix in library repo, e.g. <code>git tag 1.2.3</code>

=== How to import an existing library? ===

First, use [https://github.com/hraban/tomono tomono] in the PARENT DIRECTORY of the monorepo directory.

If the name of the repository is NOT "core", export it as MONOREPO_NAME environment variable.

For example, to import Keruald/GitHub library:

<syntaxhighlight lang="console">
$ export MONOREPO_NAME=keruald
$ echo "ssh://vcs@devcentral.nasqueron.org:5022/source/github.git github" | tomono --continue
From ssh://devcentral.nasqueron.org:5022/source/github
* [new branch] main -> github/main
* [new tag] 0.1.0 -> github/0.1.0
* [new tag] 0.1.1 -> github/0.1.1
* [new tag] 0.2.0 -> github/0.2.0
* [new tag] 0.2.1 -> github/0.2.1
Updated 6 paths from the index
</syntaxhighlight>

Then follow the procedure for a new library to update the monorepo metadata.

Don't forget to use <code>composer dump-autoload</code> to update your local Composer autoloader.

=== How to create a new library? ===
To create a new library quux, we need a new empty manyrepo on DevCentral, a mirror on GitHub and to declare it on Packagist:

# Declare your library in <code>metadata.yml</code>
# Regenerate shared files with <code>make regenerate</code> (you need Python and Jinja2): that will add your repository to files like phpcs.xml
# Create on DevCentral a new repository with a callsign starting by K for Keruald like KQUUX, and "quux" as shortname
# Create on GitHub a new repository called keruald/quux
# Publish on packagist

If the shortname is already taken on DevCentral, it's time to create a new task to provide a map of subdirectory/package repository.

Don't commit anything in newly created repos but contribute as usual by creating quux/ subdirectory in the monorepo

=== Troubleshoot ===
==== Run Arcanist unit tests ====
Before running an arc unit or arc diff command, you need to set the XDEBUG_MODE environment variable to "coverage".

This is done automatically by the Arcanist code installed on devserver role. For local development, use arcanist with the patches from our production branch. It's available at https://github.com/nasqueron/arcanist

==== Error: Class "Keruald\GitHub\XHubSignature" not found ====
When a new library is added to the repository, a new entry is added to composer.json to provide that library.

The Composer autoloader needs then to be updated with <code>composer dump-autoload</code>.

=== Annex A. IDE configuration ===
==== PhpStorm ====

Clone the monorepo on your drive, then open it in PhpStorm to generate an .idea folder.

* Edit keruald.iml with this modules content to declare the code namespaces: https://devcentral.nasqueron.org/P300
* For code style, you can use https://github.com/nasqueron/codestyle/blob/main/JetBrains/php-codestyle.xml

User:Dereckson/Devserver

2026-04-13T12:44:02Z

Dereckson: Log is available per D4057

== MediaWiki ==
=== Logs ===
tail -n 100 -f /var/log/www/dereckson.be/mediawiki-php.log

=== Reinstall ===
* /var/51-wwwroot/mediawiki-dereckson/core: wikimedia/core repository
* /var/51-wwwroot/mediawiki-dereckson/core/extensions: symlink to <code>../extensions</code>
** Clone all needed extensions in /var/51-wwwroot/mediawiki-dereckson/extensions
* /var/51-wwwroot/mediawiki-dereckson/core/skins: symlink to <code>../skins</code>
** Same with git clone ssh://review/mediawiki/skins/
* /var/dataroot/mediawiki.dereckson.be/data contains:
** my_wiki.sqlite for the content
** wikicache.sqlite for the cache

=== Update ===
* '''Core:''' mw-update-core (currently writing it)

=== Create a new extension ===
;I. Wikimedia side
* [[mw:Manual:Developing_extensions]]
* [[mw:Gerrit/New repositories/Requests]]
* [https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?projects=Project-Admins Create task for new Phabricator project]

;II. WindRiver

<syntaxhighlight lang="shell">
$ setenv MW_EXTENSION foo
$ cd ~/dev/wikimedia/mediawiki/extensions
$ git clone ssh://review/mediawiki/extensions/$MW_EXTENSION || git init $MW_EXTENSION
</syntaxhighlight>

Extension is actually stored at /var/51-wwwroot/mediawiki-dereckson/extensions, so can immediately be configured to test locally.

;III. SaaS deployment
* {{Ops file|pillar/saas/mediawiki.sls}}
* [https://devcentral.nasqueron.org/source/saas-mediawiki/browse/main/config/Settings.php config/Settings.php]

=== Troubleshoot ===
==== SQLite database is read-only ====
Runtime error near line 2: attempt to write a readonly database (8)

<syntaxhighlight lang="shell">
chown -R web-be-dereckson-mw:dereckson /var/dataroot/mediawiki.dereckson.be/data
chmod 771 /var/dataroot/mediawiki.dereckson.be/data
chmod 660 /var/dataroot/mediawiki.dereckson.be/data/my_wiki.sqlite
</syntaxhighlight>

=== Permissions to run tests and maintenance scripts ===
To run tests against wiki and maintenance scripts as user can be tricky:

<syntaxhighlight lang="shell">
touch /tmp/mw-GlobalIdGenerator5001-UID-nodeid /tmp/mw-GlobalIdGenerator5001-UUID-128
chown web-be-dereckson-mw:dereckson /tmp/mw-GlobalIdGenerator5001-*
chmod 664 /tmp/mw-GlobalIdGenerator5001-*

chmod 771 /var/dataroot/mediawiki.dereckson.be/data/locks
</syntaxhighlight>

== Zed ==
=== Useful paths ===
{| class="wikitable"
|+ Paths for Zed development
|-
! File path !! Managed by !! Notes
|-
| /usr/local/etc/nginx/vhosts/dereckson.be/zed51.conf || Salt :: webserver-alkane
|-
| /var/51-wwwroot/zed/ || Salt :: wwwroot-51 (still to do) || Git repo: git@github.com:dereckson/zed.git
|-
| /var/dataroot/zed/content/ || Manually || Git repo: git@github.com:hypership/content.git
|}

=== Logs ===
* nginx: <code>tail -n 100 -f /var/log/www/dereckson.be/zed51-error.log</code>
* PHP: <code>tail -n 100 -f /var/log/www/dereckson.be/zed51-php.log</code>

=== Staging ===

'''Note. Keruald is currently symlinked from the monorepo to vendor/keruald.'''

To recreate Zed staging area:

$ cd /var/dataroot/zed/content
$ git init .
$ git config --global --add safe.directory /var/dataroot/zed/content
$ git remote add origin git@github.com:hypership/content.git
$ git fetch --all
$ git reset --hard origin/main
$ git clone git@github.com:hypership/content_users.git users

$ sudo -u web-be-dereckson-zed51 mkdir /var/dataroot/zed/cache/sessions
$ sudo mkdir -p /var/dataroot/zed/content/users/_photos/tn
$ sudo chown -R web-be-dereckson-zed51:dereckson /var/dataroot/zed/content/users/_photos
$ sudo chmod 771 /var/dataroot/zed/content/users/_photos /var/dataroot/zed/content/users/_photos/tn

$ mkdir -p /home/dereckson/dev/zed/hypership
$ cd /home/dereckson/dev/zed/hypership
$ ln -s /var/dataroot/zed/content

Note: Zed currently not defined in wwwroot-51 in rOPS, should be done for /var/51-wwwroot/zed

== IRC ==

=== Troubleshoot ===
==== Error loading module proxy/irc ====
When trying to load proxy module, I got:

22:00:09 -!- Irssi: Error loading module proxy/irc: /home/dereckson/.irssi/modules/libirc_proxy.so: Undefined symbol "g_input_add"

Proxy is now compiled by default, personal module needs to be deleted.

User:Dereckson/Devserver

2026-04-13T12:19:27Z

Dereckson: /* Zed */

== MediaWiki ==
=== Logs ===
tail -n 100 -f /var/log/www/dereckson.be/mediawiki-php.log

=== Reinstall ===
* /var/51-wwwroot/mediawiki-dereckson/core: wikimedia/core repository
* /var/51-wwwroot/mediawiki-dereckson/core/extensions: symlink to <code>../extensions</code>
** Clone all needed extensions in /var/51-wwwroot/mediawiki-dereckson/extensions
* /var/51-wwwroot/mediawiki-dereckson/core/skins: symlink to <code>../skins</code>
** Same with git clone ssh://review/mediawiki/skins/
* /var/dataroot/mediawiki.dereckson.be/data contains:
** my_wiki.sqlite for the content
** wikicache.sqlite for the cache

=== Update ===
* '''Core:''' mw-update-core (currently writing it)

=== Create a new extension ===
;I. Wikimedia side
* [[mw:Manual:Developing_extensions]]
* [[mw:Gerrit/New repositories/Requests]]
* [https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?projects=Project-Admins Create task for new Phabricator project]

;II. WindRiver

<syntaxhighlight lang="shell">
$ setenv MW_EXTENSION foo
$ cd ~/dev/wikimedia/mediawiki/extensions
$ git clone ssh://review/mediawiki/extensions/$MW_EXTENSION || git init $MW_EXTENSION
</syntaxhighlight>

Extension is actually stored at /var/51-wwwroot/mediawiki-dereckson/extensions, so can immediately be configured to test locally.

;III. SaaS deployment
* {{Ops file|pillar/saas/mediawiki.sls}}
* [https://devcentral.nasqueron.org/source/saas-mediawiki/browse/main/config/Settings.php config/Settings.php]

=== Troubleshoot ===
==== SQLite database is read-only ====
Runtime error near line 2: attempt to write a readonly database (8)

<syntaxhighlight lang="shell">
chown -R web-be-dereckson-mw:dereckson /var/dataroot/mediawiki.dereckson.be/data
chmod 771 /var/dataroot/mediawiki.dereckson.be/data
chmod 660 /var/dataroot/mediawiki.dereckson.be/data/my_wiki.sqlite
</syntaxhighlight>

=== Permissions to run tests and maintenance scripts ===
To run tests against wiki and maintenance scripts as user can be tricky:

<syntaxhighlight lang="shell">
touch /tmp/mw-GlobalIdGenerator5001-UID-nodeid /tmp/mw-GlobalIdGenerator5001-UUID-128
chown web-be-dereckson-mw:dereckson /tmp/mw-GlobalIdGenerator5001-*
chmod 664 /tmp/mw-GlobalIdGenerator5001-*

chmod 771 /var/dataroot/mediawiki.dereckson.be/data/locks
</syntaxhighlight>

== Zed ==
=== Useful paths ===
{| class="wikitable"
|+ Paths for Zed development
|-
! File path !! Managed by !! Notes
|-
| /usr/local/etc/nginx/vhosts/dereckson.be/zed51.conf || Salt :: webserver-alkane
|-
| /var/51-wwwroot/zed/ || Salt :: wwwroot-51 (still to do) || Git repo: git@github.com:dereckson/zed.git
|-
| /var/dataroot/zed/content/ || Manually || Git repo: git@github.com:hypership/content.git
|}

=== Logs ===
* nginx: <code>tail -n 100 -f $LOG</code> - still to provision, currently general one
* PHP: <code>tail -n 100 -f /var/log/www/dereckson.be/zed51-php.log</code>

=== Staging ===

'''Note. Keruald is currently symlinked from the monorepo to vendor/keruald.'''

To recreate Zed staging area:

$ cd /var/dataroot/zed/content
$ git init .
$ git config --global --add safe.directory /var/dataroot/zed/content
$ git remote add origin git@github.com:hypership/content.git
$ git fetch --all
$ git reset --hard origin/main
$ git clone git@github.com:hypership/content_users.git users

$ sudo -u web-be-dereckson-zed51 mkdir /var/dataroot/zed/cache/sessions
$ sudo mkdir -p /var/dataroot/zed/content/users/_photos/tn
$ sudo chown -R web-be-dereckson-zed51:dereckson /var/dataroot/zed/content/users/_photos
$ sudo chmod 771 /var/dataroot/zed/content/users/_photos /var/dataroot/zed/content/users/_photos/tn

$ mkdir -p /home/dereckson/dev/zed/hypership
$ cd /home/dereckson/dev/zed/hypership
$ ln -s /var/dataroot/zed/content

Note: Zed currently not defined in wwwroot-51 in rOPS, should be done for /var/51-wwwroot/zed

== IRC ==

=== Troubleshoot ===
==== Error loading module proxy/irc ====
When trying to load proxy module, I got:

22:00:09 -!- Irssi: Error loading module proxy/irc: /home/dereckson/.irssi/modules/libirc_proxy.so: Undefined symbol "g_input_add"

Proxy is now compiled by default, personal module needs to be deleted.

Module:ProjectBox

2026-04-09T17:52:40Z

Dereckson:

-- Module:ProjectInfobox
-- Renders a structured infobox for a project page.
-- Usage: {{#invoke:ProjectInfobox|render}}

local p = {}

-- Split a comma-separated string into a trimmed list.
local function splitList(value)
local items = {}
for item in value:gmatch("[^,]+") do
table.insert(items, mw.text.trim(item))
end
return items
end

-- Wrap a value in a table cell pair (label / value).
local function row(label, value)
return mw.html.create("tr")
:tag("th"):addClass("project-infobox__label"):wikitext(label):done()
:tag("td"):addClass("project-infobox__value"):wikitext(value):done()
end

-- Render participants as a comma-separated inline list.
local function participantCell(raw)
local names = splitList(raw)
local linked = {}
for _, name in ipairs(names) do
table.insert(linked, "[[User:" .. name .. "|" .. name .. "]]")
end
return table.concat(linked, ", ")
end

function p.render(frame)
local args = frame:getParent().args

local group = mw.text.trim(args.group or "")
local project = mw.text.trim(args.project or "")
local participants = mw.text.trim(args.participants or "")
local status = mw.text.trim(args.status or "")
local description = mw.text.trim(args.description or "")

local root = mw.html.create("table"):addClass("project-infobox")
local tbody = root:tag("tbody")

-- Header row: project name as caption
root:tag("caption")
:addClass("project-infobox__title")
:wikitext(project ~= "" and project or "Project")

if group ~= "" then
tbody:node(row("Group", group))
end

if project ~= "" then
tbody:node(row("Project", project))
end

if status ~= "" then
tbody:node(row("Status", status))
end

if participants ~= "" then
tbody:node(row("Participants", participantCell(participants)))
end

if description ~= "" then
tbody:tag("tr")
:tag("td")
:attr("colspan", "2")
:addClass("project-infobox__description")
:wikitext(description)
end

return tostring(root)
end

return p

Module:ProjectBox

2026-04-09T17:41:03Z

Dereckson:

local p = {}

local function renderRow(label, value)
if not value or value == "" then
return ""
end
return string.format(
'<tr><th>%s</th><td>%s</td></tr>',
label, value
)
end

function p.render(frame)
local args = frame:getParent().args

local html = {}

table.insert(html, '<table class="infobox project-infobox">')

-- Title
if args.project and args.project ~= "" then
table.insert(html,
string.format('<tr><th colspan="2" class="infobox-title">%s</th></tr>', args.project)
)
end

-- Rows
table.insert(html, renderRow("Group", args.group))
table.insert(html, renderRow("Participants", args.participants))

table.insert(html, '</table>')

return table.concat(html, '\n')
end

return p

Module:ProjectBox

2026-04-09T17:38:42Z

Dereckson: Created page with "local p = {} local function renderRow(label, value) if not value or value == "" then return "" end return string.format( '<tr><th>%s</th><td>%s</td></tr>', label, value ) end function p.render(frame) local args = frame:getParent().args local html = {} table.insert(html, '{| class="infobox project-infobox"') -- Title (project name) if args.project then table.insert(html, string.format('! colspan="2" c..."

local p = {}

local function renderRow(label, value)
if not value or value == "" then
return ""
end
return string.format(
'<tr><th>%s</th><td>%s</td></tr>',
label, value
)
end

function p.render(frame)
local args = frame:getParent().args

local html = {}
table.insert(html, '{| class="infobox project-infobox"')

-- Title (project name)
if args.project then
table.insert(html, string.format('! colspan="2" class="infobox-title" | %s', args.project))
end

table.insert(html, '|-')

-- Rows
table.insert(html, renderRow("Group", args.group))
table.insert(html, renderRow("Participants", args.participants))

table.insert(html, '|}')

return table.concat(html, '\n')
end

return p

User:Dereckson/Sandbox

2026-04-09T17:37:22Z

Dereckson:

{{#invoke:ProjectBox|render
| project = Some project
| group = Nasqueron Operations SIG
| participants = Dereckson ⬪ ptdradmin
}}

User:Dereckson/Sandbox

2026-04-09T17:37:10Z

Dereckson: Created page with "{{#invoke:ProjectInfobox|render | project = Some project | group = Nasqueron Operations SIG | participants = Dereckson ⬪ ptdradmin }}"

{{#invoke:ProjectInfobox|render
| project = Some project
| group = Nasqueron Operations SIG
| participants = Dereckson ⬪ ptdradmin
}}

Operations grimoire/Anubis

2026-04-09T17:30:58Z

Dereckson:

'''Anubis''' is a proxy to filter out AI scrapers requests. It will allow sites like [[Operations grimoire/DevCentral|DevCentral]] to stop to serve heavy traffic for LLM model training.

__TOC__

== Challenges ==
We want to stop scraping traffic, but let legitimate traffic pass (e.g. CLI requests from Conduit).

Anubis is used by a lot of similar software forges from open-source projects: [https://anubis.techaro.lol/docs/user/known-instances Anubis known instances], but it's unclear if someone already succeed to configure it for Phabricator.

It's our current field of investigation by Gui and Dereckson.

At Wikimedia, Andrew Kostka (WMDE) has some experience deploying it, apparently for Wikibase products.

== Implementation (by Gui) ==
=== Isolation via UNIX Sockets ===
To avoid to maintain a table of TCP ports, each instance is configured to use UNIX sockets for both traffic and metrics:
* '''Main socket:''' <code><nowiki>/run/anubis/{{ instance }}.sock</nowiki></code>
* '''Metrics socket:''' <code><nowiki>/run/anubis/{{ instance }}-metrics.sock</nowiki></code>

=== Dynamic Configuration ===
The Salt states resolve the target application's port from the `docker_containers` pillar. In `anubis_instances`, we define the target:
<pre>
anubis_instances:
devcentral:
target:
service: phabricator
container: devcentral
</pre>

=== Provisioning and Vault ===
Anubis API and Dashboard keys are provisioned in '''Vault''' using a helper script [scripts/fix_anubis_devcentral.sh](cci:7://file:///C:/Users/Gui%20Martinien/Downloads/operations-main/operations-main/scripts/fix_anubis_devcentral.sh:0:0-0:0) and retrieved by Salt during deployment.

== Current work ==
* Gui deployed an experimental run manually on Dwellers to figure how we can build and configure Anubis
* Work to deploy Anubis with Salt: [https://devcentral.nasqueron.org/D3908 D3908]

== Troubleshoot ==
=== Each site must have its own Anubis instance ===
If you serve to protect two different domains, you need two Anubis instances, one per domain.

In December, we noticed strange errors about challenges not found trying to fire the same instance for two different targets from the same domain.

== See also ==
* [https://anubis.techaro.lol/ Anubis website]

Operations grimoire/Anubis

2026-04-09T17:30:21Z

Dereckson: /* Isolation via UNIX Sockets */

'''Anubis''' is a proxy to filter out AI scrapers requests. It will allow sites like [[Operations grimoire/DevCentral|DevCentral]] to stop to serve heavy traffic for LLM model training.

__TOC__

== Challenges ==
We want to stop scraping traffic, but let legitimate traffic pass (e.g. CLI requests from Conduit).

Anubis is used by a lot of similar software forges from open-source projects: [https://anubis.techaro.lol/docs/user/known-instances Anubis known instances], but it's unclear if someone already succeed to configure it for Phabricator.

It's our current field of investigation by Doba Gui and Dereckson.

At Wikimedia, Andrew Kostka (WMDE) has some experience deploying it, apparently for Wikibase products.

== Implementation (by Doba Gui) ==
=== Isolation via UNIX Sockets ===
To avoid to maintain a table of TCP ports, each instance is configured to use UNIX sockets for both traffic and metrics:
* '''Main socket:''' <code><nowiki>/run/anubis/{{ instance }}.sock</nowiki></code>
* '''Metrics socket:''' <code><nowiki>/run/anubis/{{ instance }}-metrics.sock</nowiki></code>

=== Dynamic Configuration ===
The Salt states resolve the target application's port from the `docker_containers` pillar. In `anubis_instances`, we define the target:
<pre>
anubis_instances:
devcentral:
target:
service: phabricator
container: devcentral
</pre>

=== Provisioning and Vault ===
Anubis API and Dashboard keys are provisioned in '''Vault''' using a helper script [scripts/fix_anubis_devcentral.sh](cci:7://file:///C:/Users/Gui%20Martinien/Downloads/operations-main/operations-main/scripts/fix_anubis_devcentral.sh:0:0-0:0) and retrieved by Salt during deployment.

== Current work ==
* Doba deployed an experimental run manually on Dwellers to figure how we can build and configure Anubis
* Work to deploy Anubis with Salt: [https://devcentral.nasqueron.org/D3908 D3908]

== Troubleshoot ==
=== Each site must have its own Anubis instance ===
If you serve to protect two different domains, you need two Anubis instances, one per domain.

In December, we noticed strange errors about challenges not found trying to fire the same instance for two different targets from the same domain.

== See also ==
* [https://anubis.techaro.lol/ Anubis website]

Operations grimoire/Configuration files

2026-04-05T21:07:45Z

Dereckson: Draft

This page lists configuration files managed by our SaltStack operations repository (rOPS).

Each file is deployed from {{Ops file|roles/}} subfolders. The '''Full path''' column shows the path relative to {{Ops file|roles/}}.

== bastion ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| sshd-otp || SSH || {{Ops file|roles/bastion/sshd-otp/files/sshd.rc}} || [https://docs.freebsd.org/en/articles/rc-scripting/ RC scripting]
|-
| sshd-otp || SSH || {{Ops file|roles/bastion/sshd-otp/files/sshd.rc.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| sshd-otp || systemd || {{Ops file|roles/bastion/sshd-otp/files/sshd.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|}

== core ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| certificates || syslog || {{Ops file|roles/core/certificates/files/acmesh/syslog.conf}} || [https://www.rsyslog.com/doc/ rsyslog documentation]
|-
| certificates || Certbot || {{Ops file|roles/core/certificates/files/certbot/cli.ini}} || [https://eff-certbot.readthedocs.io/en/latest/ Certbot documentation]
|-
| login || BSD login || {{Ops file|roles/core/login/files/login.conf}} || [https://man.freebsd.org/cgi/man.cgi?login.conf login.conf man page]
|-
| monitoring || Prometheus || {{Ops file|roles/core/monitoring/files/prometheus-node-exporter.env}} || [https://prometheus.io/docs/ Prometheus documentation]
|-
| monitoring || Prometheus || {{Ops file|roles/core/monitoring/files/rc/prometheus-node-exporter.conf}} || [https://prometheus.io/docs/ Prometheus documentation]
|-
| network || dhclient || {{Ops file|roles/core/network/files/FreeBSD/dhclient6.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| network || dhclient || {{Ops file|roles/core/network/files/FreeBSD/dhclient6.service}} || [https://docs.freebsd.org/en/articles/rc-scripting/ RC scripting]
|-
| network || GRE tunnels || {{Ops file|roles/core/network/files/FreeBSD/gre.conf}} || [https://man.freebsd.org/cgi/man.cgi?gre gre man page]
|-
| network || GRE tunnels || {{Ops file|roles/core/network/files/FreeBSD/netif_gre.rc}} || [https://man.freebsd.org/cgi/man.cgi?gre gre man page]
|-
| network || Network || {{Ops file|roles/core/network/files/FreeBSD/netif_ipv4.rc}} || [https://docs.freebsd.org/en/books/handbook/network/ FreeBSD Handbook - Network]
|-
| network || Network || {{Ops file|roles/core/network/files/FreeBSD/netif_ipv6.rc}} || [https://docs.freebsd.org/en/books/handbook/network/ FreeBSD Handbook - Network]
|-
| network || Routing || {{Ops file|roles/core/network/files/FreeBSD/route-drake.service}} || [https://docs.freebsd.org/en/articles/rc-scripting/ RC scripting]
|-
| network || Routing || {{Ops file|roles/core/network/files/FreeBSD/route_drake.rc}} || [https://man.freebsd.org/cgi/man.cgi?route route man page]
|-
| network || Routing || {{Ops file|roles/core/network/files/FreeBSD/router.rc}} || [https://man.freebsd.org/cgi/man.cgi?route route man page]
|-
| network || Routing || {{Ops file|roles/core/network/files/FreeBSD/routing_ipv4.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| network || Routing || {{Ops file|roles/core/network/files/FreeBSD/routing_ipv6.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| network || Routing || {{Ops file|roles/core/network/files/Linux/routes.conf}} || [https://man7.org/linux/man-pages/man8/ip-route.8.html ip-route man page]
|-
| network || Routing || {{Ops file|roles/core/network/files/Linux/routes.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|-
| network || dhclient || {{Ops file|roles/core/network/files/dhclient6.conf}} || [https://man.freebsd.org/cgi/man.cgi?dhclient.conf dhclient.conf man page]
|-
| network || systemd || {{Ops file|roles/core/network/files/ipv6-tunnels/ipv6-tunnel.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|-
| ntp || NTP || {{Ops file|roles/core/ntp/files/rc/ntpd.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| pf || PF firewall || {{Ops file|roles/core/pf/files/pf.conf}} || [https://man.freebsd.org/cgi/man.cgi?pf.conf pf.conf man page]
|-
| pf || PF firewall || {{Ops file|roles/core/pf/files/rc/pf.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| pf || pflog || {{Ops file|roles/core/pf/files/rc/pflog.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| rc || locate || {{Ops file|roles/core/rc/files/locate.rc}} || [https://man.freebsd.org/cgi/man.cgi?locate.conf locate.conf man page]
|-
| rc || periodic || {{Ops file|roles/core/rc/files/periodic.conf}} || [https://man.freebsd.org/cgi/man.cgi?periodic.conf periodic.conf man page]
|-
| rsyslog || rsyslog || {{Ops file|roles/core/rsyslog/files/default.conf}} || [https://www.rsyslog.com/doc/ rsyslog documentation]
|-
| salt || Salt || {{Ops file|roles/core/salt/files/rc.conf}} || [https://docs.saltproject.io/ Salt documentation]
|-
| salt || Vault || {{Ops file|roles/core/salt/files/vault.conf}} || [https://developer.hashicorp.com/vault/docs Vault documentation]
|-
| sshd || SSH || {{Ops file|roles/core/sshd/files/rc.conf}} || [https://man.freebsd.org/cgi/man.cgi?sshd_config sshd_config man page]
|-
| sysctl || sysctl || {{Ops file|roles/core/sysctl/files/sysctl.conf}} || [https://man.freebsd.org/cgi/man.cgi?sysctl.conf sysctl.conf man page]
|-
| userland-home || nano || {{Ops file|roles/core/userland-home/files/dereckson/.nanorc}} || [https://www.nano-editor.org/dist/latest/nanorc.5.html nanorc man page]
|-
| userland-home || Zsh || {{Ops file|roles/core/userland-home/files/dereckson/.zshrc}} || [https://zsh.sourceforge.io/Doc/ Zsh documentation]
|-
| userland-home || tmux || {{Ops file|roles/core/userland-home/files/dorianwinty/.tmux.conf}} || [https://man.openbsd.org/tmux tmux man page]
|-
| userland-home || Zsh || {{Ops file|roles/core/userland-home/files/dorianwinty/.zshrc}} || [https://zsh.sourceforge.io/Doc/ Zsh documentation]
|-
| userland-software || pkg || {{Ops file|roles/core/userland-software/files/sources/FreeBSD.conf}} || [https://man.freebsd.org/cgi/man.cgi?pkg.conf pkg.conf man page]
|-
| userland-software || pkg || {{Ops file|roles/core/userland-software/files/sources/Nasqueron.conf}} || [https://man.freebsd.org/cgi/man.cgi?pkg.conf pkg.conf man page]
|-
| userland-software || tmux || {{Ops file|roles/core/userland-software/files/tmux.conf}} || [https://man.openbsd.org/tmux tmux man page]
|}

== dbserver-mysql ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| grc || grc || {{Ops file|roles/dbserver-mysql/grc/files/grcat.config}} || [https://github.com/garabik/grc grc documentation]
|-
| mysql-server || MySQL || {{Ops file|roles/dbserver-mysql/mysql-server/files/conf.d/client.cnf}} || [https://dev.mysql.com/doc/refman/en/ MySQL documentation]
|-
| mysql-server || MySQL || {{Ops file|roles/dbserver-mysql/mysql-server/files/conf.d/server.cnf}} || [https://dev.mysql.com/doc/refman/en/ MySQL documentation]
|-
| mysql-server || MySQL || {{Ops file|roles/dbserver-mysql/mysql-server/files/mysql.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| salt || Salt || {{Ops file|roles/dbserver-mysql/salt/files/mysql.conf}} || [https://docs.saltproject.io/ Salt documentation]
|}

== dbserver-pgsql ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| server || PostgreSQL || {{Ops file|roles/dbserver-pgsql/server/files/pg_hba.conf}} || [https://www.postgresql.org/docs/current/ PostgreSQL documentation]
|-
| server || PostgreSQL || {{Ops file|roles/dbserver-pgsql/server/files/postgresql.conf}} || [https://www.postgresql.org/docs/current/ PostgreSQL documentation]
|-
| server || PostgreSQL || {{Ops file|roles/dbserver-pgsql/server/files/postgresql.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|}

== devserver ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| api-exec || API-exec || {{Ops file|roles/devserver/api-exec/files/api-exec.conf}} || ''custom config, still to document''
|-
| api-exec || API-exec || {{Ops file|roles/devserver/api-exec/files/rc/api_exec.conf}} || [https://docs.freebsd.org/en/articles/rc-scripting/ RC scripting]
|-
| mail || Sendmail || {{Ops file|roles/devserver/mail/files/sendmail.rc}} || [https://man.freebsd.org/cgi/man.cgi?sendmail sendmail man page]
|-
| pkg || pkg || {{Ops file|roles/devserver/pkg/files/nasqueron.conf}} || [https://man.freebsd.org/cgi/man.cgi?pkg.conf pkg.conf man page]
|-
| poudriere || poudriere || {{Ops file|roles/devserver/poudriere/files/poudriere.conf}} || [https://github.com/freebsd/poudriere/wiki poudriere documentation]
|-
| userland-home || Git || {{Ops file|roles/devserver/userland-home/files/dereckson/.gitconfig}} || [https://git-scm.com/docs/git-config git-config documentation]
|-
| userland-home || Mercurial || {{Ops file|roles/devserver/userland-home/files/dereckson/.hgrc}} || [https://www.mercurial-scm.org/doc/hgrc.5.html hgrc man page]
|-
| userland-home || Shell || {{Ops file|roles/devserver/userland-home/files/dereckson/.shell.yml}} || ''custom config, still to document''
|-
| userland-home || tmux || {{Ops file|roles/devserver/userland-home/files/dereckson/.tmux.conf}} || [https://man.openbsd.org/tmux tmux man page]
|-
| userland-home || Zsh || {{Ops file|roles/devserver/userland-home/files/dereckson/.zshrc-misc-aliases}} || [https://zsh.sourceforge.io/Doc/ Zsh documentation]
|-
| userland-software || ccache || {{Ops file|roles/devserver/userland-software/files/ccache.conf}} || [https://ccache.dev/manual/latest.html ccache documentation]
|-
| userland-software || make || {{Ops file|roles/devserver/userland-software/files/make.conf}} || [https://man.freebsd.org/cgi/man.cgi?make.conf make.conf man page]
|-
| userland-software || Notifications || {{Ops file|roles/devserver/userland-software/files/notifications.conf}} || ''custom config, still to document''
|-
| userland-software || PEFS || {{Ops file|roles/devserver/userland-software/files/pefs.conf}} || [https://wiki.freebsd.org/PEFS PEFS documentation]
|-
| userland-software || Transmission || {{Ops file|roles/devserver/userland-software/files/transmission.rc}} || [https://github.com/transmission/transmission/blob/main/docs/Editing-Configuration-Files.md Transmission documentation]
|-
| userland-software || URL configuration || {{Ops file|roles/devserver/userland-software/files/url.yml}} || ''custom config, still to document''
|-
| webserver-home || nginx || {{Ops file|roles/devserver/webserver-home/files/001-server.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|}

== dns ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| knot || Knot DNS || {{Ops file|roles/dns/knot/files/knot.conf}} || [https://www.knot-dns.cz/docs/ Knot DNS documentation]
|-
| knot || Knot DNS || {{Ops file|roles/dns/knot/files/rc/knot.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|}

== grafana ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| grafana || Grafana || {{Ops file|roles/grafana/grafana/files/grafana.ini}} || [https://grafana.com/docs/grafana/latest/ Grafana documentation]
|-
| grafana || Grafana || {{Ops file|roles/grafana/grafana/files/rc/grafana.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|}

== mailserver ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| dkim || OpenDKIM || {{Ops file|roles/mailserver/dkim/files/opendkim.conf}} || [http://www.opendkim.org/opendkim.conf.5.html opendkim.conf man page]
|-
| dkim || OpenDKIM || {{Ops file|roles/mailserver/dkim/files/rc/opendkim.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| dovecot || Dovecot || {{Ops file|roles/mailserver/dovecot/files/conf.d/10-auth.conf}} || [https://doc.dovecot.org/ Dovecot documentation]
|-
| dovecot || Dovecot || {{Ops file|roles/mailserver/dovecot/files/conf.d/10-mail.conf}} || [https://doc.dovecot.org/ Dovecot documentation]
|-
| dovecot || Dovecot || {{Ops file|roles/mailserver/dovecot/files/conf.d/10-main-services.conf}} || [https://doc.dovecot.org/ Dovecot documentation]
|-
| dovecot || Dovecot || {{Ops file|roles/mailserver/dovecot/files/conf.d/10-metrics.conf}} || [https://doc.dovecot.org/ Dovecot documentation]
|-
| dovecot || Dovecot || {{Ops file|roles/mailserver/dovecot/files/conf.d/10-ssl.conf}} || [https://doc.dovecot.org/ Dovecot documentation]
|-
| dovecot || Dovecot || {{Ops file|roles/mailserver/dovecot/files/dovecot.conf}} || [https://doc.dovecot.org/ Dovecot documentation]
|-
| vimbadmin || ViMbAdmin || {{Ops file|roles/mailserver/vimbadmin/files/application.ini}} || [https://github.com/opensolutions/ViMbAdmin ViMbAdmin documentation]
|}

== netbox ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| netbox || NetBox || {{Ops file|roles/netbox/netbox/files/rc/netbox.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|}

== opensearch ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| dashboards || systemd || {{Ops file|roles/opensearch/dashboards/files/dashboards.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|-
| opensearch || OpenSearch || {{Ops file|roles/opensearch/opensearch/files/account.conf}} || [https://opensearch.org/docs/latest/ OpenSearch documentation]
|-
| opensearch || OpenSearch || {{Ops file|roles/opensearch/opensearch/files/opensearch.conf}} || [https://opensearch.org/docs/latest/ OpenSearch documentation]
|-
| opensearch || systemd || {{Ops file|roles/opensearch/opensearch/files/opensearch.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|}

== paas-docker ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| containers || Docker Compose || {{Ops file|roles/paas-docker/containers/files/relay/dev.yml}} || [https://docs.docker.com/compose/ Docker Compose documentation]
|-
| containers || Sentry || {{Ops file|roles/paas-docker/containers/files/sentry/etc/config.yml}} || [https://develop.sentry.dev/self-hosted/ Sentry self-hosted documentation]
|-
| containers || Symbolicator || {{Ops file|roles/paas-docker/containers/files/symbolicator/config.yml}} || [https://getsentry.github.io/symbolicator/ Symbolicator documentation]
|-
| containers || Vault || {{Ops file|roles/paas-docker/containers/files/vault/vault.hcl}} || [https://developer.hashicorp.com/vault/docs Vault documentation]
|-
| devel || systemd || {{Ops file|roles/paas-docker/devel/files/socket.conf}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|-
| kernel || tuned || {{Ops file|roles/paas-docker/kernel/files/tuned.conf}} || [https://tuned-project.org/ tuned documentation]
|-
| nginx || logrotate || {{Ops file|roles/paas-docker/nginx/files/logrotate/nginx.conf}} || [https://man.freebsd.org/cgi/man.cgi?logrotate logrotate man page]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/_default.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/acme_dns.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/auth-grove.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/base/fallback.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/base/server.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/bugzilla.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/cachet.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/etherpad.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/hauk.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/jenkins.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/notifications.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/openfire.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/orbeon.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/penpot_web.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/phabricator.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/pixelfed.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/rabbitmq.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/registry.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/sentry.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/tommy.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/vault.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| systemd-timers || systemd || {{Ops file|roles/paas-docker/systemd-timers/files/report.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|-
| systemd-timers || systemd || {{Ops file|roles/paas-docker/systemd-timers/files/report.timer}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|-
| systemd-unit || systemd || {{Ops file|roles/paas-docker/systemd-unit/files/docker-containers.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|}

== paas-jails ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| jails || Jails || {{Ops file|roles/paas-jails/jails/files/ezjail.rc}} || [https://man.freebsd.org/cgi/man.cgi?jail jail man page]
|-
| jails || Jails || {{Ops file|roles/paas-jails/jails/files/jail.rc}} || [https://man.freebsd.org/cgi/man.cgi?jail jail man page]
|-
| jails || Network || {{Ops file|roles/paas-jails/jails/files/netif.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| jails || DNS resolver || {{Ops file|roles/paas-jails/jails/files/resolv.conf}} || [https://man.freebsd.org/cgi/man.cgi?resolv.conf resolv.conf man page]
|}

== prometheus ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| prometheus || Prometheus || {{Ops file|roles/prometheus/prometheus/files/prometheus.yml}} || [https://prometheus.io/docs/ Prometheus documentation]
|-
| prometheus || Prometheus || {{Ops file|roles/prometheus/prometheus/files/rc/prometheus.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| prometheus || newsyslog || {{Ops file|roles/prometheus/prometheus/files/syslog/newsyslog.conf}} || [https://man.freebsd.org/cgi/man.cgi?newsyslog.conf newsyslog.conf man page]
|-
| prometheus || newsyslog || {{Ops file|roles/prometheus/prometheus/files/syslog/prometheus.conf}} || [https://man.freebsd.org/cgi/man.cgi?newsyslog.conf newsyslog.conf man page]
|}

== redis ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| server || Redis || {{Ops file|roles/redis/server/files/redis.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|}

== reports ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| rhyne-wyse || Rhyne-Wyse || {{Ops file|roles/reports/rhyne-wyse/files/secrets.conf}} || [https://docs.nasqueron.org/secretsmith/connect.html#configuration-file secretsmith]
|-
| rhyne-wyse || Rhyne-Wyse || {{Ops file|roles/reports/rhyne-wyse/files/syslog/rhyne-wyse.conf}} || [https://man.freebsd.org/cgi/man.cgi?syslog.conf(5) syslog.conf]
|}

== router ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| carp || CARP || {{Ops file|roles/router/carp/files/carp.conf}} || [https://man.freebsd.org/cgi/man.cgi?carp carp man page]
|-
| carp || CARP || {{Ops file|roles/router/carp/files/carp.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| carp || CARP || {{Ops file|roles/router/carp/files/secrets.conf}} || [https://docs.nasqueron.org/secretsmith/connect.html#configuration-file secretsmith]
|}

== saas-mediawiki ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| nginx || nginx || {{Ops file|roles/saas-mediawiki/nginx/files/vhosts/nasqueron.org/agora.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/saas-mediawiki/nginx/files/vhosts/nasqueron.org/wikis.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/saas-mediawiki/nginx/files/vhosts/test.ook.space/mediawiki.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| saas || Environment || {{Ops file|roles/saas-mediawiki/saas/files/dot.env}} ||
|}

== salt-primary ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| api || Salt || {{Ops file|roles/salt-primary/api/files/api.conf}} || [https://docs.saltproject.io/ Salt documentation]
|-
| api || Salt || {{Ops file|roles/salt-primary/api/files/salt_api.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| config || Salt || {{Ops file|roles/salt-primary/config/files/pillar-tower.conf}} || [https://jgraichen.github.io/salt-tower/latest/tower/ salt-tower]
|-
| salt-wrapper || Salt || {{Ops file|roles/salt-primary/salt-wrapper/files/salt-wrapper.conf}} || [https://docs.nasqueron.org/salt-wrapper/admin.html#configuration-file salt-wrapper]
|}

== shellserver ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| database || MySQL || {{Ops file|roles/shellserver/database/files/my.cnf}} || [https://dev.mysql.com/doc/refman/en/ MySQL documentation]
|-
| odderon || systemd || {{Ops file|roles/shellserver/odderon/files/odderon.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|-
| odderon || Odderon || {{Ops file|roles/shellserver/odderon/files/servers.ini}} || [https://github.com/JiggyStardust/Odderon Odderon repository]
|-
| odderon || Odderon || {{Ops file|roles/shellserver/odderon/files/setup.ini}} || [https://github.com/JiggyStardust/Odderon Odderon repository]
|-
| userland-software || nano || {{Ops file|roles/shellserver/userland-software/files/nanorc}} || [https://www.nano-editor.org/dist/latest/nanorc.5.html nanorc man page]
|-
| userland-software || oidentd || {{Ops file|roles/shellserver/userland-software/files/oidentd.conf}} || [https://oidentd.janikrabe.com/doc/2.5/manual oidentd documentation]
|-
| userland-software || oidentd || {{Ops file|roles/shellserver/userland-software/files/oidentd.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| vault || Salt || {{Ops file|roles/shellserver/vault/files/salt-vault.conf}} || [https://docs.saltproject.io/ Salt documentation]
|-
| vault || Vault || {{Ops file|roles/shellserver/vault/files/salt.hcl}} || [https://developer.hashicorp.com/vault/docs Vault documentation]
|-
| vault || Vault || {{Ops file|roles/shellserver/vault/files/vault.hcl}} || [https://developer.hashicorp.com/vault/docs Vault documentation]
|-
| vault || systemd || {{Ops file|roles/shellserver/vault/files/vault.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|-
| web-hosting || nginx || {{Ops file|roles/shellserver/web-hosting/files/eglide/nginx/vhosts/000-fallback.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| web-hosting || nginx || {{Ops file|roles/shellserver/web-hosting/files/eglide/nginx/vhosts/001-server.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|}

== vault ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| policies || Vault || {{Ops file|roles/vault/policies/files/admin.hcl}} || [https://developer.hashicorp.com/vault/tutorials/get-started/introduction-policies Vault policy]
|-
| policies || Vault || {{Ops file|roles/vault/policies/files/airflow.hcl}} || [https://developer.hashicorp.com/vault/tutorials/get-started/introduction-policies Vault policy]
|-
| policies || Vault || {{Ops file|roles/vault/policies/files/monitoring.hcl}} || [https://developer.hashicorp.com/vault/tutorials/get-started/introduction-policies Vault policy]
|-
| policies || Vault || {{Ops file|roles/vault/policies/files/salt-primary.hcl}} || [https://developer.hashicorp.com/vault/tutorials/get-started/introduction-policies Vault policy]
|-
| policies || Vault || {{Ops file|roles/vault/policies/files/sentry.hcl}} || [https://developer.hashicorp.com/vault/tutorials/get-started/introduction-policies Vault policy]
|-
| policies || Vault || {{Ops file|roles/vault/policies/files/vault_bootstrap.hcl}} || [https://developer.hashicorp.com/vault/tutorials/get-started/introduction-policies Vault policy]
|-
| vault || Vault || {{Ops file|roles/vault/vault/files/vault.hcl}} || [https://developer.hashicorp.com/vault/docs Vault documentation]
|}

== viperserv ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| eggdrop || Eggdrop || {{Ops file|roles/viperserv/eggdrop/files/eggdrop-bot.conf}} || [https://docs.eggheads.org/ Eggdrop documentation]
|-
| eggdrop || Eggdrop || {{Ops file|roles/viperserv/eggdrop/files/eggdrop-core.conf}} || [https://docs.eggheads.org/ Eggdrop documentation]
|-
| eggdrop || Eggdrop || {{Ops file|roles/viperserv/eggdrop/files/eggdrops-live.conf}} || [https://docs.eggheads.org/ Eggdrop documentation]
|}

== webserver-alkane ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| alkane || Alkane || {{Ops file|roles/webserver-alkane/alkane/files/alkane.conf}} || [[Operations grimoire/Alkane|Alkane]]
|-
| alkane || Alkane || {{Ops file|roles/webserver-alkane/alkane/files/alkane.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]

|-
| monitoring || PHP-FPM exporter || {{Ops file|roles/webserver-alkane/monitoring/files/rc/phpfpm_exporter.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/newsyslog/nginx.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/dereckson.be/assets.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/dereckson.be/hg.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/dereckson.be/mediawiki.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/dereckson.be/scherzo.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/dereckson.be/www.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/dereckson.be/www51.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/dereckson.be/zed51.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/espace-win.org/cosmo.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/espace-win.org/grip.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/espace-win.org/www.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/hypership.space/www.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/admin.mail.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/api.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/api51.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/assets.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/autoconfig.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/daeghrefn.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/docker.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/docs.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/drive.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/ftp.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/grafana.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/infra.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/join.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/labs.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/launch.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/mail.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/obsidian51.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/packages.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/rain.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/tools51.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/trustspace.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/www.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/www51.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/test.ook.space/migration.mediawiki.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/wolfplex.org/api.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/wolfplex.org/assets.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/wolfplex.org/www.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| php || PHP-FPM || {{Ops file|roles/webserver-alkane/php/files/php-fpm-pool.conf}} || [https://www.php.net/manual/en/install.fpm.configuration.php PHP-FPM documentation]
|-
| php || PHP-FPM || {{Ops file|roles/webserver-alkane/php/files/php-fpm.conf}} || [https://www.php.net/manual/en/install.fpm.configuration.php PHP-FPM documentation]
|-
| php || PHP-FPM || {{Ops file|roles/webserver-alkane/php/files/php.ini}} || [https://www.php.net/manual/en/configuration.file.php PHP configuration file]
|}

== webserver-content ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| _generic || Environment || {{Ops file|roles/webserver-content/_generic/files/dot.env}} || [https://github.com/vlucas/phpdotenv dotenv]
|-
| org/nasqueron || Git || {{Ops file|roles/webserver-content/org/nasqueron/files/git-safe.conf}} || [https://git-scm.com/docs/git-config git-config documentation]
|}

== webserver-core ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| nginx || nginx || {{Ops file|roles/webserver-core/nginx/files/nginx.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-core/nginx/files/nginx.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|}

== webserver-legacy ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| php-sites || PHP-FPM || {{Ops file|roles/webserver-legacy/php-sites/files/php-fpm-pool.conf}} || [https://www.php.net/manual/en/install.fpm.configuration.php PHP-FPM documentation]
|-
| php-sites || PHP-FPM || {{Ops file|roles/webserver-legacy/php-sites/files/php-fpm.conf}} || [https://www.php.net/manual/en/install.fpm.configuration.php PHP-FPM documentation]
|-
| php-sites || PHP-FPM || {{Ops file|roles/webserver-legacy/php-sites/files/php.ini}} || [https://www.php.net/manual/en/configuration.file.php PHP configuration file]
|}

Operations grimoire/Services

2026-04-05T20:50:48Z

Dereckson: /* FreeBSD rc */ Basic instructions

Software running as daemons should be set as services to manage them at OS level a standard way.

== Systemd, rc and runit ==

Nasqueron infrastructure uses 3 services software:

{| class="wikitable"
|+ Service management
|-
! OS !! Use case !! Software !! Commands
|-
| FreeBSD || Standard || rc || service <service> <command>
|-
| Linux || Standard || systemd || systemctl <command> <service>
|-
| Linux || Docker containers || runit || sv <service> <command>
|}

Note how systemd inverts the general order by putting the command before the service.

== Systemd ==
=== Services ===
Search for .service file in operations repository for an idea.
It's well documented on ArchLinux wiki and freedesktop.org site.

References:
* https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html
* https://wiki.archlinux.org/title/Systemd

=== Timers ===
* Generally better to use a systemd service and a systemd timer than a crontab entry on Linux
* Don't forget to start the timer, see [https://devcentral.nasqueron.org/D3674#57039 this comment on D3674] for a demonstration

=== Howto for operations repository ===
You can follow [https://www.dereckson.be/blog/2017/01/25/deploy-a-darkbot-or-a-simple-generic-service-with-saltstack-part-1/ this tutorial] to deploy a service on Nasqueron infrastructure, it covers the step from software deployment, configuration, user creation and a systemd service.

== FreeBSD rc ==
=== Structure of a rc configuration file ===
Each service is configured in /etc/rc.conf.d/<service> file or by all the files in /etc/rc.conf.d/<service>/ directory.

Those files follow [https://man.freebsd.org/cgi/man.cgi?rc.conf rc.conf syntax] and use:
* <service>_enable="YES" to indicate auto start of the service
* various <service>_<key>=<value> per service documentation

To know all the available options for a service the best is to read the documentation at the top of every service, located in
/usr/local/etc/rc.d for applications and /etc/rc.d for the base system.

=== Template for operations repository ===
If you need to add a rc service, we've a template for the file: follow [https://devcentral.nasqueron.org/D3571 D3571 instructions]

[[Category:Operations grimoire|Services]]

Operations grimoire

2026-04-05T20:41:45Z

Dereckson: /* Appendices */

[[File:Nasqueron Operations Grimoire.jpg|thumb|320px|right|The Nasqueron operations grimoire tries to document the more arcane aspects of our complex infrastructure.]]

Welcome to the Nasqueron operations grimoire (NOG).

This grimoire is a reference about our infrastructure and services hosted with procedures we follow to build, maintain and deploy.

Our infrastructure is open, mainly documented in {{repo|operations}} repository, and we actively encourage contributions from the community.

== Infrastructure ==
* [[/Environments]]
* [[/Kubernetes]]
* [[/Docker engine]]
* [[/Salt]]

=== OS-specific ===
;By OS
* [[/FreeBSD]]
* [[/RHEL]]

;All OSes
* [[/NTP]]
* [[/Packages repository]]
* [[/Services]]: systemd, runit and rc

=== Storage ===
* [[/ZFS]]

=== Observability ===
* [[/Grafana]]
* [[/Logs]]
* [[/Prometheus]]

=== Network ===
* [[/Network]]
* [[/DNS]]
* [[/Firewall]]
* [[/IPv6]]
* [https://netbox.nasqueron.org/ NetBox]

== Services ==
=== Core services ===
; Messages queues
* [[/Kafka]]
* [[/RabbitMQ]]

; Databases
* [[/MySQL]]
* [[/PostgreSQL]]

; Ops
* [[/NetBox]]

=== Identity management ===
* [[/Login]] (Auth Grove)

=== Collaborative tools ===
* [[/DevCentral]] (Phabricator)
* [[/Etherpad]]
* [[/Mumble]]
* [[/Mastodon]] (social.nasqueron.org)
* [[/Openfire]] (XMPP)

=== IRC bots ===
* [[/Dæghrefn]] (eggdrop)
* [[/Odderon]] (darkbot)

=== Mail ===
* [[/Mail]]
* [[/Mail/DKIM]]
* [[/Mail/Sympa]]

=== Web ===
; Common documentation for all webserver roles
* [[/Web/Headers]]

; Where to host?
* [[/Docker engine]] for Docker containers front-end
* [[/Alkane]] for PHP and static sites

; SaaS for common applications
* [[MediaWiki SaaS]]
* [[/WordPress]]

; Other sites
* [[/Sites on Eglide]]
* [[/Sites on Ysul]] (currently migrating to Alkane)

; Services for web applications
* [[/Anubis]] if you need to protect from LLM scraping traffic
* [[/Orbeon]] if you're in need of a form

=== CI/CD ===
* [[/Broker]]
* [[/Docker registry]]
* [[/Jenkins]]
* [[/Notifications center]]
* [[/Sentry]]
* [[/Vault]]

=== Shellserver ===
* [[/Eglide/Vault]]

== Services configuration ==
''This section contains general information not related to a specific service.''
* [[/TLS certificates]] (Let's encrypt / letsencrypt)

== Checklists ==
=== SSH ===
* [[/Recommended SSH configuration]]

=== Infrastructure ===
* [[/How to add a server to the Nasqueron servers pool]]
* [[/How to attach a new virtual disk]]
* [[/Reboot checklist]]

=== Network ===
* [[/Checklist router post-restart]]

=== Docker ===
* [[/Restart a Docker engine]]
* [[/Dwellers to DevCentral]]
* [[/Git operations in production containers]]
* [[/Add a service to Docker PaaS]]
* [[/Docker Hub]]

=== Salt ===
* [[/Operations repository]]
* [[/Deploy with Salt]]
* [[/Create and revoke user accounts on Salt servers]]
* [[/Provision user homefiles]]

=== Terraform / OpenTofu ===
* [[/Deploy with Terraform]]

== SIG ==
* [[/Onboarding]]

== Appendices ==
* [[/Changelog]]
* [[/Contacts]]
* [[/Configuration files]]
* [[/Contribute]]
* [[/Decom]]
* [[/Evaluated products]]
* [[/External services]]
* [[/Incidents]]
* [[/Legacy archive]]
* [[/OID]]
* [[/Old content report]]
* [[/Policies]]
* [[/Who]]

[[Category:Operations grimoire|*]]
[[Category:Reference]]

Code conventions

2026-04-03T22:35:38Z

Dereckson: /* Salt */ Double quotes

== All languages ==

* Don't use more complicated constructs like ternary operators
* [http://jeroendedauw.github.io/slides/craftmanship/functions/#/1 Keep functions short and simple].
* Define explicitly methods visibility, as several languages have different default values (e.g. private for C# class members, public for PHP methods)
* Comments to document a method are written at the singular 3rd person (we seem to have moved to infinitive recently, we need to take a decision here)

== C ==
If you use [http://clang.llvm.org/docs/ClangFormat.html ClangFormat], a [https://github.com/dereckson/rabbitmq-tcl/blob/master/.clang-format .clang-format file] is available.

== JavaScript ==
The following conventions are used:
* K&R, 1TBS variant, including for functions
* 4 spaces as indent
* Use modern JavaScript idioms like <code>const</code> and <code>let</code> instead of <code>var</code>
* Consider to use async code for events-driven development, especially for servers

== PHP ==
The following conventions are used:
* K&R, 1TBS variant, including for functions
* 4 spaces as indent
* The keywords <code>true</code>, <code>false</code> and <code>null</code> must be in lower case.
* Arrays use short syntax
* Array elements ends with a comma
* Functions, methods and class names use camel case

If you use PhpStorm or another JetBrains IDE, you can import [https://github.com/nasqueron/codestyle/blob/master/JetBrains/php-codestyle.xml JetBrains/php-codestyle.xml] from the codestyle repository as a code style (Settings or Default Settings > Editor > Code Style > PHP > click on the wheel icon > Import Scheme > Intellij IDEA codestyle XML).

If you want to lint a project with phpcs, you can require the Composer package <code>nasqueron/codestyle</code> and use the following <kbd>phpcs.xml<kbd> standard file:

<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<ruleset>
<rule ref="vendor/nasqueron/codestyle/CodeSniffer" />
<file>.</file>
<exclude-pattern>\.git/</exclude-pattern>
<exclude-pattern>vendor/</exclude-pattern>
</ruleset>
</syntaxhighlight>

== Python ==
=== Code style ===
'''2023.''' We follow [https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html black style], so use black utility (<code>pip install black</code>). As such, you need to configure Flake8 to ignore rule E203.

'''2015.''' We follow [https://www.python.org/dev/peps/pep-0008/ PEP-8].

=== Templates ===
A template exists for a new Python command: [https://devcentral.nasqueron.org/source/snippets/browse/main/python/command.py python/command.py]

In packages, empty __init__.py files can follow [https://devcentral.nasqueron.org/source/merge-dictionaries/browse/main/src/mergedictionaries/utils/__init__.py;eaf5bc2c21118454837e8148147606c19d4afff7 this example].

=== Configuration files ===
Allow empty configuration files. For example, the YAML parser will return None if the file exists but is empty, we can catch that and return default instead:

<syntaxhighlight lang="python">
with open(get_configuration_path()) as fd:
return yaml.safe_load(fd) or {}
</syntaxhighlight>

== Rust ==
'''2023.''' Automated codestyle (black in Python, clang-format in Rust) seems preferable. As such, a style compatible with <code>rustfmt</code> is needed to be able to format using <code>cargo fmt</code>. You can add to your project [https://devcentral.nasqueron.org/source/codestyle/browse/main/rust/rustfmt.toml rust/rustfmt.toml in codestyle] to configure it.

'''2015.''' We followed "Rust default style", described at [https://web.archive.org/web/20170320083740/http://aturon.github.io/ https://aturon.github.io/]. It's mainly a K&R, 1TBS variant.

Use trailing comma for elements in every struct/impl/etc.

=== Threads ===
Standard library isn't the most ergonomic for threads programming, those crate allows more efficient and legible code:
* [https://docs.rs/crossbeam-channel/latest/crossbeam_channel/ crossbeam_channel] for mpmc (multiple producers, multiple consumers)
* [https://docs.rs/parking_lot/latest/parking_lot/type.Mutex.html parking_lot] for Mutex

== Salt ==
=== Style ===
;Whitespaces
* Indent with two spaces
* YAML lists use indented bullets

<syntaxhighlight lang="yaml">
id:
method:
- somekey: value
- otherkey: value
</syntaxhighlight>

;Quotes
* Use double quotes in Python, Salt and Jinja expressions

=== Tips ===

;Files provisioned
* When you ask to download a file remotely, you need a source hash, pick SHA256 as algo
* Each file provisioned from the Salt repository must contains an header explaining the fact, with the full path in the rOPS repo

;BSD and Linux distros compatible states
* populate the map.jinja file with OS logic (e.g. `dirs` for /etc vs /usr/local/etc)
* when you've a specific set of tasks to do for one OS/distro, it's acceptable to enclose it in a state by an if block

=== Vocabulary ===

;Domain names
:To refer to the fully qualified domain name sub.domain.tld, use '''fqdn'''. To split the domains in part, use '''domain''' and '''subdomain'''. This is important to understand a state without having to refer to the associated pillar to disambig domain.

== Shell scripts ==
;UNIX agnosticism:
* Don't assume absolute path, use <code>#!/usr/bin/env bash</code> and not <code>#!/bin/bash</code> (it could be elsewhere on BSD or Solaris)
* Use `sh` as must as possible, try to avoid <code>bash</code>, document exceptions rationale in your commits

;Whitespaces:
* One whitespace line between shebang and actual content
* 4 spaces as indent

;File names:
* We use hyphens (-) as separators, not underscores or camelcase
* Filename should start by a verb if it performs an action
* Don't use .sh extensions when deployed as command
** sometimes you'll see them on Phabricator pastes' titles, but it has been added there, so Phab knows shell syntax highlighting should be used
** '''Tip.''' You can use .sh in src/ to help linters, but then provide a Makefile to install it under correct name without extension. Same for operations repository where everything uses .sh, but when deploying with file.managed the extension is omitted

;Templates
* New command: [https://devcentral.nasqueron.org/source/snippets/browse/main/shell/script.sh shell/script.sh]

== TCL ==

* Indent with 4 spaces, as of 2026-03-20
* Keep blocks visually separated
* Use Tcl primitives instead of manual parsing for strings: split, lindex, lrange, join
* Avoid regex unless necessary
* List expansion {*} instead of eval

; ViperServ development
* If you build a full new system, all procedures must be defined in a namespace
* Use fully-qualified names (::namespace::proc) for procedure definitions and cross-namespace calls
* Separate low-level request logic from API-specific methods

== Makefile ==
UNIX agnosticism:
* Test your makefile against BSD make, and document in README.md to use GNU Makefile (gmake) when it's not convenient to keep compatibility

Presentation:
* Create a block with the general targets, then sections with your targets organized by categories/goals/parts

Tip:
* It's possible to provision BSDmakefile and GNUmakefile when UNIX agnosticism doesn't work.

== Structured data formats (YAML, JSON, XML) ==
The number of spaces depend if the format is usually heavily hierarchized or not:

* 2 spaces for JSON and YAML
* 4 spaces for XML, TOML and other configuration files

== Utilities ==

The https://github.com/nasqueron/codestyle repository contains resource to help to respect code convention, like a phpcs ruleset, a configuration ready for PhpStorm, IntelliJ and other JetBrains editors, or a clang-format configuration file.

== Troubleshoot ==
=== Fix indent issues ===
The <code>expand</code> utility converts tabs into spaces, while <code>unexpand</code> convert spaces into tabs.

Switch a file from tab indent to 4 spaces indent:

$ expand -t 4 foo.sh > a
$ cat a > foo.sh
$ rm a

(Avoid <code>mv</code> for shell scripts as your foo.sh has probably a 755 chmod, and a will probably have a 644 chmod, assuming 022 as umask)

Switch a file indent with 2 spaces to 4 spaces:

$ unexpand -t 2 JetBrains/php-codestyle.xml > a
$ expand -t 4 a > JetBrains/php-codestyle.xml

This last technique can be used in batch [https://gist.github.com/dereckson/80a746b408c0cf0b688a09db31d5c881 with this reindent script]:

$ git ls-files | xargs -n1 reindent 2 4

[[Category:Reference]]
[[Category:Contributor guide]]

WindRiver

2026-04-03T17:19:51Z

Dereckson:

WindRiver is an FreeBSD 14 bare metal server for Nasqueron general-purpose development.

It supersedes [[Ysul]].

Documentation: [[Devserver reference]]

== Basic information ==
* '''IP:'''
** 195.154.30.15 <strike>51.159.17.168 since 2023-06-14. Previously 51.159.18.59.</strike>
** 2a02:578:4f0d:0:30d0:7b22:6cde:a52e (native, still to migrate)
** 2001:bc8:6005:5:aa1e:84ff:fef3:5d9c (future through HE)
* '''Hostname:''' windriver.nasqueron.org
* '''Homepage:''' https://windriver.nasqueron.org/
* '''Configuration:''' <strike>64 Gb RAM, Xeon E3 1240 V6, 2x 500 GB SSD ("Pro-6-S")</strike> 96 Gb. RAM, Xeon E5-1650 v3, 3x 500 GB SSD ("Pro-4-L")
* '''ISP:''' [http://www.online.net Online] (FR)
* '''Network:''' Illiad (FR)
* '''Policy:''' Access for any Nasqueron project and for infrastructure operations task.
* '''Started:''' 2019-11-21

== Ports ==

Ports for services managed automatically through Salt are available on {{Ops file|PORTS}}

{| class="wikitable"
|+ Reserved ports - IRC server range
|-
! Port !! User account !! Description
|-
| 6901 || dereckson || irssi proxy
|-
| 6902 || dereckson || irssi proxy
|}

== Troubleshoot ==

=== To check after reboot ===

* Network
** IPv4 - ICANN
** IPv6 - main + viperserv alias
** IPv6 - can we reach something with IPv6
** IPv4 - Drake: tunnel + route + ping any server
* Services
** Alkane HTTP server
** API exec HTTP server
** Bitlbee
** Eggdrops: Dæghrefn + Wearg
** Grafana
** MariaDB
** NetBox
** nginx
** Node exporter for Prometheus
** oidentd
** php-fpm
** PostgreSQL
** Prometheus
** Redis
** Salt minion
** SSH server
* Vault connectivity

How to communicate

2026-03-24T17:13:32Z

Dereckson:

This page shows tools and best practices to communicate efficiently about code changes or operations activities.

== Ways of communication ==

=== Discussion spaces ===
Our primary discussion spaces are IRC, DevCentral and here on Agora:

{| class="wikitable"
|+ Primary discussion spaces
|-
! Space !! How to join !! Scope
|-
| [[IRC]] || [https://libera.chat/ Libera.chat] #nasqueron-ops || Discussions about servers, infrastructure, operations, access.<br>Also, as it's currently our main discussion space, you're welcome to hangout there if you want to chat with fellow nasquenautes.
|-
| DevCentral || Browse https://devcentral.nasqueron.org || Tasks, project management, status update, sprints, ideas
|-
| Agora || You're here! [https://forms.nasqueron.org/nasqueron-requests/agora-account/new Request an account] || Documentation, projects, idea, personal notes
|}

We also use Jitsi as video-conference platform and some members currently use Discord to organize their contributions:

{| class="wikitable"
|+ Known discussion spaces
|-
! Space !! How to join !! Scope
|-
|-
| Discord || https://discord.gg/DZQK8Dd8Xd || ServPulse
|-
| Jitsi || https://meet.jit.si/nasqueron || Any topic.<br>Tip: If you're first on the meeting, you can login through GitHub to open it.
|}
=== By project ===
* Nasqueron Operations SIG uses IRC: Libera.chat #nasqueron-ops
* Eli and Amine work on Discord for [[ServPulse]]

=== Tips for audio and video meeting ===
A headset can help a lot to get clear communication, without echo or reverb. When you don't have it, try to mute yourself when you don't speak (Jitsi) or enable push-to-talk feature (Discord).

Dereckson has a spare USB headset from Sennheiser if you need one.

== Share logs, screenshots ==
;Core recommandations
* DO: use appropriate tools to share information through a short link
* DON'T: use screenshots to share text, text must be shared as text
* DON'T: copy/paste full logs in chat
* DON'T: share logs with privacy data / PII, in that case give a reference to go to that log

;Tools to use
* To share directly the ouput of a command
** [https://termbin.com/ Termbin]: <code>command | nc termbin.com 9999</code>
** Arcanist to publish to DevCentral: <code>command | arc paste --</code>
* To share clipboard content
** https://dpaste.com/
** DevCentral: [https://devcentral.nasqueron.org/paste/edit/form/default/ create paste], that gives a reference to put in other objects (tasks, differential), use <code>{P100}</code> for direct inclusion or <code>P100</code> for link
* To share source code
** Pastebin are totally appropriated too
** You can also use GitHub Gist: https://gist.github.com - they can be secret or publicly available
** You can send a pull request to the repository for proof of concept
** If you want to discuss a pull request against an upstream repository, DevCentral allows "free" diff not linked to any repo too: [https://devcentral.nasqueron.org/differential/diff/create/ diff/create]

;Too many tools! I'm lost
It can require some practice to be able to pick among the most appropriate tool, so you can start with:
* Command output -> <code>command | nc termbin.com 9999</code>
* Anything else
** Ephemeral -> https://dpaste.com/
** To save and discuss in tasks -> https://devcentral.nasqueron.org/paste/edit/form/default/

[[Category:Contributor guide]]
[[Category:Reference]]

Operations grimoire/Deploy with Terraform

2026-03-22T23:51:29Z

Dereckson: /* Propagate secrets (DRP) */

== Where to work? ==
We deploy from [[Complector]] using <code>/opt/salt/nasqueron-operations</code> as our local copy of rOPS, authoritative for both Salt and Terraform

You need to belong to the <code>ops</code> group to be able to have access and have write-rights on the repository

It's important to work from there to save a shared Terraform state.

== Specific deployment notes ==
=== Vault / OpenBao ===
==== General notes ====
;OpenTofu support
As of 2026-02-07, the Vault provider isn't compiled for FreeBSD. You need to use Terraform instead.

;Vault
You need a Vault token to allow the provider to connect.

You also need to set VAULT_ADDR to https://172.27.27.7:8200 as Vault doesn't listen on 127.0.0.1

<syntaxhighlight lang="shell">
$ export VAULT_ADDR=https://172.27.27.7:8200
$ sudo /opt/salt/nasqueron-operations/utils/vault/issue-admin-token.py > ~/.vault-token

$ cd /opt/salt/nasqueron-operations/terraform/openbao
$ terraform init # if you've a new entry requiring a module, it needs to be installed
$ terraform plan
$ terraform apply
</syntaxhighlight>

It could be interesting to maintain an alternative policy to admin for the Terraform provider, restricted to the current actions. Note benefits would be limited as those include policies management.

==== Propagate secrets (DRP) ====
;No automatic secret rotation
Secrets rotation is disabled with a lifecycle management <code>ignore_changes = [ secret_id, ]</code>.

To rotate a secret, it needs first to be destroyed from terraform state:
<code>terraform destroy -target=module.viperserv_approle.vault_approle_auth_backend_role_secret_id.this</code>

;Full procedure
Once the AppRole have been created in Vault, they need to be provisioned to the relevant configuration files.

<syntaxhighlight lang="shell">
$ cd /opt/salt/nasqueron-operations/terraform/openbao
$ terraform init # if you've a new entry requiring a module, it needs to be installed
$ terraform plan
$ terraform apply

$ cd /opt/salt/nasqueron-operations
$ salt windriver state.sls_id /usr/local/etc/secrets/rhyne-wyse.yaml roles/reports/rhyne-wyse/config
$ salt windriver state.sls_id /srv/viperserv/.credentials roles/viperserv/eggdrop/config
# Missing for router
</syntaxhighlight>

<div class="alert">Important. Each time you'll reprovision the secrets, they will change.

Don't forget to always apply this full procedure.
</div>

== Table of Terraform states ==

{| class="wikitable"
|+ Terraform and OpenBao states
|-
! Configuration !! State back-end !! Path !! Software to use
|-
| openbao || On disk || /opt/salt/nasqueron-operations/terraform/openbao/terraform.tfstate || Terraform
|}

On disk paths are stored in Complector.

== Troubleshoot ==
=== Error: Module not installed ===

You need to run <code>tofu init</code> to prepare for any new provider.

<syntaxhighlight lang="shell">
$ tofu plan

│ Error: Module not installed
│
│ on rhyne_wyse.tf line 23:
│ 23: module "rhyne_wyse_approle" {
│
│ This module is not yet installed. Run "tofu init" to install all modules required by this configuration.
</syntaxhighlight>

=== Error: Incompatible provider version ===

<syntaxhighlight lang="shell">
$ tofu init

Initializing the backend...
Initializing modules...
- rhyne_wyse_approle in modules/app_credentials

Initializing provider plugins...
- Finding hashicorp/vault versions matching "5.3.0"...
╷
│ Error: Incompatible provider version
│
│ Provider registry.opentofu.org/hashicorp/vault v5.3.0 does not have a package available for your current platform, freebsd_amd64.
│
│ Provider releases are separate from OpenTofu CLI releases, so not all providers are available for all platforms. Other versions of this provider may have different platforms supported.
</syntaxhighlight>

On OpenTofu, some modules are only compiled for Linux, not for FreeBSD.
Switch to Terraform pending a solution to help the OpenTofu builds.

[[Category:Operations grimoire]]
[[Category:Terraform]]

MediaWiki:Common.css

2026-03-22T23:50:38Z

Dereckson:

/* Source code */

code, tt, kbd, pre, samp {
font-size: 0.9em !important;
}

/* Call for actions button */

.btn {
-webkit-border-radius: 6;
-moz-border-radius: 6;
border-radius: 6px;
color: #ffffff;
font-size: 1.4em;
background: #4d7b94;
padding: 10px 20px 10px 20px;
text-decoration: none;
}

.btn a, .btn a:hover, .btn a:visited {
color: white !important;
}

.btn:hover {
background: #6caacc;
text-decoration: none;
}

/* Inline code */

.inline-code, .inline-code div, .inline-code pre {
display: inline-table;
}

/*
Banners
*/

.alert {
background: #d32f2f;
color: #fff;
padding: 0.75rem 1rem;
border-radius: 4px;
font-weight: 600;
}

/*
Colors from 2017 palette

See https://devcentral.nasqueron.org/M11 or [[Design/2017 colors]]
*/

.color-magnetic-one {
/* Cyberspace gray */
color: #44484D;
}
.color-magnetic-two {
/* Anchors Aweigh blue */
color: #2B3441;
}
.color-magnetic-three {
/* Niagara blue — Pantone 17-4123 */
color: #5587A2;
}
.color-magnetic-four {
/* Primrose yellow — Pantone 13-0755 */
color: #F6D258;
}
.color-magnetic-five {
/* Green from http://www.elledecor.com/design-decorate/color/g3175/color-trends/ */
color: #67947D;
}

/*
Responsive blocks.
*/

.block {
margin: 0 0;
padding: 5vh 5vw;

border: #808080 solid 5px;
}

.block-col {
position: relative;
display:inline;
float: left;
margin-right: 1em;
padding: 1vw;
}

.block-col-quarter {
width: 20%;
}

.block-col-half {
width: 40%;
}

.user-block {
min-height: 50vh;
background-color: #44484D;
color: white;
}

.user-block dt {
color: #67947D;
font-family: 'Segoe UI', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Lato', 'Liberation Sans', 'Noto Sans', 'Helvetica Neue', 'Helvetica', sans-serif;
font-size: 1.375em;
margin-bottom: 1em;
}

.user-block a {
color: #F6D258 !important;
}

/*
Variable Grid System.
Learn more ~ http://www.spry-soft.com/grids/
Based on 960 Grid System - http://960.gs/

Licensed under GPL and MIT.
*/

/* Containers
----------------------------------------------------------------------------------------------------*/
.container_12 {
margin-left: auto;
margin-right: auto;
width: 960px;
}

/* Grid >> Global
----------------------------------------------------------------------------------------------------*/

.grid_1,
.grid_2,
.grid_3,
.grid_4,
.grid_5,
.grid_6,
.grid_7,
.grid_8,
.grid_9,
.grid_10,
.grid_11,
.grid_12 {
display:inline;
float: left;
position: relative;
margin-left: 10px;
margin-right: 10px;
}

/* Grid >> Children (Alpha ~ First, Omega ~ Last)
----------------------------------------------------------------------------------------------------*/

.alpha {
margin-left: 0;
}

.omega {
margin-right: 0;
}

/* Grid >> 12 Columns
----------------------------------------------------------------------------------------------------*/

.container_12 .grid_1 {
width:60px;
}

.container_12 .grid_2 {
width:140px;
}

.container_12 .grid_3 {
width:220px;
}

.container_12 .grid_4 {
width:300px;
}

.container_12 .grid_5 {
width:380px;
}

.container_12 .grid_6 {
width:460px;
}

.container_12 .grid_7 {
width:540px;
}

.container_12 .grid_8 {
width:620px;
}

.container_12 .grid_9 {
width:700px;
}

.container_12 .grid_10 {
width:780px;
}

.container_12 .grid_11 {
width:860px;
}

.container_12 .grid_12 {
width:940px;
}

/* Prefix Extra Space >> 12 Columns
----------------------------------------------------------------------------------------------------*/

.container_12 .prefix_1 {
padding-left:80px;
}

.container_12 .prefix_2 {
padding-left:160px;
}

.container_12 .prefix_3 {
padding-left:240px;
}

.container_12 .prefix_4 {
padding-left:320px;
}

.container_12 .prefix_5 {
padding-left:400px;
}

.container_12 .prefix_6 {
padding-left:480px;
}

.container_12 .prefix_7 {
padding-left:560px;
}

.container_12 .prefix_8 {
padding-left:640px;
}

.container_12 .prefix_9 {
padding-left:720px;
}

.container_12 .prefix_10 {
padding-left:800px;
}

.container_12 .prefix_11 {
padding-left:880px;
}

/* Suffix Extra Space >> 12 Columns
----------------------------------------------------------------------------------------------------*/

.container_12 .suffix_1 {
padding-right:80px;
}

.container_12 .suffix_2 {
padding-right:160px;
}

.container_12 .suffix_3 {
padding-right:240px;
}

.container_12 .suffix_4 {
padding-right:320px;
}

.container_12 .suffix_5 {
padding-right:400px;
}

.container_12 .suffix_6 {
padding-right:480px;
}

.container_12 .suffix_7 {
padding-right:560px;
}

.container_12 .suffix_8 {
padding-right:640px;
}

.container_12 .suffix_9 {
padding-right:720px;
}

.container_12 .suffix_10 {
padding-right:800px;
}

.container_12 .suffix_11 {
padding-right:880px;
}

/* Push Space >> 12 Columns
----------------------------------------------------------------------------------------------------*/

.container_12 .push_1 {
left:80px;
}

.container_12 .push_2 {
left:160px;
}

.container_12 .push_3 {
left:240px;
}

.container_12 .push_4 {
left:320px;
}

.container_12 .push_5 {
left:400px;
}

.container_12 .push_6 {
left:480px;
}

.container_12 .push_7 {
left:560px;
}

.container_12 .push_8 {
left:640px;
}

.container_12 .push_9 {
left:720px;
}

.container_12 .push_10 {
left:800px;
}

.container_12 .push_11 {
left:880px;
}

/* Pull Space >> 12 Columns
----------------------------------------------------------------------------------------------------*/

.container_12 .pull_1 {
left:-80px;
}

.container_12 .pull_2 {
left:-160px;
}

.container_12 .pull_3 {
left:-240px;
}

.container_12 .pull_4 {
left:-320px;
}

.container_12 .pull_5 {
left:-400px;
}

.container_12 .pull_6 {
left:-480px;
}

.container_12 .pull_7 {
left:-560px;
}

.container_12 .pull_8 {
left:-640px;
}

.container_12 .pull_9 {
left:-720px;
}

.container_12 .pull_10 {
left:-800px;
}

.container_12 .pull_11 {
left:-880px;
}

/* Clear Floated Elements
----------------------------------------------------------------------------------------------------*/

/* http://sonspring.com/journal/clearing-floats */

.clear {
clear: both;
display: block;
overflow: hidden;
visibility: hidden;
width: 0;
height: 0;
}

/* http://perishablepress.com/press/2008/02/05/lessons-learned-concerning-the-clearfix-css-hack */

.clearfix:after {
clear: both;
content: ' ';
display: block;
font-size: 0;
line-height: 0;
visibility: hidden;
width: 0;
height: 0;
}

.clearfix {
display: inline-block;
}

* html .clearfix {
height: 1%;
}

.clearfix {
display: block;
}

Operations grimoire/Deploy with Terraform

2026-03-22T23:18:13Z

Dereckson: /* Propagate secrets (DRP) */ # Missing for router

== Where to work? ==
We deploy from [[Complector]] using <code>/opt/salt/nasqueron-operations</code> as our local copy of rOPS, authoritative for both Salt and Terraform

You need to belong to the <code>ops</code> group to be able to have access and have write-rights on the repository

It's important to work from there to save a shared Terraform state.

== Specific deployment notes ==
=== Vault / OpenBao ===
==== General notes ====
;OpenTofu support
As of 2026-02-07, the Vault provider isn't compiled for FreeBSD. You need to use Terraform instead.

;Vault
You need a Vault token to allow the provider to connect.

You also need to set VAULT_ADDR to https://172.27.27.7:8200 as Vault doesn't listen on 127.0.0.1

<syntaxhighlight lang="shell">
$ export VAULT_ADDR=https://172.27.27.7:8200
$ sudo /opt/salt/nasqueron-operations/utils/vault/issue-admin-token.py > ~/.vault-token

$ cd /opt/salt/nasqueron-operations/terraform/openbao
$ terraform init # if you've a new entry requiring a module, it needs to be installed
$ terraform plan
$ terraform apply
</syntaxhighlight>

It could be interesting to maintain an alternative policy to admin for the Terraform provider, restricted to the current actions. Note benefits would be limited as those include policies management.

==== Propagate secrets (DRP) ====
;No automatic secret rotation
Secrets rotation is disabled with a lifecycle management <code>ignore_changes = [ secret_id, ]</code>.

To rotate a secret, it needs first to be destroyed from terraform state:
<code>terraform destroy -target=module.viperserv_approle.vault_approle_auth_backend_role_secret_id.this</code>

;Full procedure
Once the AppRole have been created in Vault, they need to be provisioned to the relevant configuration files.

<syntaxhighlight lang="shell">
$ cd /opt/salt/nasqueron-operations/terraform/openbao
$ terraform init # if you've a new entry requiring a module, it needs to be installed
$ terraform plan
$ terraform apply

$ cd /opt/salt/nasqueron-operations
$ salt windriver state.sls_id /usr/local/etc/secrets/rhyne-wyse.yaml roles/reports/rhyne-wyse/config
$ salt windriver state.sls_id /srv/viperserv/.credentials roles/viperserv/eggdrop/config
# Missing for router
</syntaxhighlight>

== Table of Terraform states ==

{| class="wikitable"
|+ Terraform and OpenBao states
|-
! Configuration !! State back-end !! Path !! Software to use
|-
| openbao || On disk || /opt/salt/nasqueron-operations/terraform/openbao/terraform.tfstate || Terraform
|}

On disk paths are stored in Complector.

== Troubleshoot ==
=== Error: Module not installed ===

You need to run <code>tofu init</code> to prepare for any new provider.

<syntaxhighlight lang="shell">
$ tofu plan

│ Error: Module not installed
│
│ on rhyne_wyse.tf line 23:
│ 23: module "rhyne_wyse_approle" {
│
│ This module is not yet installed. Run "tofu init" to install all modules required by this configuration.
</syntaxhighlight>

=== Error: Incompatible provider version ===

<syntaxhighlight lang="shell">
$ tofu init

Initializing the backend...
Initializing modules...
- rhyne_wyse_approle in modules/app_credentials

Initializing provider plugins...
- Finding hashicorp/vault versions matching "5.3.0"...
╷
│ Error: Incompatible provider version
│
│ Provider registry.opentofu.org/hashicorp/vault v5.3.0 does not have a package available for your current platform, freebsd_amd64.
│
│ Provider releases are separate from OpenTofu CLI releases, so not all providers are available for all platforms. Other versions of this provider may have different platforms supported.
</syntaxhighlight>

On OpenTofu, some modules are only compiled for Linux, not for FreeBSD.
Switch to Terraform pending a solution to help the OpenTofu builds.

[[Category:Operations grimoire]]
[[Category:Terraform]]

Operations grimoire/Vault

2026-03-22T18:59:45Z

Dereckson: /* Get an admin-level token */

''This page currently documents Vault installed on complector as part of {{Ops file|roles/vault/}}. It doesn't document Docker or shellserver installation. See [[Operations grimoire/Eglide/Vault]] and [[Dev zone/Vault]].''

Hashicorp Vault allows to manage credentials and is currently used:

* to provision credentials through Salt
* to allow applications to fetch credentials
* to emit certificates for the private network applications
* to store credentials used by the Nasqueron Operations SIG beings

Vault policies are fully managed through Salt in the operations repository.

Vault has been selected in 2016 for secrets management.

== Vault reference ==
=== kv engine ===
The kv engine contains the following paths:

* ops/secrets: credentials like passwords, API tokens, private keys deployed to servers - a reference for machines
* ops/internal: credentials to third-party services internally shared amongst ops - a reference for humans
* ops/privacy: privacy information

==== Secrets ====
Secrets are directly and manually managed in Vault. If we need to run a disaster recovery procedure, we'll roll any secret by defining them again and deploy from rOPS those new secrets.

==== Privacy data ====
Personal identity information (PII) shared inside the Nasqueron Operations squad are more convenient to manage as a repository.

Such access to the repository is restricted to commit data, and ensure this data is deployed to the servers needing it. Any other use isn't allowed.

Information to the repository is then published in Vault, and referred in rOPS as Vault credentials.

'''Note:''' The ops/privacy path is only intended for PII of current or previous members of the Ops SIG, like IP addresses allowed to connect to restricted resources like the ops VPN. This is not acceptable to put 3rd party information in this repository.

=== pki engine ===
Services listening to private IPs use the Vault PKI to generate certificates:

* pki_root: root CA, certificate available at https://api.nasqueron.org/infra/security/pki/root/ca
* pki_vault: intermediate CA used for Vault itself

Certificates should be issued short-term and frequently renewed by automated services.

=== transit engine ===
Encryption as a service is available for applications under /transit path.

See https://learn.hashicorp.com/tutorials/vault/eaas-transit.

Applications should use a policy restricting to a subpath for that app, not to the whole engine.

=== Users accounts ===

Members of the Operations SIG need an access to Vault to create and maintain credentials.

Currently, we use tokens. To generate a token:

vault token create -policy=admin

To connect to Vault with a token from a devserver (e.g. WindRiver), you need:

# Store the token in <code>$HOME/.vault-token</code>
# Define environment variable VAULT_ADDR: <code>export VAULT_ADDR=https://172.27.27.7:8200</code>

Tokens need to be frequently renew (before expiration) with <code>vault renew</code>

== Salt configuration ==
=== Get a secret through Salt ===
The information in the ops/secrets and ops/privacy kv engines are integrated in the Salt pillar:

<syntaxhighlight lang="yaml">
ext_pillar:
# Credentials to deploy to servers
- vault:
conf: path=ops/secrets
nesting_key: credentials

# Personal identity information from Nasqueron Operations SIG members
- vault:
conf: path=ops/privacy
nesting_key: privacy
</syntaxhighlight>

You can then access to this information in Salt states using the following references:

{| class="wikitable"
|+ Access to Salt data
|-
! Category !! Example of path in Vault !! Example of pillar key in Salt
|-
| Secrets || ops/secrets/foo || pillar['credentials']['foo']
|-
| Privacy data || ops/privacy/ops-cidr || pillar['privacy']['ops-cidr']
|}

The ops/internal paths aren't accessible through Vault.

=== Policies ===

Policies are managed in {{Ops file|pillar/credentials/vault.sls}}.

For Salt, we deploy secrets to servers, policy management for a node consist to provide the list of secrets a role should have access to, generally in '''vault_secrets_by_role''' dictionary.

For other applications:
* create a policy .hcl in <code>roles/vault/policies/files/</code>
* declare the policy in the pillar under <code>vault_policies</code> list, it should match the .hcl file (without the extension or the path)
* run the repository tests to check if both information matches ; to only run that part, use <code>cd _tests && python3 -m unittest discover pillar/credentials/</code>

To add only an application policy, Salt can be deployed like this:

salt complector state.sls_id vault_policy_airflow roles/vault/policies

Salt policies can be tested by specifying the node name:

salt complector state.sls_id salt-node-windriver roles/vault/policies test=True

=== DRP ===
Any step we need to do to configure the engines should be added to the {{ops file|roles/vault/bootstrap}} unit.

If we need to recover Vault, two solutions are available:
* restore the storage, to keep data (credentials, certificates including the root CA one)
* recreate it from scratch through the roles/vault/bootstrap unit

== Howto ==
=== Allow a new application to authenticate to Vault ===
Applications need a policy and an authentication method, for example here for an application called yourservice with AppRole with secret_id and role_id:
# Create a new policy in operations repository: {{D|3270}}
# Deploy it from Complector with <code>salt complector state.sls_id vault_policy_yourservice roles/vault/policies</code>
# Create an approle matching that policy: <code>vault write auth/approle/role/yourservice token_policies="yourservice" token_ttl=1h token_max_ttl=4h</code>
# Get role_id with <code>vault read auth/approle/role/yourservice/role-id</code>
# Get secret_id with <code>vault write -force auth/approle/role/yourservice/secret-id</code>
# If you wish Salt to provision those credentials during your service deployment, probably a good idea to write them too: <code>vault kv put secrets/nasqueron/yourservice/vault username=role-id password=secret-id</code> [to skip if you don't use Salt to provision role-id and secret-id]

=== Get an admin-level token ===
Ops can use the self-service hvac script to get a token valid for 30 days:

ssh complector
cd /opt/salt/nasqueron-operations
sudo ./utils/vault/issue-admin-token.py

If Vault certificate has expired, add the `--insecure` argument.

You can also create a $HOME/bin/vault-login helper script:

<syntaxhighlight language="sh">
#!/bin/sh

touch $HOME/.vault-token
chmod 600 $HOME/.vault-token
ssh complector sudo /opt/salt/nasqueron-operations/utils/vault/issue-admin-token.py | tr -d '\n' > $HOME/.vault-token
</syntaxhighlight>

== Troubleshoot ==
=== Connecting to Vault ===
==== Access to web UI ====
Vault isn't listening any public IP, but accept connections from internal network, so you can open a SSH tunnel against <code>complector:8200</code> and then browse https://localhost:8200:

<code>ssh -L 8200:complector:8200 router-001.nasqueron.org</code>

==== curl: (60) SSL certificate problem ====
Curl is compiled against a certificate bundle (<code>curl-config --ca</code> for the path). That bundle doesn't contain the pki_root certificate. We deploy this certificate in /etc/ssl/certs, but curl won't check there if not instructed to.

If you build an immutable environment like a container, add the certificate to the bundle.

On other machines, create a curl configuration file in ~/.curlrc (it doesn't seem currently possible to create a system one) with <code>capath=/etc/ssl/certs</code>.

If you've still the issue after that, check two things:
* with <code>curl -v</code>, the path should correctly there: <code>* CApath: /etc/ssl/certs</code> in addition to a CAfile.
* with <code>file /etc/ssl/certs/* | grep -i nasqueron</code> you should have a result ; if not, put the certificate in /usr/local/share/certs and relaunch the tool to link it in /etc/ssl/certs, for example <code>certctl rehash</code> on FreeBSD (needs root access).

=== Certificates ===
==== How to unseal when certificate have expired? ====
Use the web UI through SSH tunnel.

==== Renew Vault HTTP certificates ====

Vault uses TLS certificates managed by its own CA. That can create a chicken/egg issue if certificates have expired to connect to it, as the Vault client strictly requires valid TLS certificated to issue commands to renew certificates.

Connect to the web UI works as your browser is able to bypass certificate requirement. Opening a SSH tunnel with <code>-L 8200:complector:8200</code> should work for that.

Certificates configuration is available at [https://devcentral.nasqueron.org/D2639 D2639].

The web UI doesn't offer a comprehensive sets of widgets to generate certificates. You can instead use the ''Vault Browser CLI'' to run Vault CLI commands from the web UI. The signing operation can be done through endpoint configuration UI.

<div style="background-color: indianred; border: solid 3px black; color:white; font-size: large; padding: 2em;">Automation for this part is being tested.

You can preview automation proposal in /home/dereckson/sandbox/vault/renew-certificates on Complector.
</div>

Based on current D2639 state (2023-01), you can do the following:
* Has intermediate authority certificate expired? [old instructions, currently not valid anymore]
** Web console: <code>write -format=json pki_vault/intermediate/generate/internal common_name="nasqueron.drake Intermediate Authority"</code>
** At https://localhost:8200/ui/vault/secrets/pki_vault/pki/roles/nasqueron-drake you can use the sign intermediate button to sign it, don't forget to fill the following information:
*** CSR, pick from console the .data.csr output from JSON response
*** Format: pem_bundle
*** TTL: 100 days
*** Common name: "nasqueron.drake Intermediate Authority"
*** Organization: Nasqueron
*** Organization unit: Nasqueron Operations SIG
*** Country: BE
** Follow the warning instruction: copy the certificate bundle, and in pki_vault, use Set signed intermediate to set the certificate as intermediate one. That will create a new issuer, fetch the name in "issuers".
** Save also the certificate bundle to /usr/local/share/certs/nasqueron-vault-intermediate.crt
** Edit the nasqueron-drake role to use your new issuer name
* Has complector.nasqueron.drake certificate has expired?
** Web console: <code>write -format=json pki_vault/issue/nasqueron-drake common_name=complector.nasqueron.drake ttl=2160h ip_sans=127.0.0.1,172.27.27.7</code>, save the output in /usr/local/etc/certificates/vault files:
*** .data.certificate to certificate.pem
*** .data.issuing_ca to ca.pem
*** .data.private_key to private.key (careful how you replace the \n, if you use Python REPL, do it on Complector itself and get rid of the history with <code>import readline ; readline.clear_history()</code>)
** Prepare the fullchain bundle with <code>cat certificate.pem ca.pem > fullchain.pem</code>
** Send a SIGHUP signal to Vault to reload configuration with <code>kill -1 <Vault PID></code>, HTTP server should pick new certificate and you can know directly use the vault command. Vault configuration currently uses fullchain.pem and private.key.

CSR uses <code>line1\nline2\nline3</code> format in JSON. You can use a Python REPL with print("...") to print the CSR in several lines. CSR isn't confidential information, key is protected in Vault and never exposed.

'''jq.''' Another tool that can help is <code>jq</code>. For example, <code>cat certificate.json | jq -r .data.certificate > /usr/local/etc/certificates/vault/certificate.pem</code> will save it in multiline format.

If you get an issue about private key missing at Set signed intermediate step, don't forget you're setting an intermediate certificate for pki_vault, and not for pki_root, set that here: https://localhost:8200/ui/vault/settings/secrets/configure/pki_vault/cert

Paths where to store certificates matter:
* pki_root certificates are stored in /usr/local/share/certs
* pki_vault certificates are stored in /usr/local/etc/certificates/vault

Ensure `private.key` belongs to user `vault` and receives a correct chmod like 400.

==== Services known to break when a certificate is expired ====

* Salt, but that's ad-hoc and explicit
* Sentry containers: <code>sudo docker ps -a | grep sentry | grep -v "Up "</code>

=== Salt ===
==== Policy for a node doesn't contain new secret entry ====
If the policies are attached to a new role:

# Ensure new secret have been added for the right role in {{Ops file|pillar/credentials/vault.sls}}
#* If missing, validate afterwards with <code>salt complector pillar.get vault_secrets_by_role:yourrole</code>
#* You need to refresh the pillar if still missing: <code>salt complector saltutil.refresh_pillar</code>
# Ensure role has been added to {{Ops file|pillar/nodes/nodes.sls}} and NetBox
#* If missing, refresh pillar afterwards
#* Validate with <code>salt complector node.get roles <server name></code>
# Final check: <code>salt complector state.sls_id salt-node-<server name> roles/vault/policies test=True</code>
# If diff is complicated to read, check the full policies document by role: <code>salt complector credentials.build_policies_by_node</code>
#* Secret path present? Check the policy isn't already up-to-date: <code>vault policy read salt-node-<server name></code>

==== credentials.vault_policy_present returns Bad Request ====

Vault returns a 400 error if the policy format is incorrect.

'''Case 1.''' The state ID starts by <code>vault_policy_</code>. You manually added a file to roles/vault/policies/file: this error means Vault API founds a syntax error in it. You can use https://github.com/mschuchard/linter-vault-policy if you use Pulsar (ex Atom) to lint those files.

'''Case 2.''' The state ID starts by anything else. The policy has been generated through _modules/credentials.py.

Check if the pillar values added are correct:
* if not, add a test in <code>_tests/pillar/credentials/test_vault.py</code> to detect the case
* if yes, there is an issue with the Python module code to fix

'''Example of Salt output.'''

<syntaxhighlight>
----------
ID: vault_policy_admin
Function: credentials.vault_policy_present
Name: admin
Result: False
Comment: Failed to change policy: Bad Request
Started: 13:45:14.162421
Duration: 76.168 ms
Changes:
</syntaxhighlight>

[[Category:Operations grimoire]]
[[Category:Vault]]

Operations grimoire/Vault

2026-03-22T18:57:55Z

Dereckson: /* Get an admin-level token */

''This page currently documents Vault installed on complector as part of {{Ops file|roles/vault/}}. It doesn't document Docker or shellserver installation. See [[Operations grimoire/Eglide/Vault]] and [[Dev zone/Vault]].''

Hashicorp Vault allows to manage credentials and is currently used:

* to provision credentials through Salt
* to allow applications to fetch credentials
* to emit certificates for the private network applications
* to store credentials used by the Nasqueron Operations SIG beings

Vault policies are fully managed through Salt in the operations repository.

Vault has been selected in 2016 for secrets management.

== Vault reference ==
=== kv engine ===
The kv engine contains the following paths:

* ops/secrets: credentials like passwords, API tokens, private keys deployed to servers - a reference for machines
* ops/internal: credentials to third-party services internally shared amongst ops - a reference for humans
* ops/privacy: privacy information

==== Secrets ====
Secrets are directly and manually managed in Vault. If we need to run a disaster recovery procedure, we'll roll any secret by defining them again and deploy from rOPS those new secrets.

==== Privacy data ====
Personal identity information (PII) shared inside the Nasqueron Operations squad are more convenient to manage as a repository.

Such access to the repository is restricted to commit data, and ensure this data is deployed to the servers needing it. Any other use isn't allowed.

Information to the repository is then published in Vault, and referred in rOPS as Vault credentials.

'''Note:''' The ops/privacy path is only intended for PII of current or previous members of the Ops SIG, like IP addresses allowed to connect to restricted resources like the ops VPN. This is not acceptable to put 3rd party information in this repository.

=== pki engine ===
Services listening to private IPs use the Vault PKI to generate certificates:

* pki_root: root CA, certificate available at https://api.nasqueron.org/infra/security/pki/root/ca
* pki_vault: intermediate CA used for Vault itself

Certificates should be issued short-term and frequently renewed by automated services.

=== transit engine ===
Encryption as a service is available for applications under /transit path.

See https://learn.hashicorp.com/tutorials/vault/eaas-transit.

Applications should use a policy restricting to a subpath for that app, not to the whole engine.

=== Users accounts ===

Members of the Operations SIG need an access to Vault to create and maintain credentials.

Currently, we use tokens. To generate a token:

vault token create -policy=admin

To connect to Vault with a token from a devserver (e.g. WindRiver), you need:

# Store the token in <code>$HOME/.vault-token</code>
# Define environment variable VAULT_ADDR: <code>export VAULT_ADDR=https://172.27.27.7:8200</code>

Tokens need to be frequently renew (before expiration) with <code>vault renew</code>

== Salt configuration ==
=== Get a secret through Salt ===
The information in the ops/secrets and ops/privacy kv engines are integrated in the Salt pillar:

<syntaxhighlight lang="yaml">
ext_pillar:
# Credentials to deploy to servers
- vault:
conf: path=ops/secrets
nesting_key: credentials

# Personal identity information from Nasqueron Operations SIG members
- vault:
conf: path=ops/privacy
nesting_key: privacy
</syntaxhighlight>

You can then access to this information in Salt states using the following references:

{| class="wikitable"
|+ Access to Salt data
|-
! Category !! Example of path in Vault !! Example of pillar key in Salt
|-
| Secrets || ops/secrets/foo || pillar['credentials']['foo']
|-
| Privacy data || ops/privacy/ops-cidr || pillar['privacy']['ops-cidr']
|}

The ops/internal paths aren't accessible through Vault.

=== Policies ===

Policies are managed in {{Ops file|pillar/credentials/vault.sls}}.

For Salt, we deploy secrets to servers, policy management for a node consist to provide the list of secrets a role should have access to, generally in '''vault_secrets_by_role''' dictionary.

For other applications:
* create a policy .hcl in <code>roles/vault/policies/files/</code>
* declare the policy in the pillar under <code>vault_policies</code> list, it should match the .hcl file (without the extension or the path)
* run the repository tests to check if both information matches ; to only run that part, use <code>cd _tests && python3 -m unittest discover pillar/credentials/</code>

To add only an application policy, Salt can be deployed like this:

salt complector state.sls_id vault_policy_airflow roles/vault/policies

Salt policies can be tested by specifying the node name:

salt complector state.sls_id salt-node-windriver roles/vault/policies test=True

=== DRP ===
Any step we need to do to configure the engines should be added to the {{ops file|roles/vault/bootstrap}} unit.

If we need to recover Vault, two solutions are available:
* restore the storage, to keep data (credentials, certificates including the root CA one)
* recreate it from scratch through the roles/vault/bootstrap unit

== Howto ==
=== Allow a new application to authenticate to Vault ===
Applications need a policy and an authentication method, for example here for an application called yourservice with AppRole with secret_id and role_id:
# Create a new policy in operations repository: {{D|3270}}
# Deploy it from Complector with <code>salt complector state.sls_id vault_policy_yourservice roles/vault/policies</code>
# Create an approle matching that policy: <code>vault write auth/approle/role/yourservice token_policies="yourservice" token_ttl=1h token_max_ttl=4h</code>
# Get role_id with <code>vault read auth/approle/role/yourservice/role-id</code>
# Get secret_id with <code>vault write -force auth/approle/role/yourservice/secret-id</code>
# If you wish Salt to provision those credentials during your service deployment, probably a good idea to write them too: <code>vault kv put secrets/nasqueron/yourservice/vault username=role-id password=secret-id</code> [to skip if you don't use Salt to provision role-id and secret-id]

=== Get an admin-level token ===
Ops can use the self-service hvac script to get a token valid for 30 days:

ssh complector
cd /opt/salt/nasqueron-operations
sudo ./utils/vault/issue-admin-token.py

If Vault certificate has expired, add the `--insecure` argument.

You can also automate this as a oneliner to store the token in the default token file:

ssh complector sudo /opt/salt/nasqueron-operations/utils/vault/issue-admin-token.py > ~/.vault-token ; chmod 600 ~/.vault-token

== Troubleshoot ==
=== Connecting to Vault ===
==== Access to web UI ====
Vault isn't listening any public IP, but accept connections from internal network, so you can open a SSH tunnel against <code>complector:8200</code> and then browse https://localhost:8200:

<code>ssh -L 8200:complector:8200 router-001.nasqueron.org</code>

==== curl: (60) SSL certificate problem ====
Curl is compiled against a certificate bundle (<code>curl-config --ca</code> for the path). That bundle doesn't contain the pki_root certificate. We deploy this certificate in /etc/ssl/certs, but curl won't check there if not instructed to.

If you build an immutable environment like a container, add the certificate to the bundle.

On other machines, create a curl configuration file in ~/.curlrc (it doesn't seem currently possible to create a system one) with <code>capath=/etc/ssl/certs</code>.

If you've still the issue after that, check two things:
* with <code>curl -v</code>, the path should correctly there: <code>* CApath: /etc/ssl/certs</code> in addition to a CAfile.
* with <code>file /etc/ssl/certs/* | grep -i nasqueron</code> you should have a result ; if not, put the certificate in /usr/local/share/certs and relaunch the tool to link it in /etc/ssl/certs, for example <code>certctl rehash</code> on FreeBSD (needs root access).

=== Certificates ===
==== How to unseal when certificate have expired? ====
Use the web UI through SSH tunnel.

==== Renew Vault HTTP certificates ====

Vault uses TLS certificates managed by its own CA. That can create a chicken/egg issue if certificates have expired to connect to it, as the Vault client strictly requires valid TLS certificated to issue commands to renew certificates.

Connect to the web UI works as your browser is able to bypass certificate requirement. Opening a SSH tunnel with <code>-L 8200:complector:8200</code> should work for that.

Certificates configuration is available at [https://devcentral.nasqueron.org/D2639 D2639].

The web UI doesn't offer a comprehensive sets of widgets to generate certificates. You can instead use the ''Vault Browser CLI'' to run Vault CLI commands from the web UI. The signing operation can be done through endpoint configuration UI.

<div style="background-color: indianred; border: solid 3px black; color:white; font-size: large; padding: 2em;">Automation for this part is being tested.

You can preview automation proposal in /home/dereckson/sandbox/vault/renew-certificates on Complector.
</div>

Based on current D2639 state (2023-01), you can do the following:
* Has intermediate authority certificate expired? [old instructions, currently not valid anymore]
** Web console: <code>write -format=json pki_vault/intermediate/generate/internal common_name="nasqueron.drake Intermediate Authority"</code>
** At https://localhost:8200/ui/vault/secrets/pki_vault/pki/roles/nasqueron-drake you can use the sign intermediate button to sign it, don't forget to fill the following information:
*** CSR, pick from console the .data.csr output from JSON response
*** Format: pem_bundle
*** TTL: 100 days
*** Common name: "nasqueron.drake Intermediate Authority"
*** Organization: Nasqueron
*** Organization unit: Nasqueron Operations SIG
*** Country: BE
** Follow the warning instruction: copy the certificate bundle, and in pki_vault, use Set signed intermediate to set the certificate as intermediate one. That will create a new issuer, fetch the name in "issuers".
** Save also the certificate bundle to /usr/local/share/certs/nasqueron-vault-intermediate.crt
** Edit the nasqueron-drake role to use your new issuer name
* Has complector.nasqueron.drake certificate has expired?
** Web console: <code>write -format=json pki_vault/issue/nasqueron-drake common_name=complector.nasqueron.drake ttl=2160h ip_sans=127.0.0.1,172.27.27.7</code>, save the output in /usr/local/etc/certificates/vault files:
*** .data.certificate to certificate.pem
*** .data.issuing_ca to ca.pem
*** .data.private_key to private.key (careful how you replace the \n, if you use Python REPL, do it on Complector itself and get rid of the history with <code>import readline ; readline.clear_history()</code>)
** Prepare the fullchain bundle with <code>cat certificate.pem ca.pem > fullchain.pem</code>
** Send a SIGHUP signal to Vault to reload configuration with <code>kill -1 <Vault PID></code>, HTTP server should pick new certificate and you can know directly use the vault command. Vault configuration currently uses fullchain.pem and private.key.

CSR uses <code>line1\nline2\nline3</code> format in JSON. You can use a Python REPL with print("...") to print the CSR in several lines. CSR isn't confidential information, key is protected in Vault and never exposed.

'''jq.''' Another tool that can help is <code>jq</code>. For example, <code>cat certificate.json | jq -r .data.certificate > /usr/local/etc/certificates/vault/certificate.pem</code> will save it in multiline format.

If you get an issue about private key missing at Set signed intermediate step, don't forget you're setting an intermediate certificate for pki_vault, and not for pki_root, set that here: https://localhost:8200/ui/vault/settings/secrets/configure/pki_vault/cert

Paths where to store certificates matter:
* pki_root certificates are stored in /usr/local/share/certs
* pki_vault certificates are stored in /usr/local/etc/certificates/vault

Ensure `private.key` belongs to user `vault` and receives a correct chmod like 400.

==== Services known to break when a certificate is expired ====

* Salt, but that's ad-hoc and explicit
* Sentry containers: <code>sudo docker ps -a | grep sentry | grep -v "Up "</code>

=== Salt ===
==== Policy for a node doesn't contain new secret entry ====
If the policies are attached to a new role:

# Ensure new secret have been added for the right role in {{Ops file|pillar/credentials/vault.sls}}
#* If missing, validate afterwards with <code>salt complector pillar.get vault_secrets_by_role:yourrole</code>
#* You need to refresh the pillar if still missing: <code>salt complector saltutil.refresh_pillar</code>
# Ensure role has been added to {{Ops file|pillar/nodes/nodes.sls}} and NetBox
#* If missing, refresh pillar afterwards
#* Validate with <code>salt complector node.get roles <server name></code>
# Final check: <code>salt complector state.sls_id salt-node-<server name> roles/vault/policies test=True</code>
# If diff is complicated to read, check the full policies document by role: <code>salt complector credentials.build_policies_by_node</code>
#* Secret path present? Check the policy isn't already up-to-date: <code>vault policy read salt-node-<server name></code>

==== credentials.vault_policy_present returns Bad Request ====

Vault returns a 400 error if the policy format is incorrect.

'''Case 1.''' The state ID starts by <code>vault_policy_</code>. You manually added a file to roles/vault/policies/file: this error means Vault API founds a syntax error in it. You can use https://github.com/mschuchard/linter-vault-policy if you use Pulsar (ex Atom) to lint those files.

'''Case 2.''' The state ID starts by anything else. The policy has been generated through _modules/credentials.py.

Check if the pillar values added are correct:
* if not, add a test in <code>_tests/pillar/credentials/test_vault.py</code> to detect the case
* if yes, there is an issue with the Python module code to fix

'''Example of Salt output.'''

<syntaxhighlight>
----------
ID: vault_policy_admin
Function: credentials.vault_policy_present
Name: admin
Result: False
Comment: Failed to change policy: Bad Request
Started: 13:45:14.162421
Duration: 76.168 ms
Changes:
</syntaxhighlight>

[[Category:Operations grimoire]]
[[Category:Vault]]

Wearg

2026-03-21T09:48:02Z

Dereckson: /* MariaDB server connectivity */

Wearg is an eggdrop and a notifications client.

== Features ==

Wearg handles two important workflows for the Nasqueron Operations SIG:

* Publish notifications on IRC channels: Services --HTTPS--> [[Operations grimoire/Notifications center|Notifications center]] --AMQP--> [[Operations grimoire/RabbitMQ|broker]] --AMQP--> Wearg --IRC--> Channel publication
* Allow to log to servers log: Channel publication --HTTPS--> Nasqueron API --IO--> servers log

== Troubleshoot ==
=== No messages are received ===
Check through another client (the CLI client for example) all works fine at notifications center and broker level.

If so:

# Check we're connected through <code>.tcl mq connected</code>
# If so, disconnect it with <code>.tcl mq disconnect</code>
# Check timer through .tcl utimers, you should have one (and only one) timer with ::broker::on_tick as callback
## Too many timers? kill extra timers with <code>.tcl killutimer timer<id></code>, good luck for the guess the second game
## No timer? <code>.tcl broker::on_tick</code>
# Ask next message in the queue .tcl mq get wearg-notifications
# If stuck at the previous operation, close the connection through the broker interface: http://white-rabbit.nasqueron.org:15672/#/connections (username is daeghrefn, source IP is 212.83.187.132). This method is pretty effective

=== Can't publish to servers log ===
==== MariaDB server connectivity ====

If the MariaDB connection is broken, <code>.+log [server] message works</code>, but not directly <code>[server] message</code>.

* Short-term solution: <code>.tcl sqlrehash</code> in the Wearg partyline
* Long-term solution: automate reconnect with {{T|2282}}

Wearg

2026-03-21T09:47:30Z

Dereckson:

Wearg is an eggdrop and a notifications client.

== Features ==

Wearg handles two important workflows for the Nasqueron Operations SIG:

* Publish notifications on IRC channels: Services --HTTPS--> [[Operations grimoire/Notifications center|Notifications center]] --AMQP--> [[Operations grimoire/RabbitMQ|broker]] --AMQP--> Wearg --IRC--> Channel publication
* Allow to log to servers log: Channel publication --HTTPS--> Nasqueron API --IO--> servers log

== Troubleshoot ==
=== No messages are received ===
Check through another client (the CLI client for example) all works fine at notifications center and broker level.

If so:

# Check we're connected through <code>.tcl mq connected</code>
# If so, disconnect it with <code>.tcl mq disconnect</code>
# Check timer through .tcl utimers, you should have one (and only one) timer with ::broker::on_tick as callback
## Too many timers? kill extra timers with <code>.tcl killutimer timer<id></code>, good luck for the guess the second game
## No timer? <code>.tcl broker::on_tick</code>
# Ask next message in the queue .tcl mq get wearg-notifications
# If stuck at the previous operation, close the connection through the broker interface: http://white-rabbit.nasqueron.org:15672/#/connections (username is daeghrefn, source IP is 212.83.187.132). This method is pretty effective

=== Can't publish to servers log ===
==== MariaDB server connectivity ====

If the MariaDB connection is broken, <code>.+log [server] message works</code>, but not directly <code>[server] message</code>.

Short-term solution: <code>.tcl sqlrehash</code> in the Wearg partyline
Long-term solution: {{T|2282}}

Code conventions

2026-03-20T01:47:16Z

Dereckson: /* Makefile */

== All languages ==

* Don't use more complicated constructs like ternary operators
* [http://jeroendedauw.github.io/slides/craftmanship/functions/#/1 Keep functions short and simple].
* Define explicitly methods visibility, as several languages have different default values (e.g. private for C# class members, public for PHP methods)
* Comments to document a method are written at the singular 3rd person (we seem to have moved to infinitive recently, we need to take a decision here)

== C ==
If you use [http://clang.llvm.org/docs/ClangFormat.html ClangFormat], a [https://github.com/dereckson/rabbitmq-tcl/blob/master/.clang-format .clang-format file] is available.

== JavaScript ==
The following conventions are used:
* K&R, 1TBS variant, including for functions
* 4 spaces as indent
* Use modern JavaScript idioms like <code>const</code> and <code>let</code> instead of <code>var</code>
* Consider to use async code for events-driven development, especially for servers

== PHP ==
The following conventions are used:
* K&R, 1TBS variant, including for functions
* 4 spaces as indent
* The keywords <code>true</code>, <code>false</code> and <code>null</code> must be in lower case.
* Arrays use short syntax
* Array elements ends with a comma
* Functions, methods and class names use camel case

If you use PhpStorm or another JetBrains IDE, you can import [https://github.com/nasqueron/codestyle/blob/master/JetBrains/php-codestyle.xml JetBrains/php-codestyle.xml] from the codestyle repository as a code style (Settings or Default Settings > Editor > Code Style > PHP > click on the wheel icon > Import Scheme > Intellij IDEA codestyle XML).

If you want to lint a project with phpcs, you can require the Composer package <code>nasqueron/codestyle</code> and use the following <kbd>phpcs.xml<kbd> standard file:

<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<ruleset>
<rule ref="vendor/nasqueron/codestyle/CodeSniffer" />
<file>.</file>
<exclude-pattern>\.git/</exclude-pattern>
<exclude-pattern>vendor/</exclude-pattern>
</ruleset>
</syntaxhighlight>

== Python ==
=== Code style ===
'''2023.''' We follow [https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html black style], so use black utility (<code>pip install black</code>). As such, you need to configure Flake8 to ignore rule E203.

'''2015.''' We follow [https://www.python.org/dev/peps/pep-0008/ PEP-8].

=== Templates ===
A template exists for a new Python command: [https://devcentral.nasqueron.org/source/snippets/browse/main/python/command.py python/command.py]

In packages, empty __init__.py files can follow [https://devcentral.nasqueron.org/source/merge-dictionaries/browse/main/src/mergedictionaries/utils/__init__.py;eaf5bc2c21118454837e8148147606c19d4afff7 this example].

=== Configuration files ===
Allow empty configuration files. For example, the YAML parser will return None if the file exists but is empty, we can catch that and return default instead:

<syntaxhighlight lang="python">
with open(get_configuration_path()) as fd:
return yaml.safe_load(fd) or {}
</syntaxhighlight>

== Rust ==
'''2023.''' Automated codestyle (black in Python, clang-format in Rust) seems preferable. As such, a style compatible with <code>rustfmt</code> is needed to be able to format using <code>cargo fmt</code>. You can add to your project [https://devcentral.nasqueron.org/source/codestyle/browse/main/rust/rustfmt.toml rust/rustfmt.toml in codestyle] to configure it.

'''2015.''' We followed "Rust default style", described at [https://web.archive.org/web/20170320083740/http://aturon.github.io/ https://aturon.github.io/]. It's mainly a K&R, 1TBS variant.

Use trailing comma for elements in every struct/impl/etc.

=== Threads ===
Standard library isn't the most ergonomic for threads programming, those crate allows more efficient and legible code:
* [https://docs.rs/crossbeam-channel/latest/crossbeam_channel/ crossbeam_channel] for mpmc (multiple producers, multiple consumers)
* [https://docs.rs/parking_lot/latest/parking_lot/type.Mutex.html parking_lot] for Mutex

== Salt ==
=== Style ===
Whitespaces:
* Indent with two spaces
* YAML lists use indented bullets

<syntaxhighlight lang="yaml">
id:
method:
- somekey: value
- otherkey: value
</syntaxhighlight>

=== Tips ===

;Files provisioned
* When you ask to download a file remotely, you need a source hash, pick SHA256 as algo
* Each file provisioned from the Salt repository must contains an header explaining the fact, with the full path in the rOPS repo

;BSD and Linux distros compatible states
* populate the map.jinja file with OS logic (e.g. `dirs` for /etc vs /usr/local/etc)
* when you've a specific set of tasks to do for one OS/distro, it's acceptable to enclose it in a state by an if block

=== Vocabulary ===

;Domain names
:To refer to the fully qualified domain name sub.domain.tld, use '''fqdn'''. To split the domains in part, use '''domain''' and '''subdomain'''. This is important to understand a state without having to refer to the associated pillar to disambig domain.

== Shell scripts ==
;UNIX agnosticism:
* Don't assume absolute path, use <code>#!/usr/bin/env bash</code> and not <code>#!/bin/bash</code> (it could be elsewhere on BSD or Solaris)
* Use `sh` as must as possible, try to avoid <code>bash</code>, document exceptions rationale in your commits

;Whitespaces:
* One whitespace line between shebang and actual content
* 4 spaces as indent

;File names:
* We use hyphens (-) as separators, not underscores or camelcase
* Filename should start by a verb if it performs an action
* Don't use .sh extensions when deployed as command
** sometimes you'll see them on Phabricator pastes' titles, but it has been added there, so Phab knows shell syntax highlighting should be used
** '''Tip.''' You can use .sh in src/ to help linters, but then provide a Makefile to install it under correct name without extension. Same for operations repository where everything uses .sh, but when deploying with file.managed the extension is omitted

;Templates
* New command: [https://devcentral.nasqueron.org/source/snippets/browse/main/shell/script.sh shell/script.sh]

== TCL ==

* Indent with 4 spaces, as of 2026-03-20
* Keep blocks visually separated
* Use Tcl primitives instead of manual parsing for strings: split, lindex, lrange, join
* Avoid regex unless necessary
* List expansion {*} instead of eval

; ViperServ development
* If you build a full new system, all procedures must be defined in a namespace
* Use fully-qualified names (::namespace::proc) for procedure definitions and cross-namespace calls
* Separate low-level request logic from API-specific methods

== Makefile ==
UNIX agnosticism:
* Test your makefile against BSD make, and document in README.md to use GNU Makefile (gmake) when it's not convenient to keep compatibility

Presentation:
* Create a block with the general targets, then sections with your targets organized by categories/goals/parts

Tip:
* It's possible to provision BSDmakefile and GNUmakefile when UNIX agnosticism doesn't work.

== Structured data formats (YAML, JSON, XML) ==
The number of spaces depend if the format is usually heavily hierarchized or not:

* 2 spaces for JSON and YAML
* 4 spaces for XML, TOML and other configuration files

== Utilities ==

The https://github.com/nasqueron/codestyle repository contains resource to help to respect code convention, like a phpcs ruleset, a configuration ready for PhpStorm, IntelliJ and other JetBrains editors, or a clang-format configuration file.

== Troubleshoot ==
=== Fix indent issues ===
The <code>expand</code> utility converts tabs into spaces, while <code>unexpand</code> convert spaces into tabs.

Switch a file from tab indent to 4 spaces indent:

$ expand -t 4 foo.sh > a
$ cat a > foo.sh
$ rm a

(Avoid <code>mv</code> for shell scripts as your foo.sh has probably a 755 chmod, and a will probably have a 644 chmod, assuming 022 as umask)

Switch a file indent with 2 spaces to 4 spaces:

$ unexpand -t 2 JetBrains/php-codestyle.xml > a
$ expand -t 4 a > JetBrains/php-codestyle.xml

This last technique can be used in batch [https://gist.github.com/dereckson/80a746b408c0cf0b688a09db31d5c881 with this reindent script]:

$ git ls-files | xargs -n1 reindent 2 4

[[Category:Reference]]
[[Category:Contributor guide]]

Clean up

2026-03-20T01:38:43Z

Dereckson: /* Tab to spaces */

== Style ==
=== EOL at EOF ===
There is a need for a blank line at end of file.

You can add them with <code>echo</code>.

<syntaxhighlight lang="console">
$ git ls-files | while read f; do tail -n1 $f | read -r _ || echo >> $f; done
</syntaxhighlight>

=== UNIX lines ===
<syntaxhighlight lang="console">
$ dos2unix
</syntaxhighlight>

=== Encoding ===
<syntaxhighlight lang="console">
$ iconv -f iso-8859-15 -t utf-8
</syntaxhighlight>

=== Tab to spaces ===
Git has a filter to be able to normalize with expand. See [https://eev.ee/blog/2016/06/04/converting-a-git-repo-from-tabs-to-spaces/ here].

As expand doesn't have a inline capability, you need to create a temporary file:

tmp_file=$(mktemp -t spaces)
expand -t 4 "$source_file" > "$tmp_file"
mv "$tmp_file" "$source_file"

=== Trailing spaces ===
<syntaxhighlight lang="console">
$ git ls-files | xargs -n 1 gsed -i 's/[[:space:]]*$//'
</syntaxhighlight>

=== UTF-8 BOM ===
Some old editors started a file by the sequence of bytes [0xEF, 0xBB, 0xBF] to allow the UTF-8 file encoding to be detected. This practice is discouraged nowadays and those should removed.

<syntaxhighlight lang="console">
$ sed -e '1s/^\xef\xbb\xbf//' < bomfile > newfile
</syntaxhighlight>

[[Category:Howto]]
[[Category:Contributor guide]]

WindRiver

2026-03-19T22:23:05Z

Dereckson:

User:Dereckson/Devserver

2026-03-19T22:02:12Z

Dereckson:

== MediaWiki ==
=== Logs ===
tail -n 100 -f /var/log/www/dereckson.be/mediawiki-php.log

=== Reinstall ===
* /var/51-wwwroot/mediawiki-dereckson/core: wikimedia/core repository
* /var/51-wwwroot/mediawiki-dereckson/core/extensions: symlink to <code>../extensions</code>
** Clone all needed extensions in /var/51-wwwroot/mediawiki-dereckson/extensions
* /var/51-wwwroot/mediawiki-dereckson/core/skins: symlink to <code>../skins</code>
** Same with git clone ssh://review/mediawiki/skins/
* /var/dataroot/mediawiki.dereckson.be/data contains:
** my_wiki.sqlite for the content
** wikicache.sqlite for the cache

=== Update ===
* '''Core:''' mw-update-core (currently writing it)

=== Create a new extension ===
;I. Wikimedia side
* [[mw:Manual:Developing_extensions]]
* [[mw:Gerrit/New repositories/Requests]]
* [https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?projects=Project-Admins Create task for new Phabricator project]

;II. WindRiver

<syntaxhighlight lang="shell">
$ setenv MW_EXTENSION foo
$ cd ~/dev/wikimedia/mediawiki/extensions
$ git clone ssh://review/mediawiki/extensions/$MW_EXTENSION || git init $MW_EXTENSION
</syntaxhighlight>

Extension is actually stored at /var/51-wwwroot/mediawiki-dereckson/extensions, so can immediately be configured to test locally.

;III. SaaS deployment
* {{Ops file|pillar/saas/mediawiki.sls}}
* [https://devcentral.nasqueron.org/source/saas-mediawiki/browse/main/config/Settings.php config/Settings.php]

=== Troubleshoot ===
==== SQLite database is read-only ====
Runtime error near line 2: attempt to write a readonly database (8)

<syntaxhighlight lang="shell">
chown -R web-be-dereckson-mw:dereckson /var/dataroot/mediawiki.dereckson.be/data
chmod 771 /var/dataroot/mediawiki.dereckson.be/data
chmod 660 /var/dataroot/mediawiki.dereckson.be/data/my_wiki.sqlite
</syntaxhighlight>

=== Permissions to run tests and maintenance scripts ===
To run tests against wiki and maintenance scripts as user can be tricky:

<syntaxhighlight lang="shell">
touch /tmp/mw-GlobalIdGenerator5001-UID-nodeid /tmp/mw-GlobalIdGenerator5001-UUID-128
chown web-be-dereckson-mw:dereckson /tmp/mw-GlobalIdGenerator5001-*
chmod 664 /tmp/mw-GlobalIdGenerator5001-*

chmod 771 /var/dataroot/mediawiki.dereckson.be/data/locks
</syntaxhighlight>

== Zed ==
=== Logs ===
tail -n 100 -f /var/log/www/dereckson.be/zed51-php.log

=== Staging ===

'''Note. Keruald is currently symlinked from the monorepo to vendor/keruald.'''

To recreate Zed staging area:

$ cd /var/dataroot/zed/content
$ git init .
$ git config --global --add safe.directory /var/dataroot/zed/content
$ git remote add origin git@github.com:hypership/content.git
$ git fetch --all
$ git reset --hard origin/main
$ git clone git@github.com:hypership/content_users.git users

$ sudo -u web-be-dereckson-zed51 mkdir /var/dataroot/zed/cache/sessions
$ sudo mkdir -p /var/dataroot/zed/content/users/_photos/tn
$ sudo chown -R web-be-dereckson-zed51:dereckson /var/dataroot/zed/content/users/_photos
$ sudo chmod 771 /var/dataroot/zed/content/users/_photos /var/dataroot/zed/content/users/_photos/tn

$ mkdir -p /home/dereckson/dev/zed/hypership
$ cd /home/dereckson/dev/zed/hypership
$ ln -s /var/dataroot/zed/content

Note: Zed currently not defined in wwwroot-51 in rOPS, should be done for /var/51-wwwroot/zed

== IRC ==

=== Troubleshoot ===
==== Error loading module proxy/irc ====
When trying to load proxy module, I got:

22:00:09 -!- Irssi: Error loading module proxy/irc: /home/dereckson/.irssi/modules/libirc_proxy.so: Undefined symbol "g_input_add"

Proxy is now compiled by default, personal module needs to be deleted.