Settings

settings.yml

Note

Reference for every variable in defaults/settings.yml.default. That file is the shipped default. Your own settings.yml, which you create by copying it, takes precedence and is the only file you should edit.

Table of Contents

• Creating your settings file
• Must change before the first run
• Global settings
• Conventions
• Core
• Download
• PVR
• Media
• Tools
• Monitoring
• Extras
• Generated secrets

Creating your settings file

cp defaults/settings.yml.default settings.yml
nano settings.yml

The playbook loads the default file first and your file second, so anything you leave out falls back to the shipped default. You can delete every block you do not intend to deploy.

Warning

settings.yml holds every secret in the stack in plaintext. It is git-ignored, keep it that way, and do not paste it into an issue.

Must change before the first run

These have placeholder values that either will not work or are not safe to expose.

Setting	Why
domain	Your domain. Nothing resolves without it
data_folder	Where all media lives. Point it at your storage before the first run, moving it later means moving the data
user, uid, group, gid	Must match the account that owns data_folder or hardlinking breaks
cloudflare.api_token	Cloudflare credential, see Cloudflare credentials
cloudflare.api_key, cloudflare.api_email, cloudflare.domain_zone_id	As above
traefik.origin_certificate	Required. There is no Let's Encrypt in this stack
traefik.origin_certificate_private_key	As above
authelia.username, authelia.password	Ship as demo / demo
authelia.jwt_secret	Ships as a_very_important_secret
authelia.unsecure_session_secret	Ships as demo
authelia.storage_encryption_key	Must be at least 64 characters or Authelia will not start
qbittorrent.web_password, web_password_salt	Ship as placeholder strings
nzbget.restricted_username, restricted_password	Ship as demo / demo

Generate the random values with:

openssl rand -hex 32   # jwt_secret, session secret
openssl rand -hex 64   # storage_encryption_key

Global settings

Applied across every role.

Setting	Default	Description
user	debian	Host user owning the config and data directories
uid	1000	User ID passed to the containers as PUID
group	docker	Host group owning the config and data directories
gid	998	Group ID passed to the containers as PGID
ssh_port	22	Used by the Fail2Ban jail configuration
domain	example.com	Your domain. Every service is published as <subdomain>.<domain>
dynamic_ip	false	Set true on a residential connection to deploy the Cloudflare DDNS container
data_folder	/mnt/storage	Root of the media tree, see Folder Structure
tz	Europe/Berlin	Timezone passed to every container
notifications_email	example@mail.com	Default recipient for Authelia, Watchtower and unattended-upgrades mail
use_crowdsec	true	true deploys CrowdSec and the Traefik bouncer. false installs Fail2Ban instead

Important

use_crowdsec is an either-or switch, not an add-on. With true you get CrowdSec and the Traefik bouncer plugin. With false the hardening role installs Fail2Ban instead. You never get both.

Conventions

Most role blocks share the same three keys, so they are not repeated in every table below.

Key	Meaning
tag	Docker image tag. See Applications for the defaults
folder	Host path for that service's config, conventionally /opt/<service>
subdomain	Published as <subdomain>.<domain>

Only the keys that do something beyond this are documented per role.

Core

cloudflare

Setting	Description
tag_ddns	Tag for the cloudflare-ddns container, deployed only when dynamic_ip is true
tag_companion	Tag for traefik-cloudflare-companion
api_email	Cloudflare account email
api_key	Cloudflare Global API Key
api_token	Cloudflare scoped API token
domain_zone_id	Zone ID of your domain, found on the Cloudflare dashboard overview page

Cloudflare credentials

The stack uses two different Cloudflare credential types and they are not interchangeable:

Credential	Used by
api_token	The DDNS container only
api_key plus api_email	The Traefik Cloudflare Companion, which creates DNS records for each service

crowdsec

Setting	Description
console_enrollment_key	Enrolment key from the CrowdSec console. Optional, links your instance to the dashboard
firewall_bouncer_key	Key you choose, registered with cscli bouncers add firewall-bouncer
traefik_bouncer_key	Key you choose, registered as the Traefik plugin's LAPI key
whitelist_ip_range	CIDR that CrowdSec will never ban. Set this to your own network before deploying

Tip

The bouncer keys are values you invent, not values Cloudflare or CrowdSec issue. Generate them like any other secret and keep them consistent between runs.

traefik

Setting	Description
tag_bouncer	Version of the CrowdSec bouncer Traefik plugin
api_url	Hostname of the Traefik dashboard
origin_certificate	PEM body of your Cloudflare Origin Certificate
origin_certificate_private_key	Matching private key

Important

There is no ACME or Let's Encrypt in this stack. Traefik serves a Cloudflare Origin Certificate as its default certificate, and requires a verified client certificate from Cloudflare (clientAuthType: RequireAndVerifyClientCert) with a TLS 1.3 minimum.

This means two things are mandatory: paste both PEM blocks into settings.yml, and enable Authenticated Origin Pulls in Cloudflare as described on the Cloudflare page. Without both, Traefik will refuse the connection.

