Dereckson at 19:30, 11 February 2026

2026-02-11T19:30:41Z

← Older revision		Revision as of 19:30, 11 February 2026
Line 176:		Line 176:

	However, you can start contributing with basic YAML knowledge and learn as you go!		However, you can start contributing with basic YAML knowledge and learn as you go!

			[[Category:Operations grimoire]]
			[[Category:FAQ]]

Dereckson: Created page with "== General Questions == === What is the rOPS repository? === rOPS ('''r'''epository '''OPS''') is the Nasqueron operations repository. It contains the configuration of our infrastructure servers and follows the principle of ''Infrastructure as Code'' to offer documentation, reproducibility, transparency and to allow external contributions. The repository is available at https://devcentral.nasqueron.org/diffusion/OPS/ === What does this repository contain? === The re..."

2026-02-11T19:30:28Z

Created page with "== General Questions == === What is the rOPS repository? === rOPS ('''r'''epository '''OPS''') is the Nasqueron operations repository. It contains the configuration of our infrastructure servers and follows the principle of ''Infrastructure as Code'' to offer documentation, reproducibility, transparency and to allow external contributions. The repository is available at https://devcentral.nasqueron.org/diffusion/OPS/ === What does this repository contain? === The re..."

New page

== General Questions ==

=== What is the rOPS repository? ===

rOPS ('''r'''epository '''OPS''') is the Nasqueron operations repository. It contains the configuration of our infrastructure servers and follows the principle of ''Infrastructure as Code'' to offer documentation, reproducibility, transparency and to allow external contributions.

The repository is available at https://devcentral.nasqueron.org/diffusion/OPS/

=== What does this repository contain? ===

The repository contains:
* Server configuration
* Deployment information for our applications and services

Combined with NetBox, it constitutes an exhaustive inventory and source of truth for our infrastructure.

=== What technology does Nasqueron use for infrastructure management? ===

