docs(MdBook): add MdBook for online rustmail documentation

Author: Akinator31

.github/workflows/docs.yml

@@ -0,0 +1,38 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: 'latest'
+
+      - name: Build documentation
+        run: mdbook build docs
+
+      - name: Setup SSH
+        uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.SSH_KEY }}
+
+      - name: Add known hosts
+        run: ssh-keyscan -H rustmail.rs >> ~/.ssh/known_hosts
+
+      - name: Deploy to server via rsync
+        run: |
+          rsync -avz --delete book/ ubuntu@rustmail.rs:/var/www/rustmail_docs/

.gitignore

@@ -9,4 +9,5 @@ node_modules
 package-lock.json
 bin
 rustmail/static
-rustmail_panel/dist
+rustmail_panel/dist
+/book/

docs/SUMMARY.md

@@ -0,0 +1,43 @@
+# Summary
+
+[Introduction](index.md)
+
+---
+
+# Getting Started
+
+- [Installation](getting-started/installation.md)
+- [Configuration](getting-started/configuration.md)
+- [First Steps](getting-started/first-steps.md)
+
+---
+
+# User Guides
+
+- [Commands](guides/commands.md)
+- [Server Modes](guides/server-modes.md)
+- [Tickets](guides/tickets.md)
+- [Web Panel](guides/panel.md)
+
+---
+
+# Deployment
+
+- [Docker](deployment/docker.md)
+- [Production](deployment/production.md)
+
+---
+
+# Reference
+
+- [Configuration Options](reference/configuration.md)
+- [REST API](reference/api.md)
+- [Database Schema](reference/database.md)
+
+---
+
+# Development
+
+- [Architecture](development/architecture.md)
+- [Building](development/building.md)
+- [Contributing](development/contributing.md)

docs/book.toml

@@ -0,0 +1,28 @@
+[book]
+title = "Rustmail Documentation"
+description = "Documentation for Rustmail, a Discord modmail bot"
+authors = ["Rustmail Team"]
+language = "en"
+src = "."
+
+[build]
+build-dir = "../book"
+
+[output.html]
+default-theme = "navy"
+preferred-dark-theme = "navy"
+git-repository-url = "https://github.com/Rustmail/rustmail"
+edit-url-template = "https://github.com/Rustmail/rustmail/edit/main/docs/{path}"
+site-url = "/"
+
+[output.html.fold]
+enable = true
+level = 1
+
+[output.html.search]
+enable = true
+limit-results = 20
+boost-hierarchy = 2
+
+[output.html.playground]
+editable = false

docs/deployment/docker.md

@@ -304,6 +304,40 @@ Common issues:
 - Missing required configuration fields
 - Permission issues on mounted volumes
 
+### Container Stops After "Database connected!"
+
+If logs only show:
+```
+Database connection pool established
+Database connected!
+```
+
+The bot cannot load `config.toml`. The most common cause is an incorrect volume mount:
+
+```bash
+# WRONG - relative path creates a directory instead of mounting the file
+docker run -v config.toml:/app/config.toml ...
+
+# CORRECT - use absolute path
+docker run -v $(pwd)/config.toml:/app/config.toml ...
+docker run -v /home/user/rustmail/config.toml:/app/config.toml ...
+```
+
+Verify the mount is correct:
+```bash
+# Should show a file, not a directory
+docker exec rustmail ls -la /app/config.toml
+
+# Should display your config content
+docker exec rustmail cat /app/config.toml
+```
+
+If `/app/config.toml` is a directory, remove the container and recreate with the correct path:
+```bash
+docker rm -f rustmail
+docker run -d --name rustmail -v $(pwd)/config.toml:/app/config.toml:ro ...
+```
+
 ### Cannot Connect to Panel
 
 - Verify port 3002 is exposed: `docker port rustmail`

docs/getting-started/configuration.md