Paste multi-line PEM blocks with a YAML block scalar:

traefik:
  origin_certificate: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----

authelia

Setting	Description
username	The single account created in the users file
password	Plaintext here, hashed into the users file on deploy
displayname	Shown in the portal
email	Used for password reset
jwt_secret	Signs identity tokens
session_name	Name of the session cookie
unsecure_session_secret	Signs the session cookie
storage_encryption_key	Encrypts the Authelia database. At least 64 characters
redis.hostname	Hostname of the session store container
redis.folder	Host path for the Redis data
notification_email_to	Defaults to notifications_email
notification_email_from	Defaults to authelia@<domain>
notification_email_server	Defaults to the postfix container
notification_email_server_port	Defaults to 587
notification_email_server_user	Leave empty when relaying through the bundled postfix
notification_email_server_password	As above

Full detail on Authentication.

homer

Setting	Description
tag_companion	Tag for Homer Service Discovery
title	Dashboard title
subtitle	Dashboard subtitle, defaults to your domain
services	List of dashboard groups, each with a name and a Font Awesome icon

The services list defines the group headings only. Which card lands in which group comes from the homer.service label on each container, see the Homer matrix.

watchtower

Setting	Description
monitor_only	false by default, meaning Watchtower updates containers automatically
notification_email_delay	Delay in seconds before sending the notification mail

Warning

With monitor_only: false, Watchtower pulls and restarts containers on its own whenever an image tag moves. Combined with latest tags, your stack updates itself without asking. Set monitor_only: true to be notified instead of updated.

postfix

Setting	Description
hostname	Hostname the SMTP relay announces, and the name other containers use to reach it

Download

qbittorrent

Setting	Description
web_user	Web UI username
web_password	Web UI password
web_password_salt	Salt for the PBKDF2 hash the role writes into qBittorrent.conf
bittorrent_port	Incoming peer port, forward it on your router

rutorrent

Setting	Description
bittorrent_port	Incoming peer port
dht_port	DHT port

nzbget

Setting	Description
restricted_username	Restricted account, also used by the PVRs to connect
restricted_password	As above

PVR

All six roles use only the common tag, folder and subdomain keys.

Root folders and download clients are configured automatically, see Autoconfiguration.

Media

yamtrack

Setting	Description
secret	Django signing key. Leave empty to generate one into <folder>/.secrets/secret
user	Admin account created on first run. Leave empty for a generated name
password	Leave empty for a generated password, printed at the end of the play
registration	false by default. Yamtrack is published without Authelia, so leaving this false keeps signup closed
tmdb_api, trakt_api, mal_api	Metadata source keys. Empty means the image's shared default key
igdb_id, igdb_secret	IGDB client credentials
simkl_id, simkl_secret	Simkl client credentials
hardcover_api	Must include the Bearer prefix
comicvine_api	ComicVine key

Important

registration gates the public signup form. Because Yamtrack has no Authelia middleware in front of it, setting this to true opens account creation to anyone who can reach the URL. The admin account is created through the Django CLI and does not need it.

kavita

Setting	Description
user	Admin account created on first run. Leave unset for <domain without its TLD>.kavita
password	Leave unset for a generated 24 character password, printed at the end of the play

Note

kavita.user and kavita.password are supported by the role but are not listed in settings.yml.default. Add them to your own settings.yml if you want to choose the credentials rather than take the generated ones.

The admin account and the Books, Comics and Mangas libraries are created automatically, see Autoconfiguration.

seerr, jellyfin, navidrome

Common keys only.

Tools

filebrowser, syncthing, archivebox and whoami use common keys only. whoami has no folder, as it stores nothing.

Monitoring

speedtesttracker

Setting	Description
app_key	Laravel application key. Leave empty to generate one into <folder>/.secrets/app_key
admin_email	Leave empty to default to admin@<domain>
admin_password	Leave empty for a generated password, printed at the end of the play

scrutiny

Setting	Description
cron	How often the collector polls S.M.A.R.T data, cron syntax in the host timezone. Default every 6 hours

Disks are detected automatically with lsblk, including NVMe and virtio. Nothing to configure.

netdata, librespeed

Common keys only.

Extras

tinymotd

Setting	Description
folder	Where the tinymotd git checkout lands. No image, no subdomain

utils

Not represented in settings.yml.default at all. It reads its own role defaults, documented on the Utils page.

Generated secrets

Three roles will generate a secret for you when you leave the setting empty, persist it under <folder>/.secrets/, and print the resulting credentials at the end of the play.

Role	Generated when empty	Persisted at
Kavita	password	<folder>/.secrets/admin_password
Yamtrack	secret, user, password	<folder>/.secrets/secret
Speedtest Tracker	app_key, admin_password	<folder>/.secrets/app_key, <folder>/.secrets/admin_password

Because the passwords are persisted, re-running the playbook does not rotate them.

Important

These credentials are printed once, at the end of the playbook run. If you scroll past them, read the file under <folder>/.secrets/ on the host rather than redeploying.