diff --git a/README.md b/README.md
index 8c351b7..1246abe 100644
--- a/README.md
+++ b/README.md
@@ -52,10 +52,18 @@ Please note that you will always need to install your own reverse proxy that
 terminates TLS for you and handles certificates. We do not support TLS directly
 in the application, instead, please use this prefered method. 
 
+Upgrading and migrating is descrube
+
 ### Migrating (Production)
 
-Migrations are not implemented yet. Once we need them, we'll add them and
-document the usage here.
+Migrations are done with
+[Alembic](https://alembic.sqlalchemy.org/en/latest/index.html), please refer to
+its documentation for help. Most of the time, running this command will do all
+the migrations you need:
+
+```bash
+docker-compose run --rm api alembic upgrade head
+```
 
 ### Upgrading from v0.2 to v0.3
 
@@ -165,8 +173,14 @@ testing.
 
 ### Migrating (Development)
 
-Migrations are not implemented yet. Once we need them, we'll add them and
-document the usage here.
+Migrations are done with
+[Alembic](https://alembic.sqlalchemy.org/en/latest/index.html), please refer to
+its documentation for help. Most of the time, running this command will do all
+the migrations you need:
+
+```bash
+docker-compose run --rm api alembic upgrade head
+```
 
 
 ## Import OpenStreetMap data
diff --git a/UPGRADING.md b/UPGRADING.md
index 486a412..a6dc86c 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -2,8 +2,16 @@
 
 This document describes the general steps to upgrade between major changes.
 Simple migrations, e.g. for adding schema changes, are not documented
-explicitly. Once we implement them, their usage will be described in the
-[README](./README.md).
+explicitly. Their general usage is described in the [README](./README.md) (for
+development) and [deployment/README.md](deployment/README.md) (for production).
+
+## 0.5.0
+
+* **Prepare SQL Tiles**: required
+* **OSM Import**: no
+* **Migration**: required
+* **Reimport tracks**: required
+* **Config changes**: none
 
 ## 0.4.1
 
diff --git a/deployment/README.md b/deployment/README.md
index e9e0e47..d4d96f4 100644
--- a/deployment/README.md
+++ b/deployment/README.md
@@ -367,6 +367,20 @@ docker-compose up -d
 Before updating make sure that you have properly backed-up your instance so you 
 can always roll back to a pre-update state.
 
+#### Migrating
+
+Migrations are done with
+[Alembic](https://alembic.sqlalchemy.org/en/latest/index.html), please refer to
+its documentation for help. Most of the time, running this command will do all
+the migrations you need:
+
+```bash
+docker-compose run --rm portal alembic upgrade head
+```
+
+You are advised to create a backup (see below) before running a migration, and
+to shut down the services before the migration and start them afterwards.
+
 ### Backups
 
 To backup your instances private data you only need to backup the ``$ROOT`` folder.