@@ -10,7 +10,8 @@ The easiest way to create your configuration is the online generator:
 
 **[config.rustmail.rs](https://config.rustmail.rs)**
 
-The generator walks you through each setting and produces a valid `config.toml` file. You can also build the configurator locally from the [rustmail_configurator](https://github.com/Rustmail/rustmail_configurator) repository.
+The generator walks you through each setting and produces a valid `config.toml` file. You can also build the
+configurator locally from the [rustmail_configurator](https://github.com/Rustmail/rustmail_configurator) repository.
 
 ---
 
@@ -22,7 +23,8 @@ If you prefer to create the configuration manually, copy `config.example.toml` a
 cp config.example.toml config.toml
 ```
 
-Below is an overview of each configuration section. For a complete reference of all options, see [Configuration Reference](../reference/configuration.md).
+Below is an overview of each configuration section. For a complete reference of all options,
+see [Configuration Reference](../reference/configuration.md).
 
 ---
 
@@ -67,6 +69,7 @@ staff_guild_id = 987654321098765432
 ```
 
 In dual-server mode:
+
 - `community_guild_id` is where your users are
 - `staff_guild_id` is where ticket channels are created
 
@@ -82,7 +85,8 @@ user_message_color = "3d54ff"
 staff_message_color = "ff3126"
 ```
 
-The `inbox_category_id` is required. Create a category in your staff server (or your single server) and copy its ID. All ticket channels will be created under this category.
+The `inbox_category_id` is required. Create a category in your staff server (or your single server) and copy its ID. All
+ticket channels will be created under this category.
 
 ---
 
@@ -105,45 +109,73 @@ client_secret = "your_oauth2_client_secret"
 redirect_url = "http://localhost:3002/api/auth/callback"
 ```
 
-### Understanding the Redirect URL
+### Understanding redirect_url vs ip
+
+These two fields serve different purposes and are often confused:
+
+| Field          | Purpose                                            | Required                     |
+|----------------|----------------------------------------------------|------------------------------|
+| `redirect_url` | Public URL for OAuth2 authentication and log links | **Yes** (if panel enabled)   |
+| `ip`           | Network interface binding address                  | No (defaults to auto-detect) |
+
+### The redirect_url Field (Important)
 
-The `redirect_url` is where Discord sends users after they authenticate. It must:
+The `redirect_url` is **your panel's public URL**. It is used for:
 
-1. Match exactly what you configured in the Discord Developer Portal
-2. Point to your bot's `/api/auth/callback` endpoint
+1. **OAuth2 authentication** - Discord redirects users here after login
+2. **Log links** - Links to ticket logs sent in your logs channel
+
+It must:
+
+- Match **exactly** what you configured in the Discord Developer Portal
+- End with `/api/auth/callback`
+- Be accessible from the internet (or your network for local use)
 
 **Local development:**
+
 ```toml
 redirect_url = "http://localhost:3002/api/auth/callback"
 ```
 
-**Production with domain:**
+**Production with domain (behind reverse proxy):**
+
 ```toml
 redirect_url = "https://panel.example.com/api/auth/callback"
 ```
 
-### The IP Field
+**LAN access (no domain):**
+
+```toml
+redirect_url = "http://192.168.1.100:3002/api/auth/callback"
+```
+
+### The ip Field (Optional)
 
 ```toml
 [bot]
 ip = "192.168.1.100"  # Optional
 ```
 
-The `ip` field controls what address the panel shows for direct access. If omitted, Rustmail auto-detects your local IP address.
+The `ip` field controls which **network interface** the panel server binds to. This is a technical setting for advanced
+network configurations.
+
+- If omitted, Rustmail auto-detects your local IP
+- If the IP is invalid or unavailable, it falls back to `0.0.0.0` (all interfaces)
 
 **When to set it manually:**
 
-- Running in Docker with specific network configuration
+- Running in Docker with host networking
 - When auto-detection returns an incorrect interface
-- When you want to display a specific LAN address
+- When you need to bind to a specific network interface
 
-**Note:** This field is cosmetic for the panel URL display. It does not affect where the server binds (the bot always listens on `0.0.0.0:3002`).
+**For most users:** Leave `ip` unset and focus on configuring `redirect_url` correctly.
 
 ---
 
 ## Reverse Proxy Setup
 
-For production deployments, you typically run Rustmail behind a reverse proxy (Nginx, Caddy, Traefik, NPM, etc.) with a custom domain.
+For production deployments, you typically run Rustmail behind a reverse proxy (Nginx, Caddy, Traefik, NPM, etc.) with a
+custom domain.
 
 ### Architecture
 
@@ -157,11 +189,11 @@ Internet → Reverse Proxy (443) → Rustmail (3002)
 ### Nginx Proxy Manager (NPM)
 
 1. **Add Proxy Host:**
-   - Domain: `panel.example.com`
-   - Scheme: `http`
-   - Forward Hostname/IP: Your server's internal IP or `localhost`
-   - Forward Port: `3002`
-   - Enable SSL with Let's Encrypt
+    - Domain: `panel.example.com`
+    - Scheme: `http`
+    - Forward Hostname/IP: Your server's internal IP or `localhost`
+    - Forward Port: `3002`
+    - Enable SSL with Let's Encrypt
 
 2. **Configure Rustmail:**
    ```toml
@@ -171,7 +203,7 @@ Internet → Reverse Proxy (443) → Rustmail (3002)
    ```
 
 3. **Update Discord OAuth2:**
-   - Add `https://panel.example.com/api/auth/callback` to your redirect URIs
+    - Add `https://panel.example.com/api/auth/callback` to your redirect URIs
 
 ### Nginx Configuration
 
@@ -216,11 +248,13 @@ labels:
 
 **OAuth2 redirect mismatch:**
 The redirect URL in `config.toml` must exactly match one of the URLs configured in Discord Developer Portal. Check for:
+
 - Protocol mismatch (`http` vs `https`)
 - Trailing slashes
 - Port numbers
 
 **Panel not accessible:**
+
 - Verify the reverse proxy can reach port 3002
 - Check firewall rules
 - Ensure Rustmail is running and panel is enabled
@@ -240,7 +274,8 @@ panel_super_admin_roles = [987654321098765432]
 - `panel_super_admin_users` - List of Discord user IDs
 - `panel_super_admin_roles` - List of Discord role IDs
 
-Users matching either list have unrestricted panel access. Additional permissions can be granted through the panel itself.
+Users matching either list have unrestricted panel access. Additional permissions can be granted through the panel
+itself.
 
 ---
 

docs/getting-started/installation.md

@@ -15,8 +15,9 @@ Before installing Rustmail, create a Discord application:
 3. Navigate to **Bot** in the sidebar
 4. Click **Add Bot**
 5. Under **Privileged Gateway Intents**, enable:
-   - **Server Members Intent**
-   - **Message Content Intent**
+    - **Presence Intent**
+    - **Server Members Intent**
+    - **Message Content Intent**
 6. Copy the bot token (you will need it for configuration)
 
 ### Bot Invitation
@@ -26,15 +27,15 @@ Invite the bot to your server(s) with the required permissions:
 1. Go to **OAuth2 > URL Generator**
 2. Select scopes: `bot`, `applications.commands`
 3. Select permissions:
-   - Manage Channels
-   - Read Messages/View Channels
-   - Send Messages
-   - Manage Messages
-   - Embed Links
-   - Attach Files
-   - Read Message History
-   - Add Reactions
-   - Use Slash Commands
+    - Manage Channels
+    - Read Messages/View Channels
+    - Send Messages
+    - Manage Messages
+    - Embed Links
+    - Attach Files
+    - Read Message History
+    - Add Reactions
+    - Use Slash Commands
 4. Copy the generated URL and open it in your browser
 5. Select your server and authorize
 
@@ -49,6 +50,7 @@ For dual-server mode, invite the bot to both servers.
 Download the latest release from [GitHub Releases](https://github.com/Rustmail/rustmail/releases).
 
 Available platforms:
+
 - Linux (x86_64)
 - Windows (x86_64)
 - macOS (x86_64, ARM64)
@@ -87,7 +89,8 @@ On first run, the bot creates:
 rustmail/
 ├── rustmail
 ├── config.toml
-└── db.sqlite         # SQLite database (auto-created)
+└── db
+    └── db.sqlite # SQLite database (auto-created)
 ```
 
 ---