diff --git a/README.md b/README.md
index 65c0cb59eb10f5bcacfed44dd120763831370ba9..e41c0f2e135137f46bd2b4cbbfb10328c2a0aad7 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,30 @@
 # python-infodisplay
 
-## Intent
+## Getting started
 
-This project is intended to replace the existing infodisplay tech stack.
\ No newline at end of file
+Install required python libraries, e.g.
+
+```
+pip install -r requirements.txt
+```
+
+Set required environment variables in a sensible way.
+
+```
+# API access token for homeassistant.s0
+HOMEASSISTANT_TOKEN=
+# Matrix API token for chat.stratum0.org
+MATRIX_TOKEN=
+# If necessary, force IPv4-only connections
+IP_MODE=legacy
+```
+
+Then, start the server and open http://localhost:8888
+
+```
+python3 index.py
+```
+
+## Structure of the application
+
+Every widget on the infodisplay is rendered into Jinja templates by a handler residing in `handlers`. The `index.htm` uses HTMX to reload each widget independently on different timers. Handlers using external data sources use the `@cached` decorator to avoid frequent requests to their respective upstream services.