These repository-wide instructions apply to contributors and coding agents working in this checkout.
- Before creating a role, read and follow the contribution criteria in
README.mdand the new-role requirements in.github/PULL_REQUEST_TEMPLATE.md. - Derive patterns from current, actively deployed roles. Deprecated, migration,
alias, and
No CIroles are exceptions and must not be used as templates for new roles. - Before adding or renaming a role or tag, search both Sandbox and Saltbox for
role and tag collisions. Do not introduce a Sandbox role that unintentionally
shadows a Saltbox role through
roles_pathprecedence.
- Use
snake_casefor role directories, Ansible role names, and variable prefixes. Declare the user-facing install tag explicitly insandbox.yml; every literal Ansible tag uses lowercase kebab-case. Role names and install tags do not need to be identical. - Start Ansible source YAML under
defaults/,tasks/,handlers/, andvars/with the repository's standard title, author attribution, repository URL, GPL, and YAML-document header. Preserve existing contributor attribution when modifying roles. Static YAML payloads underfiles/and templates are outside this source-header rule. - New active application roles contain
defaults/main.ymlandtasks/main.yml. Add templates, files, or task subtasks only when the role uses them. - Add new main and independently runnable roles under
Apps Startinsandbox.ymlwith their install tags by default. UseNo CIonly when a role cannot participate in the install matrix or is not runnable by itself; non-runnable companion roles usenever. - Keep auxiliary tags on the application's single role entry. Exclude
display-only tags through the CI
ignored_tagsconfiguration rather than registering the same role again underNo CI. - When a role supports multiple instances, declare
<role>_instances, keep the instance loop intasks/main.yml, and put per-instance work intasks/main2.yml. Set<role>_namefrom the loop item and useinstanceas the loop variable for new roles.
- Follow established role patterns; avoid custom/unusual implementations.
- Use the standard variable naming scheme:
<role>_name,<role>_role_*withlookup('role_var', ...). - Every
lookup('role_var', ...)in defaults must specify an explicitrole=target; cross-role targets remain valid. - When an empty string, list, or mapping should select a supplied fallback, use
default_if_empty=truewith a non-Nonedefault; do not repeat manual non-empty checks aroundrole_var. - Prefer simple, predictable defaults; leave optional values empty rather than inventing new behavior.
- Add plain-language comments for non-obvious user-facing settings and their constrained values. Describe the setting's purpose instead of restating an upstream environment-variable name. Use the documentation directives below when a comment should apply to multiple variables.
- Keep configurable API endpoints, release-metadata endpoints, and reusable
download bases in role defaults and resolve them through
role_var. A fixed one-off upstream asset may remain in a task when no override is intended. - When CI needs credentials that satisfy role validation, generate a compliant role-local variable with a
set_facttask guarded bycontinuous_integrationinstead of changing workflows or global user credentials. - Use generator options that guarantee required character classes instead of adding hardcoded character prefixes.
- Keep one-time database bridge releases in an explicit migration role and leave the regular role on the current release.
- Detect completed database migrations from database integrity and preserved records, not from marker files or file existence alone.
- Keep edits ASCII-only and minimal unless the repo already uses Unicode in the same file.
- Use plain action and domain wording in variables and task names.
- When present, order top-level sections as Basics → Settings → backend-specific sections → Paths → Web → DNS → Traefik → Ports → Docker → Dependencies. Keep the literal
PostgresandRedissections between Settings and Paths, and keep Ports immediately before Docker. - Paths:
<role>_role_paths_folderdefaults to<role>_name.<role>_role_paths_locationuses{{ server_appdata_path }}/{{ <role>_role_paths_folder }}.<role>_role_paths_folders_listincludes the appdata root and any subpaths the app needs.- Use
<role>_role_paths_recursive: truewhen a role needs its folders recursively owned by the configured user. Recursive handling changes owner and group only;_paths_permissionsapplies to explicitly declared directories and existing child modes are preserved.
- Web/DNS/Traefik follow the standard Saltbox/Sandbox templates (subdomain/domain/port/url; DNS record/zone/proxy; traefik defaults).
- Keep port allocation inputs, assigned-port lookups, and allocation bounds in a dedicated top-level
Portssection. The Docker# Portssubsection contains only actual container port-bind defaults, customizations, and their composed list. - Remove a role's existing Docker container before assigning ports. The allocator treats every remaining running or stopped container binding as unavailable and never adopts an existing container port.
- Every role declaring
<role>_role_traefik_enabledalso declares the complete API router contract: middleware defaulted totraefik_default_middleware_api, an empty custom middleware layer, an API-enabled toggle, and an API endpoint. Usefalseand an empty endpoint when the role has no default API route. - A parent role that exposes a namespaced web adapter through an included Traefik-enabled role declares the complete regular and API Traefik contract under the parent namespace and forwards every field into the included role's
*_role_traefik_*variables. - Canonical web URL defaults use
lookup('role_web', role='<role>', scheme='https'); canonical host defaults omitscheme. Named endpoint families passendpoint='<family>'. - Keep local-service, credential-bearing, port/path, and URL-from-host variants explicit so existing override layering remains authoritative.
- Docker:
- Define container, image-pull, image-repository, image-tag, composed-image, hostname, and restart-policy defaults for roles using the shared Docker container task. Define network alias/default/custom/composed defaults unless an explicit supported network mode replaces attached networks.
- Container state is owned by the shared Docker container task, which creates
containers in the started state. Do not add a role-local
_docker_statedefault. - A computed Docker image must define
_docker_image_repoand_docker_image_tagdefaults and access both through explicitlookup('role_var', ..., role='<role>')calls. - Network aggregates must use either
docker_networks_common + _docker_networks_default + _docker_networks_customor the interface-pinned variant. The interface-pinned variant may add onlycom.docker.network.endpoint.ifnameto common networks withmap('combine', ...), and the application network must pin a distinct interface. Both variants keep custom last. - Do not override network aliases or use other custom
map('combine', ...)logic. - GPU-capable roles declare
<role>_role_docker_gpu_enabled: truein defaults and rely on the shared Docker container task. Do not includeset_docker_gpu_variables.ymlfrom application role tasks. Globaluse_intelanduse_nvidiaremain mandatory gates;_docker_nvidia_disabledand_docker_dev_dri_disabledare optional per-container opt-outs. - When Docker hosts are used, compose only the role-local
_docker_hosts_defaultand_docker_hosts_custommappings; do not adddocker_hosts_common. - Set
<role>_role_docker_networks_aliasto the role name variable (e.g.,{{ <role>_name }}); avoid custom alias strings. - Only include the ports block if the app needs host‑published ports.
- Define Docker healthcheck tests as an explicit block list beginning with
CMD,CMD-SHELL, orNONE. PreferCMD; when shell syntax requiresCMD-SHELL, add the exact# saltbox-lint allow cmd-shelldirective to thetest:line. - Follow the Saltbox linter for parser-level Jinja formatting; do not duplicate its indentation algorithms in this guidance.
- Avoid custom security/capability defaults unless there is a clear repo precedent.
- Do not add
_role_docker_sections with empty defaults. Networks are always defined for normally attached containers; omit them only when an explicit supported network mode replaces attached networks. Omit envs/volumes/ports/labels/etc. unless used. - Conditional ports may intentionally default to no host bindings; do not require
_docker_ports_customto be unconditional without first confirming the role's exposure semantics. - When an application data path has a matching environment setting, set it explicitly to the container-side volume path so an upstream default change cannot redirect persisted data.
- Treat
<role>_role_docker_envs_customonly as the final environment override layer; do not inspect it to compute first-class role defaults. - When an image ignores PUID/PGID but supports an arbitrary runtime user, use
{{ uid }}:{{ gid }}as the Docker user and recursively normalize existing appdata ownership without changing file modes.
- Build
*_role_depends_onfrom explicit container names or role-local variables. If you uselookup('role_var', ...)for another Sandbox role's container, ensure that role is listed insandbox.ymlso its defaults are loaded; its tag can be its own ornever. Saltbox role defaults are supplied bypre_tasksand do not require Sandbox registration. - For multi-role apps, keep all user-facing settings in the main role; imported roles should not define their own settings defaults.
- Keep PostgreSQL-specific defaults in a dedicated
Postgressection; only the<role>_role_postgres_deploytoggle may remain inSettings. - In sub-roles, environment variable lookups that rely on settings must target the main role (use
lookup('role_var', ..., role='<main_role>')). - Default initial application-administrator username, password, and email
settings in the main role to
user.name,user.pass, anduser.email, and have sub-roles use those settings. Provider, SMTP, database, and service credentials require their own role-local settings. - When an application imposes stricter credential rules than the global defaults, wrap the global value in a role-local setting and direct validation failures to that override so users do not have to change the global credential.
- Name internal computed defaults with a
_lookupsuffix instead of_effective, and place the appropriate directive immediately above each lookup variable.# Do not edit or override using the inventoryis a hard prohibition for values that must never be changed through inventory.# Skip docshides an internal variable from generated documentation because users are not expected to edit it, but it is not an absolute prohibition on inventory overrides. Preserve the stronger directive when it already exists, and never stack the two comments.
- Docs automation reads top-level variables from
defaults/main.yml, after the---marker when present. Standard hash-delimited sections determine the rendered grouping and order; files without sections useGeneral.Pathsand metadata sections are omitted.Web,DNS,Traefik, andDockersections also control which global override families are shown. - Use
# <Name> - Sub-section Startand# <Name> - Sub-section Endto group related variables. These markers are case-sensitive; close each subsection before starting another.
| Comment or directive | Scope and effect |
|---|---|
# Ordinary comment |
Describes only the next variable; consecutive lines form one comment block. |
# [GLOBAL] text |
Adds shared text to subsequent variables until a new section or subsection end. Multiple lines accumulate. |
# [NOGLOBAL] text |
Suppresses shared text for the next variable and uses its local comment block instead; later variables still inherit the shared text. |
# Skip docs |
Excludes the next variable from generated documentation. |
# Do not edit or override using the inventory |
Also excludes the next variable; retain the stronger inventory restriction described above. |
[GLOBAL]and[NOGLOBAL]are case-sensitive. Put[NOGLOBAL]at the beginning of the variable's local comment block. Ordinary local comments otherwise follow the inherited global text. Blank lines do not clear pending comments or global scope.- For exclusion directives, follow the exact spelling and placement required
above for
_lookupvariables. Prefer# Skip docsfor documentation-only exclusion; preserve existing inventory prohibitions and never stack both. - In
Docker, associated comments become headings; explanatory example comments come fromdocker_overrides.variables.*.descriptionin the docs configuration. - An
_instancesvariable enables instance-aware output._defaultor_customvariables hide their corresponding aggregate variable. Shared Docker options absent from the role appear in Docker+ when enabled by the docs configuration; hidden Docker sections also hide Docker+. - Page frontmatter supports
disabled,checks,sections,inventory,app_links, andproject_descriptionundersaltbox_automation.inventory.show_sectionsandinventory.hide_sectionsfilter sections case-insensitively, with hiding taking precedence; they cannot restore parser-excluded sections.inventory.example_overridessupplies separate YAML examples without changing defaults or inferred types. - When editing page controls or generator configuration, consult the complete
frontmatter reference
and configuration reference.
The role-authoring reference
documents source directives and discovery. Preview affected roles with
sb-docs generate <role>using the configured docs generator, and inspect each variable's rendered comments, visibility, and examples.
- Use
ansible.builtin.include_tasksandansible.builtin.include_rolefor task and role composition; do not introduce static imports. When wrapper tags must apply to included child tasks, keep the tags on the include and repeat them underapply.tags. - Before changing a shared
resources/tasksfile's inputs, setup, or variable resolution, search Saltbox and Sandbox for every direct include. Treat multiple callers as a real interface: pass explicit inputs from every caller, exercise each distinct caller condition, and keep the shared task independent of stale host-levelset_factvalues. - When a shared resource replaces a registered task, expose the effective underlying module result under a caller-named variable and preserve the caller's failure suppression and success/failure tests.
- Treat fixtures that pin computed facts as downstream-only. Shared-fact acceptance completes only when each real tagged playbook path resolves and schedules the intended producer through
roles_path, including same-name shadow roles, and consumes the produced fact downstream. - Before an application role imports a database or persistent-backend role, remove every existing application or worker container that can access that backend. Place these removals after non-mutating validation and fact resolution but before the first backend import; removing a legacy backend container does not satisfy this requirement.
- Common flow (as applicable): DNS → remove container → create directories → create container.
- Use
resources_tasks_pathhelpers:docker/remove_docker_container.yml,directories/create_directories.yml,docker/create_docker_container.yml. - Perform Git checkouts through
resources/tasks/git/clone_git_repo.yml; do not callansible.builtin.gitdirectly from role tasks. - Fetch GitHub API metadata through
resources/tasks/git/github_api_request.yml; do not referencesvmdirectly from role defaults or tasks, and keep archive downloads direct. - For simple web installers with deterministic defaults, prefer completing the upstream installer with
ansible.builtin.urion fresh non-CI installs, protect submitted credentials withno_log, and verify the generated config; correct existing configs separately. - Validate required settings with
ansible.builtin.failin the main role that imports other roles (do not put required-variable fails in sub-roles). - Persist generated secrets that must remain stable across runs with
saltbox_facts; expose a role setting defaulted to the registered fact and validate the resolved setting before container creation. - Load persisted role facts through
saltbox_factsrather than parsing its INI storage directly. For retrieval, omitkeysso missing values are not inserted as empty placeholders. - Place prompts for copying generated setup credentials after application deployment. Include the application URL and instructions explaining where and how to use the credential, both in prompts and in display-only tags.
- In assertions, prefer boolean Jinja tests such as
is search(...)oris match(...)over filters such asregex_searchthat return strings ornone. - When validating API keys derived from
get_info, fail if the value is empty or equals the default"not installed"string. - For multi‑service apps, include the backend/DB role first, then frontend.
- When defaulting service URLs or API keys from existing instances, include
resources/tasks/instances/get_info.ymland pass an explicitget_info_listcontaining every service whose discovered information the role consumes. sandbox.ymlruns Saltbox'spre_tasksrole before application roles, and its variable-loading step imports every Saltbox roledefaults/main.ymlinto the Sandbox play. Treat variables provided by Saltbox role defaults, including instance lists, as defined; do not add redundant existence guards, discovery, or duplicate defaults for them.
- If a parent role includes a backend role, pass settings explicitly in
include_rolevars. - Keep backend appdata under the parent role’s appdata folder unless the repo shows a different pattern.
- When sharing appdata, set the backend role
*_paths_locationto the main role*_paths_locationto avoid creating unused folders. - If a backend role shares the main role appdata, omit the backend Paths section and skip
create_directories; use the main role paths directly in the backend volume defaults. - If the main role includes a backend role via
include_role, do not give the backend the same tag insandbox.yml(that would double‑run). - If the backend is a companion role not meant to run by itself, tag it
neverand place it under the “No CI” section. - If the backend is meant to run by itself, give it its own tag (not the main role’s) and keep it under Apps Start.
- If you do put the backend role in
sandbox.ymlwith the same tag as the main role, remove theinclude_role.
- Treat
.github/workflows/sandbox.ymland the Saltbox linter as the current sources of truth for mechanically enforced checks; do not reproduce their complete rule sets here. - Before handoff, run
ansible-lint, the Go-based Saltbox linter withsaltbox-lint check ., andgit diff --check. The Python linter is not a substitute for the Go linter. Run./scripts/check_missing_entries.shwhen changing roles orsandbox.yml. Follow.github/workflows/sandbox.ymlfor the current Saltbox checkout and dependency setup. - Run installation or behavior tests only on an explicitly designated disposable or test Saltbox host. Report static validation separately from live role validation, and state any coverage that could not be performed.