diff --git a/README.md b/README.md
index c63bf18..41e45b3 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,99 @@
 # gitea-auto-urls
+
+Automatically generates Traefik middleware to shorten Gitea repository URLs.
+
+## Purpose
+
+Removes the username from single-user Gitea instances: `https://git.pihkaal.xyz/pihkaal/repo-name` → `https://git.pihkaal.xyz/repo-name`.  
+Note that this will work only if you have a single user on Gitea, this is not meant to be used with multiple users. This projects is done based on my needs.
+
+## How it works
+
+1. Fetches all repositories from Gitea API
+2. Generates Traefik rewrite middleware using a template
+3. Outputs configuration to `/etc/traefik/dynamic/gitea-rewrites.yml`
+4. Traefik auto-reloads when the file changes
+
+## Quick start
+
+```shell
+$ pnpm build
+$ pnpm start
+```
+
+## Traefik Configuration
+
+Configure Traefik to watch the dynamic configuration directory:
+
+```yaml
+# add this to your traefik config to be able to put dynamic config in /etc/traefik/dynamic
+providers:
+  file:
+    directory: "/etc/traefik/dynamic"
+    watch: true
+```
+
+## Docker Setup
+
+You can add this to your gitea stack:
+
+```yaml
+services:
+  # ...
+  auto-urls:
+    image: git.pihkaal.xyz/pihkaal/gitea-auto-urls:latest
+    container_name: gitea-auto-urls
+    restart: always
+    environment:
+      - PORT=3000
+      - GITEA_URL
+      - GITEA_USERNAME
+      - GITEA_TOKEN
+      - GITEA_WEBHOOK_SECRET
+      - TEMPLATE_FILE=/config/gitea-rewrites.yml.in
+      - OUTPUT_FILE=/config/gitea-rewrites.yml
+    volumes:
+      - /etc/traefik/dynamic:/config
+    networks:
+      - gitea
+```
+
+## Configure in gitea
+
+### Create the token
+
+Navigate to `/user/settings/applications`, then click "Generate a new token". Only required permissions are `read:repository` and `read:user`.
+
+![](./assets/gitea-token-creation.png)
+
+### Create the webhook
+
+Navigate to `/user/settings/hooks`, then click "Add webhook".
+
+![](./assets/gitea-webhook-creation.png)
+
+In "Target URL", put the server address. If you use docker and added this service to your gitea stack, just put `http://container_name:PORT` (e.g `http://gitea-auto-urls:3000`).
+In "Secret", put the same secret you used for `GITEA_WEBHOOK_SECRET`. You can easily generate it using:
+
+```shell
+$ openssl rand -base64 32
+```
+
+Lastly, for the triggers select "Custom Events", then "Repository".
+
+And you're done, just hit "Add Webhook" and the service will start working.  
+The Gitea webhooks interface shows you the logs, so you can see here if it reached the service.
+
+## Template Format
+
+You can put anything in here, `{{REPOSITORIES}}` will be pipe-separated repos list (`repo-a|repo-b`) and `{{USERNAME}}` just contain `GITEA_USERNAME`.  
+Minimal config: (see `gitea-rewrites.yml.in`):
+
+```yaml
+http:
+  middlewares:
+    gitea-rewrites:
+      replacePathRegex:
+        regex: "^/({{REPOSITORIES}})(.*)$"
+        replacement: "/{{USERNAME}}/$1$2"
+```
diff --git a/assets/gitea-token-creation.png b/assets/gitea-token-creation.png
new file mode 100644
index 0000000..3b3893d
Binary files /dev/null and b/assets/gitea-token-creation.png differ
diff --git a/assets/gitea-webhook-creation.png b/assets/gitea-webhook-creation.png
new file mode 100644
index 0000000..24787c7
Binary files /dev/null and b/assets/gitea-webhook-creation.png differ