We mainly rely on [https://docs.saltproject.io/en/latest/contents.html Salt] (SaltStack) for deployment and automation. The repository also includes utilities for humans and Terraform provisioning.

=== What is the minimum Salt version required? ===

The minimum Salt version is '''3006'''.

=== What servers are in scope for this repository? ===

Both Nasqueron servers and side projects we manage are in scope. For example, the [http://www.eglide.org/ Eglide] service is configured through <code>roles/core</code> (common to every server) and <code>roles/shellserver</code> (specific).

== Repository Structure ==

=== How is the repository organized? ===

The repository is organized into seven main areas:

; A. Services : Configuration organized in roles and units
; B. Structured data : Pillar data for configuration
; C. SaltStack modules : Python modules for complex logic
; D. UNIX resources assignments : UIDs, GIDs, and port assignments
; E. Tests : Unit and integration tests
; F. Resources : Templates and resources for automated tasks
; G. Utilities : Scripts for operations team members

=== What are roles and units? ===

'''Roles''' are full high-level services (e.g., mailserver, paas-docker). They represent the goal a server accomplishes.

'''Units''' are components needed to achieve the service's goals (e.g., a userland software collection, a nginx server).

Directory structure follows <code>roles/<role>/<unit></code>.

=== What are states and formulas? ===

States (also called formulas) are the configuration files in the <code>roles/</code> directory. They are generally written in YAML with Jinja2 templating.

The <code>top.sls</code> file defines which states are loaded by server, while the <code>services.sls</code> describes service configurations that aren't server-specific.

=== What is pillar? ===

Pillar is structured data stored in the <code>pillar/</code> directory. This data is structured cleanly and queried from states, directly or through functions. Each pillar .sls file is written in YAML.

The <code>top.sls</code> file defines which pillar files are loaded by server, while the <code>tower.sls</code> file acts similarly and allows more flexibility.

=== What is the map.jinja file for? ===

The <code>map.jinja</code> file provides "Omni-OS" configuration. Since we deploy onto several Linux distributions (Debian, Rocky) and FreeBSD, we need to provide a way to map packages and directories across different operating systems.

=== Where are configuration files stored? ===

If configuration files for a unit should be stored, a subfolder <code>files/</code> is created at unit level within the role/unit structure.

=== What are SaltStack modules? ===

While states offer powerful templating capabilities, they can become too complex when evolving from declarations to full programs. Salt modules express more complex logic in Python. The Python functions can be called directly from states.

Modules are stored in:
* <code>_modules/</code> for execution modules
* <code>_states/</code> for states modules

=== What is the hotfixes directory for? ===

If anything escapes the role and unit logic organization, like CVE hotfixes, the <code>hotfixes/</code> directory is used.

=== Where are UIDs, GIDs, and ports documented? ===

This repository is the source of truth for service accounts, groups and ports:
* '''UIDs''' document unique usernames and the UIDs for system accounts
* '''GIDs''' document the same information for groups
* '''PORTS''' contain the list of reserved application ports

When a service needs any of those resources, they are assigned in those files.

=== How do I test my changes? ===

Unit and integration tests are stored in <code>_tests/</code>

You can test the correctness of several repository aspects:
* Salt configuration files in <code>_tests/config/</code>
* Salt execution modules in <code>_tests/modules/</code>
* Salt pillar in <code>_tests/pillar/</code>
* Scripts deployed within this repository in <code>_tests/scripts/</code>

If you add a new directory, you should add a corresponding entry in <code>Makefile</code>.

=== What are resources and utilities? ===

'''Resources''' (<code>_resources/</code>) are used by automated tasks to generate repository files, such as templates for new services.

'''Utilities''' (<code>utils/</code>) are scripts and other utilities to be run by Nasqueron Operations SIG members.

== Contributing ==

=== How can I contribute? ===

Contributions are welcome, especially if you wish to:
# Improve our infrastructure
# Install or configure something on a Nasqueron server
# Install or configure something on a project we manage (like Eglide)
# Automate deployment of one of your Nasqueron projects

Follow the [https://agora.nasqueron.org/How%20to%20contribute%20code contributor guide] to send a commit for review. This procedure is open to everyone.

=== Where can I report issues? ===

Issues can be reported on the [https://devcentral.nasqueron.org/tag/servers/ #Servers component] on DevCentral, the Nasqueron Phabricator instance.

=== Where can I find more documentation? ===

Documentation about the repository and tips for IDEs are available on Agora:
https://agora.nasqueron.org/Operations_grimoire/Operations_repository

=== Where can I get help? ===

Support for contributors is provided on our IRC channel: '''#nasqueron-ops''' on [https://libera.chat/ Libera].

== Terminology ==

=== What terminology does Nasqueron use? ===

The repository uses inclusive terminology:

; Salt primary server : A server that issues commands to other servers or itself
; Node : A server, baremetal or VM configured by Salt

Nasqueron follows the inclusive language conventions to ensure that our community is welcoming to everyone.

=== Why doesn't the repository use master/slave terminology? ===

Nasqueron follows inclusive language conventions. Instead of "master," we use "Salt primary server" to describe the server that issues commands.

== Licensing ==

=== What is the license for this repository? ===

A lot of configuration as code is trivial, and so ineligible for copyright per [https://en.wikipedia.org/wiki/Threshold_of_originality threshold of originality].

When this is not the case, the code is licensed under [https://opensource.org/licenses/BSD-2-Clause BSD-2-Clause] if not otherwise specified.

== Getting Started ==

=== I'm new to the repository. Where should I start? ===

# Read this FAQ and the main [https://devcentral.nasqueron.org/diffusion/OPS/ README]
# Check the [https://agora.nasqueron.org/Operations_grimoire/Operations_repository Operations grimoire] for detailed documentation
# Join our IRC channel '''#nasqueron-ops''' on [https://libera.chat/ Libera] for support
# Browse the <code>roles/</code> directory to see how services are structured
# Look at existing commits on DevCentral to understand the contribution workflow

=== What background knowledge do I need? ===

Helpful knowledge includes:
* YAML syntax
* [https://docs.saltproject.io/en/latest/contents.html SaltStack] basics
* Jinja2 templating
* Python (for writing modules)
* UNIX / Linux system administration

However, you can start contributing with basic YAML knowledge and learn as you go!

Operations grimoire/Operations repository/FAQ - Revision history

Dereckson at 19:30, 11 February 2026