update docs

README.md

@@ -1,15 +1,89 @@
-# Net Neutrality Discord bot
+# Net Neutrality Discord Bot
 
-This is the source code for my custom discord bot.
-This is a personal project, so I offer no support on how to build it.
+A custom Discord bot written in Java. It uses [JDA](https://github.com/discord-jda/JDA) for Discord, a [Lavalink](https://github.com/lavalink-devs/Lavalink) node for music playback, MariaDB/MySQL for persistence, and exposes an HTTP API built with Javalin.
 
+This is a personal project. No support is offered for building or running it.
 
-The preferred method for running the bot is by using Docker Compose like this:
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Configuration](#configuration)
+- [Running with Docker Compose](#running-with-docker-compose)
+- [Running Locally](#running-locally)
+- [Testing](#testing)
+- [License](#license)
+
+## Requirements
+
+- Docker and Docker Compose (recommended), or
+- JDK 25 and Maven (the included `mvnw` wrapper works) for local runs
+- A MariaDB/MySQL database
+- A Lavalink node, version 4.2.0 or newer
+- A Discord bot token
+
+## Configuration
+
+All settings are provided as environment variables. A template with every supported variable is available in [`bot.properties.example`](bot.properties.example).
+
+Key variables:
+
+| Variable | Description |
+| --- | --- |
+| `NETNEUTRALITY_BOT_TOKEN` | Discord bot token |
+| `NETNEUTRALITY_BOT_PREFIX` | Command prefix |
+| `NETNEUTRALITY_BOT_OWNER` | Discord user ID of the bot owner |
+| `NETNEUTRALITY_API_PORT` | Port for the HTTP API (default `9000`) |
+| `MYSQL_HOST`, `MYSQL_PORT`, `MYSQL_USER`, `MYSQL_PASSWORD`, `MYSQL_DATABASE` | Database connection settings |
+| `NETNEUTRALITY_LAVALINK_URI`, `NETNEUTRALITY_LAVALINK_PASSWORD` | Lavalink connection settings |
+| `NETNEUTRALITY_SENTRY_DSN` | Optional Sentry DSN for error reporting |
+| `GITEA_HOST`, `GITEA_TOKEN`, `GITEA_OWNER`, `GITEA_REPO` | Optional Gitea settings for issue reporting |
+
+## Running with Docker Compose
+
+Docker Compose is the preferred way to run the bot. It starts the bot, the database, Lavalink, and the supporting YouTube cipher and PO token services.
+
+1. Copy `bot.properties.example` and fill in the values (see [Configuration](#configuration)).
+2. Build and start the stack:
 
 ```bash
 docker compose build
 docker compose up -d
 ```
 
-The environment variables needed for the bot to run are available in the file **bot.properties.example**
-If running locally without Docker, you need to copy the example file to **bot.properties** and fill the values.
+3. View logs:
+
+```bash
+docker compose logs -f netneutrality-bot
+```
+
+Logs are also written to the `logs` directory.
+
+## Running Locally
+
+1. Copy `bot.properties.example` to `bot.properties` and fill in the values.
+2. Make sure a database and a Lavalink node are reachable at the configured addresses.
+3. Build the project:
+
+```bash
+./mvnw package
+```
+
+4. Run the bot:
+
+```bash
+java -jar target/netneutrality.jar
+```
+
+Dependencies are copied to `target/lib` during packaging and referenced by the jar manifest.
+
+## Testing
+
+```bash
+./mvnw test
+```
+
+Database tests use Testcontainers, so Docker must be running. Checkstyle runs during the `test` phase.
+
+## License
+
+See the [LICENSE](LICENSE) file.