docs(configuration): add Valkey cache options and clarify bot owner setup

- Introduced Valkey as an optional cache backend for persistent state across restarts, with detailed configuration instructions.
- Updated documentation to specify that bot owner ID and sysadmins should be set in `config/config.json` instead of `.env`.
- Enhanced Docker installation guide to include Valkey setup and usage instructions for shared caching.

Author: kzndotsh

docs/content/selfhost/config/bot-token.md

@@ -45,16 +45,15 @@ Quick guide to get your Discord bot token configured for Tux.
 
 ## Environment Setup
 
-Add to your `.env` file:
+Add your bot token to `.env`:
 
 ```env
 # Required: Your Discord bot token
 BOT_TOKEN=your_bot_token_here
-
-# Optional: Bot owner Discord user ID (for admin commands)
-USER_IDS__BOT_OWNER_ID=your_discord_user_id_here
 ```
 
+Set **bot owner ID** (and optional sysadmins) in **`config/config.json`**, not in `.env`. See [Self-Host Configuration](index.md) for the JSON structure.
+
 !!! important "Keep Tokens Secret"
     - Never share your token
     - Don't commit it to version control

docs/content/selfhost/config/environment.md

@@ -47,13 +47,47 @@ POSTGRES_PASSWORD=your_secure_password
 
 See [Database Configuration](database.md) for setup.
 
-### Bot owner (recommended)
+### Optional: Valkey (cache)
+
+Valkey (Redis-compatible) is an **optional** cache backend. When configured, Tux uses it for
+guild config, jail status, prefix, and permission caches so state can be shared across
+restarts or multiple processes. When Valkey is not set or unavailable, Tux uses an
+in-memory cache (no extra service required).
+
+Use either **VALKEY_URL** or **individual variables**:
 
 ```env
-USER_IDS__BOT_OWNER_ID=123456789012345678
+# Option A: URL (overrides VALKEY_HOST/PORT/DB/PASSWORD)
+VALKEY_URL=valkey://localhost:6379/0
+
+# Option B: Individual (e.g. for Docker with tux-valkey)
+VALKEY_HOST=tux-valkey
+VALKEY_PORT=6379
+VALKEY_DB=0
+VALKEY_PASSWORD=
+```
+
+Leave `VALKEY_URL` and `VALKEY_HOST` empty to disable Valkey. See the
+[ENV Reference](../../reference/env.md) for all Valkey variables.
+
+!!! note "When to use Valkey"
+    Use Valkey if you want cache to persist across bot restarts or run multiple Tux
+    processes. For a single instance that restarts rarely, in-memory cache is sufficient.
+
+### Bot owner and sysadmins (recommended)
+
+Configure in **`config/config.json`**, not in `.env`:
+
+```json
+{
+  "USER_IDS": {
+    "BOT_OWNER_ID": 123456789012345678,
+    "SYSADMINS": [123456789012345678, 987654321098765432]
+  }
+}
 ```
 
-Enables owner-only commands and maintenance control. [ENV Reference](../../reference/env.md) documents `USER_IDS__SYSADMINS` and other IDs.
+Enables owner-only commands and maintenance control. See [Self-Host Configuration](index.md) for the full JSON layout and `uv run config generate` for an example file.
 
 ## Docker
 

docs/content/selfhost/config/index.md

@@ -48,6 +48,7 @@ Complete guide to environment variable configuration, including:
 
 - Configuration priority and loading order
 - Essential variables
+- Optional Valkey (cache) backend
 - Docker-specific configuration
 - Validation and testing
 
@@ -67,12 +68,15 @@ POSTGRES_PASSWORD=your_secure_password_here
 # Optional
 LOG_LEVEL=INFO
 DEBUG=false
-USER_IDS__BOT_OWNER_ID=123456789012345678
 ```
 
+!!! note "Bot owner, sysadmins, prefix"
+    Set `USER_IDS.BOT_OWNER_ID`, `USER_IDS.SYSADMINS`, and `BOT_INFO.PREFIX` in
+    `config/config.json`, not in `.env`. See the JSON example below.
+
 ### `config/config.json`
 
-JSON configuration file for structured settings:
+JSON configuration file for structured settings (bot owner, sysadmins, prefix, intents, etc.):
 
 ```json
 {
@@ -84,6 +88,10 @@ JSON configuration file for structured settings:
     "presences": true,
     "members": true,
     "message_content": true
+  },
+  "USER_IDS": {
+    "BOT_OWNER_ID": 123456789012345678,
+    "SYSADMINS": [123456789012345678, 987654321098765432]
   }
 }
 ```
@@ -154,6 +162,21 @@ All three privileged intents are required for full functionality:
 - **members**: Required for on_member_join, jail, tty_roles
 - **message_content**: Required for prefix commands and most features
 
+### Enable optional Valkey cache
+
+To use Valkey (Redis-compatible) for shared cache across restarts:
+
+```env
+# With Docker (start tux-valkey with --profile valkey)
+VALKEY_HOST=tux-valkey
+VALKEY_PORT=6379
+
+# Or use a URL
+VALKEY_URL=valkey://localhost:6379/0
+```
+
+Leave Valkey unset to use in-memory cache. See [Environment Configuration](environment.md#optional-valkey-cache).
+
 ### Set Log Level
 
 ```env

