diff --git a/README.md b/README.md
index f6e141db8589c1dca076ae3d9fa1951e255958ac..5e451ab70525e7bb10f63d6a3b2e77fe77b037e0 100644
--- a/README.md
+++ b/README.md
@@ -119,3 +119,32 @@ deployment/wiki/webhook_secret
 ```
 
 On the server it lives at: `/opt/social.coop/wiki.social.coop/` and is running as the systemd service `wiki.social.coop.service`.
+
+## Mastodon upgrade notes
+
+- get current version from social.coop
+- find next version from mastodon github releases
+- check upgrade notes
+- we are on docker!
+- check whether there are DB migrations
+- make backup? `systemctl start pg-dump-to-s3.service`
+	- takes 15 mins or so?
+- separate command to see backup progress
+- make merge request on git.coop sauce repo to bump version in a couple of
+  places in docker-compose.yaml
+- `git diff v3.1.2..v3.1.3 -- docker-compose.yml` in mastodon repo after pulling
+  to check whether there were any changes we should consider mirroring to our
+  docker-compose file
+- could be cool to make these merge requests in advance
+- write a toot announcing upgrade and boost on admin account
+- touch file on server to activate maintenance mode
+- actually do the upgrade
+	- migration command creates a fresh web container and runs the migration
+	  command and then deletes that new container
+- turn maintenance mode off
+- we copy static assets outside of the container so they can be served by nginx
+	- there's a command for this which moves stuff into a temporary dir in nginx
+	  and pulls assets out of docker container into that folder in docker
+	  container
+- ssh forwarding is nice, then with `sudo -E -s` you have ssh access to stuff
+  you do from host machine(?)