diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2589cb7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,96 @@
+# dcbot
+
+![img.png](docs/notifications.png)
+
+A minimalist Discord bot that sends notifications of gained/lost villages.
+
+## Getting started
+
+### Development
+
+#### Setting up the environment
+
+Prerequisites:
+
+1. **Go** (>= 1.19)
+2. **Node.js** (LTS, needed for commitlint)
+3. **Kubernetes** (>= 1.25.0)
+	1. **minikube**
+	2. **Docker Desktop**
+4. **Docker CLI**
+5. **Skaffold**
+6. **pre-commit**
+7. **IDE/Code editor** (e.g. Goland, VSCode, vim, neovim)
+8. **API** from [core](https://gitea.dwysokinski.me/twhelp/core)
+9. [**Bot token**](https://discord.com/developers/docs/topics/oauth2#bots)
+8. **direnv** (optional, but recommended)
+
+```shell
+# if you have direnv installed
+direnv allow
+
+# install git hooks and required tools
+make install
+
+# copy secret.example.yml
+cp ./k8s/overlays/dev/secret.example.yml ./k8s/overlays/dev/secret.yml
+# encode a bot token
+echo -n 'token' | base64
+# add the encoded token to secret.yml
+vim ./k8s/overlays/dev/secret.yml
+
+# run all required services
+skaffold run --port-forward=true --tail=true
+
+# stop all of them
+skaffold delete
+```
+
+#### Running unit tests
+
+At least one of the following is required to run unit tests:
+
+- Docker ([dockertest](https://github.com/ory/dockertest) will spin up a database)
+- Postgres database
+
+```shell
+# Docker
+go test -v ./...
+
+# Postgres database
+TESTS_DB_DSN=postgres://dcbot:dcbot_pass@127.0.0.1/dcbot go test -v ./... 
+```
+
+#### Creating a new database migration
+
+```shell
+# create a migration
+go run ./cmd/dcbot/main.go db create go migration 1
+```
+
+![img.png](docs/migration.png)
+
+## Configuration options
+
+Configuration options can be specified via environment variables.
+
+| Env variable                   | Default         | Description                                                                                                    |
+|--------------------------------|-----------------|----------------------------------------------------------------------------------------------------------------|
+| ``APP_MODE``                   | ``development`` | Whether to use development or production settings                                                              |
+| ``DB_DSN``                     |                 | **Required.** Syntax: ``postgres://user:password@host:5432/db?sslmode=disable``. Only Postgres is supported.   |
+| ``DB_MAX_OPEN_CONNECTIONS``    | ``5``           | Maximum number of open connections to the database (https://pkg.go.dev/database/sql#DB.SetMaxOpenConns)        |
+| ``DB_MAX_IDLE_CONNECTIONS``    | ``2``           | Maximum number of connections in the idle connection pool (https://pkg.go.dev/database/sql#DB.SetMaxIdleConns) |
+| ``DB_CONNECTION_MAX_LIFETIME`` | ``3m``          | Maximum amount of time a connection may be reused (https://pkg.go.dev/database/sql#DB.SetConnMaxLifetime)      |
+| ``TWHELP_URL``                 |                 | **Required.** API URL (e.g. https://tribalwarshelp.com)                                                        |
+| ``TWHELP_TIMEOUT``             | ``10s``         | Time limit for requests to TWHelp                                                                              |
+| ``BOT_TOKEN``                  |                 | **Required.** https://discord.com/developers/docs/topics/oauth2#bots                                           |
+| ``BOT_MAX_GROUPS_PER_SERVER``  | ``10``          | Max number of groups per server                                                                                |
+| ``BOT_MAX_MONITORS_PER_GROUP`` | ``10``          | Max number of monitors per group                                                                               |
+
+## License
+
+Distributed under the MIT License. See ``LICENSE`` for more information.
+
+## Contact
+
+Dawid Wysokiński - [contact@dwysokinski.me](mailto:contact@dwysokinski.me)
\ No newline at end of file
diff --git a/docs/migration.png b/docs/migration.png
new file mode 100644
index 0000000..10cdb92
Binary files /dev/null and b/docs/migration.png differ
diff --git a/docs/notifications.png b/docs/notifications.png
new file mode 100644
index 0000000..ce867c6
Binary files /dev/null and b/docs/notifications.png differ