docs/content/selfhost/index.md

@@ -44,6 +44,14 @@ These are the system requirements needed to install and run Tux.
 !!! tip "Tip"
     If you don't want to manage the database yourself, consider using a managed PostgreSQL service such as [Supabase](https://supabase.com/).
 
+#### Optional: Valkey (cache)
+
+- **Valkey** (Redis-compatible): Optional. When configured, Tux uses it for guild config,
+  jail status, prefix, and permission caches so state can persist across restarts.
+  When not set, Tux uses in-memory cache. See
+  [Environment Configuration](config/environment.md#optional-valkey-cache) and
+  [Docker Installation](install/docker.md#valkey-optional-cache).
+
 ### Discord Bot Requirements
 
 - **Bot Token**: Read [our guide](./config/bot-token.md) on obtaining a bot token.

docs/content/selfhost/install/docker.md

@@ -86,10 +86,6 @@ POSTGRES_USER=tuxuser
 POSTGRES_PASSWORD=your_secure_password_here
 POSTGRES_PORT=5432
 
-# Optional: Bot Configuration
-USER_IDS__BOT_OWNER_ID=123456789012345678
-BOT_INFO__PREFIX=$
-
 # Optional: Logging
 LOG_LEVEL=INFO
 DEBUG=false
@@ -130,8 +126,9 @@ Profiles work as in [Docker Compose](https://docs.docker.com/compose/how-tos/pro
 
 The Docker Compose setup includes:
 
-- **tux-postgres** - PostgreSQL database
-- **tux** (production) or **tux-dev** (development) - Tux Discord bot
+- **tux-postgres** - PostgreSQL database (no profile; always started with Tux)
+- **tux** (production) or **tux-dev** (development) - Tux Discord bot; use `--profile production` or `--profile dev`
+- **tux-valkey** (optional) - Valkey cache for shared cache across restarts; use `--profile valkey`
 - **tux-adminer** (optional) - Database management UI at `http://localhost:8080`; use `--profile adminer`
 
 ## Services Overview
@@ -172,6 +169,30 @@ docker compose --profile production --profile adminer up -d
 
 Omit `--profile adminer` to run without Adminer.
 
+### Valkey (optional cache)
+
+Valkey provides a shared cache (guild config, jail status, prefix, permissions) that
+persists across bot restarts. Without it, Tux uses in-memory cache (no extra container).
+
+To use Valkey with Docker:
+
+1. Start Valkey with the `valkey` profile:
+
+   ```bash
+   docker compose --profile dev --profile valkey up -d
+   # or
+   docker compose --profile production --profile valkey up -d
+   ```
+
+2. Set the Valkey host in `.env` so Tux can connect:
+
+   ```env
+   VALKEY_HOST=tux-valkey
+   VALKEY_PORT=6379
+   ```
+
+Omit `--profile valkey` and leave `VALKEY_HOST` empty to run without Valkey.
+
 ## Configuration
 
 ### Environment Variables
@@ -188,14 +209,16 @@ POSTGRES_USER=tuxuser
 POSTGRES_PASSWORD=your_secure_password_here
 POSTGRES_PORT=5432
 
-# Bot Configuration
-USER_IDS__BOT_OWNER_ID=123456789012345678
-BOT_INFO__PREFIX=$
+# Bot owner, sysadmins, prefix: set in config/config.json; see [Configuration](../config/index.md)
 
 # Logging
 LOG_LEVEL=INFO
 DEBUG=false
 
+# Optional: Valkey (use with --profile valkey)
+VALKEY_HOST=tux-valkey
+VALKEY_PORT=6379
+
 # Optional: External Services
 EXTERNAL_SERVICES__SENTRY_DSN=https://[email protected]/project-id
 ```