diff --git a/README.md b/README.md
new file mode 100644
index 0000000..618baf1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,39 @@
+# prayertimes
+
+Prayer times and location search backed by Diyanet data, with an
+astronomical-calculation fallback when the upstream API is unavailable.
+
+## Running
+
+```bash
+go run .
+```
+
+Or via Docker (the image ships with a preseeded GeoNames cities database,
+no extra setup needed):
+
+```bash
+docker build -t prayertimes .
+docker run -p 8000:8000 prayertimes
+```
+
+### Environment variables
+
+| Variable  | Default                      | Description          |
+|-----------|-------------------------------|-----------------------|
+| `PORT`    | `8000`                        | HTTP listen port      |
+| `DB_PATH` | `./prayertimes.sqlite3`       | Path to the cities DB |
+
+## API
+
+Interactive API docs (Swagger UI) are served at `/api`, covering the
+current `/api/v1/*` endpoints. Older `/api/diyanet/*` endpoints are
+deprecated and intentionally left out of the docs.
+
+## Development
+
+Refresh the cities database from GeoNames:
+
+```bash
+python3 scripts/seed_cities.py --db ./prayertimes.sqlite3
+```