diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..f0cf661
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,23 @@
+# Copy this file to `.env` and fill in your real values.
+# `.env` is gitignored so your secrets stay local.
+
+# Your Discord bot token (Developer Portal -> your app -> Bot -> Reset/Copy Token).
+BOT_TOKEN=your-bot-token-here
+
+# Numeric ID of your test server, so /hello registers instantly as a guild command.
+# Enable Developer Mode in Discord, right-click the server, "Copy Server ID".
+# Leave unset to register /hello globally (can take up to an hour to appear).
+GUILD_ID=123456789012345678
+
+# Lavalink server the bot connects to for music playback.
+# In docker-compose the bot reaches Lavalink at ws://lavalink:2333 (set there);
+# ws://localhost:2333 is the default for running the bot outside a container.
+LAVALINK_URI=ws://localhost:2333
+# Shared secret between the bot and the Lavalink server. docker-compose passes
+# this same value to the server as LAVALINK_SERVER_PASSWORD, so the two always
+# match. Set a strong value — do NOT ship the youshallnotpass default.
+LAVALINK_PASSWORD=change-me
+
+# Path to the catchphrases file (one phrase per line). Optional; defaults to
+# catchphrases.txt in the working directory.
+CATCHPHRASES_FILE=catchphrases.txt
diff --git a/.gitignore b/.gitignore
index d02fbc8..635d1c7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -54,5 +54,7 @@ lavalink/plugins/
 ### Local secrets ###
 .env
 .env.*
+# ...but keep the committed template.
+!.env.example
 *.local
 secrets.properties
diff --git a/README.md b/README.md
index 37d1ce6..385e2f6 100644
--- a/README.md
+++ b/README.md
@@ -47,8 +47,8 @@ cp .env.example .env
 | --- | --- | --- |
 | `BOT_TOKEN` | ✅ | Discord bot token (Developer Portal → your app → Bot) |
 | `GUILD_ID` | optional | Test server ID for instant command registration. If unset, commands register globally (can take up to an hour) |
-| `LAVALINK_URI` | optional | Defaults to `ws://localhost:2333` (matches `docker-compose.yml`) |
-| `LAVALINK_PASSWORD` | optional | Defaults to `youshallnotpass` (matches `lavalink/application.yml`) |
+| `LAVALINK_URI` | optional | Defaults to `ws://localhost:2333` for local runs. In `docker-compose.yaml` the bot is pointed at `ws://lavalink:2333` (the service name) |
+| `LAVALINK_PASSWORD` | ✅ | Shared secret between the bot and the Lavalink server. Compose passes the same value to the server as `LAVALINK_SERVER_PASSWORD`, so they always match. The bot **exits** if it's unset |
 
 `.env` is gitignored, so your token stays local.
 
@@ -83,6 +83,33 @@ voice channel in your server and try `/play <song or url>`.
 - [ ] Run the bot: `./gradlew run`
 - [ ] In Discord, run `/hello` to confirm it responds, then `/play` from a voice channel
 
+## Run with Docker (prebuilt image)
+
+If you'd rather not build from source, `docker-compose.yaml` pulls the prebuilt
+bot image and runs it alongside Lavalink. You only need Docker — no JDK.
+
+1. Create your config and the files the bot reads at runtime, next to the compose file:
+
+   ```bash
+   cp .env.example .env        # then fill in BOT_TOKEN and LAVALINK_PASSWORD
+   ```
+
+   Make sure `catchphrases.txt`, `always100.txt`, and `always90.txt` exist as
+   **files** here. They're mounted into the container — if any is missing, Docker
+   creates an empty **directory** in its place and the mount breaks.
+
+2. Pull and start both services:
+
+   ```bash
+   docker compose pull        # fetch the bot + Lavalink images
+   docker compose up -d       # start in the background
+   docker compose logs -f     # watch logs; look for "Bot connected and ready as ..."
+   docker compose down        # stop
+   ```
+
+The bot connects to Lavalink over the internal Docker network automatically, so
+you don't set `LAVALINK_URI` yourself here.
+
 ## Notes
 
 - Queue state is kept in memory, so it resets if the bot restarts.