Add documentation for bot and server configuration (#223)

* Create docs/ directory

* README: Update usage and deployment docs

* Add support for Python 3.9

* configure-guild.py: Set default notification level to only_mentions

* Update development documentation

* Document Pretix Mock content

* Fix pretix-mock endpoints

* pretix-mock: shut down properly

* Fix: Use actual name to greet user, not typed name

Author: NMertsch

README.md

@@ -18,13 +18,13 @@ The bot has the following extensions ("Cogs"):
 
 ## Screenshots
 ### Registration Channel:
-![Registration Channel](./img/registration-channel.png)
+![Registration Channel](docs/img/registration-channel.png)
 
 ### Registration Form:
-![Registration Form](./img/registration-form.png)
+![Registration Form](docs/img/registration-form.png)
 
 ### Programme Notification:
-![Programme Notification](./img/programme-notification.png)
+![Programme Notification](docs/img/programme-notification.png)
 
 ## Configuration
 
@@ -47,10 +47,12 @@ Cache files (will be created if necessary):
 * `pretix_cache.json`: Local cache of Pretix ticket data
 * `schedule_cache.json`: Local cache of [programapi](https://github.com/europython/programapi) schedule
 
-## Setup
-### Quickstart using `pip`
+## Usage
 
-If you just want to try the bot and skip the development setup, you can use `pip` (requires Python >= 3.11):
+This section describes how to install and run the bot.
+Please see below for development and EuroPython-specific deployment instructions.
+
+With pip:
 
 ```shell
 # create and activate virtual environment (optional, but recommended)
@@ -65,17 +67,65 @@ export DISCORD_BOT_TOKEN=...  # Windows: $env:DISCORD_BOT_TOKEN = '...'
 export PRETIX_TOKEN=...  # Windows: $env:PRETIX_TOKEN = '...'
 
 # run the bot with a given config file
-run-bot --config your-config-file.toml
+run-bot --config-file your-config-file.toml
+```
+
+With uv:
+
+```shell
+# install dependencies in virtual environment
+uv sync
+
+# set environment variables
+export DISCORD_BOT_TOKEN=...  # Windows: $env:DISCORD_BOT_TOKEN = '...'
+export PRETIX_TOKEN=...  # Windows: $env:PRETIX_TOKEN = '...'
+
+# run the bot with a given config file
+uv run run-bot --config-file your-config-file.toml
 ```
 
-### Full Development Setup
+## Development Setup
 
-* Install `uv` as documented [here](https://docs.astral.sh/uv/getting-started/installation/).
-* Run `uv sync --dev` to create/update a virtual environment with all dependencies according to [`uv.lock`](./uv.lock).
-* Run `. .venv/bin/activate` (Windows: `.venv/Scripts/activate`) to activate the virtual environment
+NOTE: This project uses [uv](https://docs.astral.sh/uv/) to manage Python versions and dependencies.
+  If you don't plan to add/remove/update dependencies, you can also use [pip](https://pip.pypa.io/en/stable/), and any Python version >= 3.9.
+
+### Discord Server and Bot Setup
+
+Follow [Discord Server and Bot Setup](docs/discord-server-bot-setup.md)
+if you don't yet have a Bot and Server for developing the bot.
+
+Expected outcome: You have a Discord Bot Token and can run a Discord Bot on a Discord Server.
+
+### Discord Server Configuration
+
+Follow [Discord Server Configuration](docs/discord-server-configuration.md)
+to configure your existing Discord Server with the expected channels, roles and messages.
+
+Expected outcome: A Discord Server ready to be used for this bot.
+
+### Pretix Integration
+
+This bot connects to a Pretix instance to obtain a list of valid tickets.
+
+Follow [Pretix Client Setup](docs/pretix-client-setup.md) to either connect to a real Pretix instance,
+or to use a mock.
+
+### Python environment setup
+
+* Using `uv`
+    * Install `uv` as documented [here](https://docs.astral.sh/uv/getting-started/installation/)
+    * Activate virtual environment: `. .venv/bin/activate` (macOS, Linux) or `.venv/Scripts/activate` (Windows)
+    * Run `uv sync --dev` to create/update a virtual environment with all dependencies according to [uv.lock](./uv.lock).
+* Using `pip`
+    * Create a virtual environment: `python3 -m venv .venv` (might require `apt install python3-venv` or similar on some systems)
+    * Activate virtual environment: `. .venv/bin/activate` (macOS, Linux) or `.venv/Scripts/activate` (Windows)
+    * Ensure `pip` version is >= 25.1.0: `python3 -m pip install --upgrade pip` (earlier versions don't support [PEP 735](https://peps.python.org/pep-0735/) Dependency Groups)
+    * Install all dependencies according to [pyproject.toml](pyproject.toml): `python3 -m pip install -e . --group dev`
 * Run `pre-commit install` to install the [pre-commit](https://pre-commit.com/) hooks.
 * Run `pre-commit run --all-files` to verify your setup. All checks should pass.
 
+### Run the bot
+
 To run the bot, use the following:
 
 ```shell
@@ -87,7 +137,7 @@ export PRETIX_TOKEN=...  # Windows: $env:PRETIX_TOKEN = '...'
 run-bot --config your-config-file.toml
 ```
 
-#### Working with `uv`
+### Working with `uv`
 
 This is a list of useful commands when working with `uv`.
 Please refer to the [uv documentation](https://docs.astral.sh/uv) or `uv help` for details.
@@ -123,15 +173,23 @@ uv remove [package]
 * Check code style: `ruff check .`
 * Run tests: `pytest`
 
-### Deployment
+## Deployment
 
-The bot is deployed on a VPS using a GitHub Action.
+For the EuroPython conference, this bot is deployed on a VPS.
 It uses Ansible to configure the VPS, and Docker Compose to run the bot.
+The deployment process is executed via a GitHub Action.
 
 Related files:
 
-* [.github/workflows/deploy.yml](./.github/workflows/deploy.yml): The GitHub Action
-* [ansible/deploy-playbook.yml](./ansible/deploy-playbook.yml): The Ansible Playbook
-* [Dockerfile](./Dockerfile): The Docker container recipe
-* [compose.yaml](./compose.yaml): The Docker Compose recipe
-* [prod-config.toml](./prod-config.toml): The Prod bot configuration
+* In this repository:
+    * [.github/workflows/deploy.yml](./.github/workflows/deploy.yml): GitHub Action
+    * [ansible/deploy-playbook.yml](./ansible/deploy-playbook.yml): Ansible Playbook
+    * [Dockerfile](./Dockerfile): Docker container recipe
+    * [compose.yaml](./compose.yaml): Docker Compose recipe
+    * [prod-config.toml](./prod-config.toml): Prod bot configuration
+* On the VPS:
+    * `/root/.secrets`: Contains `DISCORD_BOT_TOKEN` and `PRETIX_TOKEN`
+    * `/root/livestreams.toml`: Livestream URL configuration
+    * `/home/bot/registered_log.txt`: Registration log
+    * `/home/bot/pretix_cache.json`: Pretix cache
+    * `/home/bot/schedule_cache.json`: Program cache

docs/discord-server-bot-setup.md

@@ -0,0 +1,145 @@
+# Discord Server and Bot Setup
+
+Follow this guide to
+
+* Create a Discord Server
+* Create a Discord Bot
+* Connect the Bot to the Server
+
+NOTE: These steps require a Discord account with two-factor authentication enabled.
+
+## Create the Server
+
+In the left sidebar of the Discord Window, click the button "Add a Server":
+
+![Discord: Add a Server](img/add-server.png)
+
+Select "Create My Own":
+
+![Discord: Create My Own](img/create-my-own.png)
+
+Skip further questions:
+
+![Discord: Skip question](img/skip-question.png)
+
+Configure the server name and icon (can be updated later), then click "Create":
+
+![Discord: Server name and icon](img/server-name-and-icon.png)
+
+Congratulations, you now have your own Discord server.
+
+## Create a Bot
+
+Go to https://discord.com/developers/applications/ and log in.
+
+In the top-right corner, click "New Application".
+
+![Bot: New Application](img/new-application.png)
+
+Configure the application name (can be updated later), agree to the terms of service, and click "Create".
+
+![Bot: Create Application](img/create-application.png)
+
+In the left sidebar, go to "General Information" and configure the bot's icon and description (optional, can be updated later).
+
+![Bot: Icon and Description](img/bot-icon-and-description.png)
+
+Scroll down and configure the Terms of Service and Privacy Policy (optional, can be updated later).
+
+![Bot: ToS and Privacy Policy](img/bot-tos-privacy.png)
+
+In the left sidebar, go to "Installation".
+Remove the option "User install" and set the Install Link to "None".
+
+![Bot: Install configuration](img/bot-install-config.png)
+
+In the left sidebar, go to "Bot", then scroll down to "Privileged Gateway Intents".
+Activate "Server Member Intent" and "Message Content Intent".
+Click "Save Changes".
+
+![Bot: Configure Intents](img/configure-intents.png)
+
+In the left sidebar, go to "OAuth2".
+Select the scope "bot" and the permission "Administrator".
+
+![Bot: Scope and Permissions](img/bot-scopes-and-permissions.png)
+
+Scroll down, configure the integration type "Guild Install", and copy the URL.
+
+![Bot: Integration URL](img/bot-integration-url.png)
+
+Open the copied URL in a web browser. You will be prompted to open the Discord app.
+
+![Bot: Open in Discord](img/bot-open-in-discord.png)
+
+Proceed to add the bot to your server.
+
+![Bot: Add to Server](img/bot-add-to-server.png)
+
+Confirm the assigned permissions.
+
+![Bot: Confirm Permissions](img/bot-confirm-permissions.png)
+
+Congratulations, you created a bot and added it to a server.
+
+![Bot: Post-Installation Screen](img/bot-post-install-screen.png)
+
+## Use the Bot
+
+To use the bot from Python, you need an authorization token.
+
+Go back to https://discord.com/developers/applications/.
+In the left sidebar, go to "Bot", and click "Reset Token".
+
+![Bot: Reset Token](img/bot-reset-token.png)
+
+Confirm that step. This might require a two-factor authentication confirmation.
+
+![Bot: Confirm Token Reset](img/bot-confirm-token-reset.png)
+
+Copy your new token and store it somewhere safe.
+
+![Bot: Copy Token](img/bot-copy-token.png)
+
+To confirm the installation, install the Python package [discord.py](https://pypi.org/project/discord.py/)
+(e.g. with `pip install discord.py`), and run the following script (add your bot token at `BOT_TOKEN = "..."`):
+
+```python
+import asyncio
+
+import discord
+from discord.ext import commands
+
+BOT_TOKEN = "..."
+
+
+class Bot(commands.Bot):
+    async def on_ready(self):
+        print("ready", self.user.name, self.user.id)
+
+
+class Ping(commands.Cog):
+    @commands.hybrid_command(name="ping")
+    async def ping(self, context):
+        await context.send("Pong!")
+
+
+async def main():
+    prefix = commands.when_mentioned_or("$")
+
+    intents = discord.Intents(messages=True, message_content=True)
+    async with Bot(command_prefix=prefix, intents=intents) as bot:
+        await bot.add_cog(Ping())
+        await bot.start(BOT_TOKEN)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+In Discord, go to your server and write the message `$ping` in a text channel.
+The bot should respond with `Pong!`.
+
+![Bot: Ping Pong](img/bot-ping-pong.png)
+
+You can now stop the Python script by pressing Ctrl+C.

docs/discord-server-configuration.md

@@ -0,0 +1,38 @@
+# Discord Server Configuration
+
+Follow this guide to configure an existing Discord Server.
+
+NOTE: This guide requires you to run a Discord Bot on the Discord Server.
+
+## Remove Current Configuration (optional)
+
+If you are starting with a fresh Discord Server, it is recommended to delete all existing channels
+and categories.
+
+To delete a channel or category, right-click it, then left-click the "Delete" option.
+
+![Server: Delete Category](img/server-delete-category.png)
+
+Repeat this step until the server is empty.
+
+![Server: Empty Server](img/empty-server.png)
+
+NOTE: If you skip this step, the configuration script will still work and will not delete anything.
+
+Ensure that [discord.py](https://pypi.org/project/discord.py/) and [pydantic](https://pypi.org/project/pydantic) are installed.
+Set the environment variable `BOT_TOKEN` to your authorization token,
+then run the script [scripts/configure-guild.py](/scripts/configure-guild.py).
+
+```shell
+# macOS, Linux:
+export BOT_TOKEN="..."
+
+# Windows:
+$env:BOT_TOKEN = '...'
+
+python scripts/configure-guild.py --verbose
+```
+
+Your server should now be fully configured.
+
+![Server: Full Configuration](img/server-full-configuration.png)