Configuration

Configuration

GamesDownloader is configured in two layers:

1. Infrastructure - a handful of values set once in .env before the container starts: host paths, the database and Redis passwords, the auth secret, and the port. These cannot be changed from the web UI because the app needs them to boot. They are covered on the Installation page.
2. Everything else - scrapers, downloads, security, notifications, appearance, users, plugins, and so on. These are configured in the app after you log in, and stored in the application's database. Sensitive values (API keys, SMTP password, OAuth secrets) are encrypted at rest. This is where you will spend almost all of your configuration time.

This page is the map of that second layer.

---

Contents

• First run: the setup wizard
• Settings tabs at a glance
• Infrastructure vs in-app settings
• Where your data lives
• Backups

---

First run: the setup wizard

The first time you open GamesDownloader with no admin account, a 7-step setup wizard walks you through language, the admin account, an optional GOG connection, scraper keys, and basic preferences. It only appears until the first admin exists, and everything it sets can be changed later in Settings. See the setup wizard section on the Installation page for the step-by-step.

---

Settings tabs at a glance

The Settings area (admin view)

Open Settings from the user menu (top-right avatar). The tabs you see depend on your role: Appearance and Libraries are available to every user; the rest are admin-only. Each row links to the page with the full detail.

Tab	Who	What it controls	Details
Appearance	Everyone	Layout mode (Modern / Classic), colour skin, animation and background effects, active theme plugin.	Themes
Libraries	Everyone	Which libraries are visible, their order, and (for admins) custom libraries and access rules.	Users & Permissions
Security	Admin	Brute-force protection, IP allowlist, trusted proxies and CORS, public base URL, sessions, audit log, security-report email, ClamAV.	Network & Security
GOG	Admin	GOG connection and library-sync behaviour.	GOG Integration
Metadata	Admin	Scraper credentials (IGDB, RAWG, ScreenScraper, SteamGridDB) and metadata options.	Scrapers & Metadata
Downloads	Admin	Per-platform packaging, global and per-user speed limits, download tokens, Transmission.	Downloads & Torrents
ROMs	Admin	ROM scanning, base ROM path, cover-art preferences.	ROMs & Emulation
Notifications	Admin	SMTP server, email security alerts, and webhook templates (Discord, generic JSON).	Email & Notifications
Plugins	Admin	Install, enable/disable, configure, and remove plugins.	Plugin Development
Plugin Store	Admin	Browse and install plugins from configured store sources; update detection.	Plugin Development
Users	Admin	Create and manage users, assign roles, per-game access, view active sessions.	Users & Permissions

---

Infrastructure vs in-app settings

A natural question: why are the database password and the auth secret in .env, but the scraper keys and SMTP password in the UI? The dividing line is when the value is needed and how it is protected:

• .env values are needed to boot. The app cannot open its own database without DB_PASSWD, and cannot decrypt anything without GD_AUTH_SECRET_KEY. These must exist before the first line of application code runs, so they come from the environment. They live in plaintext in your .env file - keep that file readable only by you, and never commit it to a repository.
• In-app values are stored encrypted at rest. Everything you enter in Settings is written to the application database. Sensitive fields (scraper API keys, SMTP password, OAuth client secrets) are encrypted with a key derived from GD_AUTH_SECRET_KEY, so a stolen database dump does not hand over your credentials. This is why you should always set those in the UI rather than in .env.

Do not put scraper keys, SMTP passwords, or OAuth secrets in .env. The application does not read scraper credentials from environment variables at all, and storing any secret there keeps it in plaintext and visible to anyone who can run docker inspect. Use the relevant Settings tab instead. See the note under Metadata API keys on the Installation page.

---

Where your data lives

Everything persistent is stored under GD_BASE_DIR on the host (default ./data, i.e. a data/ folder next to your compose file). The complete layout:

Path	Contents
data/games/GOG	Published GOG game files
data/games/CUSTOM	Custom game files (uploaded, torrent, scanned)
data/games/roms/{platform}	ROM files per platform
data/downloads	GOG downloaded installers (pre-publish staging)
data/downloads/torrents	Torrent download staging area
data/resources/gog/{gog_id}	GOG game media (covers, backgrounds, screenshots, logos, icons)
data/resources/library/{game_id}	Custom Games library media (downloaded from external scrapers)
data/resources/roms/{platform}/{rom_id}	Per-ROM media (cover, hero, bezel, wheel, video, support art)
data/resources/roms/{platform}/{rom_id}/states/{user_id}	Save states, per user per ROM
data/resources/roms/{platform}/{rom_id}/saves/{user_id}	Battery saves (SRAM), per user per ROM
data/resources/avatars	User profile pictures
data/resources/platforms	Platform icons, name logos, fanart
data/config	App configuration and the auth secret (.secret_key)
data/config/launchbox_cache	LaunchBox SQLite index (built once, reused across restarts)
data/config/transmission	Transmission daemon config and logs
data/config/torrents	Generated .torrent files for library seeding
data/plugins	Installed plugins (each in its own subdirectory)
data/clamav	ClamAV virus definitions (~300 MB)
data/db	MariaDB data files
data/redis	Redis/Valkey persistence

---

Backups

You do not need to back up everything. Two directories are essential, the rest is re-downloadable:

• data/db - the database. Your entire library catalogue, users, settings, requests, and download history. Losing this means starting over.
• data/config - contains .secret_key. Without it, every session is invalidated and all encrypted-at-rest secrets (scraper keys, SMTP password, OAuth secrets) become unrecoverable, forcing you to re-enter them.

Everything else is bulky but replaceable:

• data/games and data/downloads are your actual game and ROM files - back these up if they are not stored elsewhere, but they are not part of the application state.
• data/resources (artwork) can be re-scraped.
• data/clamav re-downloads via freshclam.
• data/redis is a cache and is rebuilt automatically.

A simple approach for the critical state:

# Stop the stack for a consistent snapshot, then archive db + config
docker compose down
tar czf gd-backup-$(date +%F).tar.gz -C "$GD_BASE_DIR" data/db data/config
docker compose up -d

For a live (no-downtime) database backup, use mysqldump against the gd-mariadb container instead of stopping the stack.

---

Next: dive into a specific area - Scrapers & Metadata, Network & Security, or Email & Notifications.