diff --git a/README.md b/README.md
new file mode 100644
index 0000000..04d2fbe
--- /dev/null
+++ b/README.md
@@ -0,0 +1,44 @@
+# abstractnonsense/pages
+
+These are scripts that we use on [git.abstractnonsense.se][git]
+to have deployment to a [GitLab pages](gl-pages)-like environment.
+
+They are meant to be used in conjunction with [actions/pages][action-pages]
+to deploy to [pages.abstractnonsen.se][pages],
+but could be set up for any other domain.
+
+##  Requirements
+
+You need
+- a webserver with webroot
+- write-access to the webroot by some user
+- the ability to add ssh-keys to that user
+
+## Setup
+### initial setup
+We recommend a system-user that is solely used for the pages
+deployment. We will call it `pages` for the rest of this file.
+Create it with
+```
+sudo adduser --system --shell /bin/bash --gecos 'Pages deployment' --group --disabled-password --no-create-home pages
+```
+Copy `deploy.sh` to `/home/pages/deploy.sh` (or some other place where you want to store it).
+Edit the configuration variables in the file to your liking.
+Here, you have to ensure that the `pages` user has write access to `WEB_ROOT` and `STORAGE_ROOT`.
+Also make sure that `STORAGE_ROOT` has permissions so that other users cannot read it
+with `sudo chmod 600 <STORAGE_ROOT>`.
+
+### Settting up a new repository
+
+For each new repository, you want to do the following:
+Run `setup-key.sh <owner>/<repository>` to generate a ssh keypair and set up the `pages` user to accept this.
+Here, `<owner>/<repository>` can be anything, it will be the path relative to the webroot where this ssh key
+will be able to deploy to, but this would be the recommended pattern for git instances.
+
+In your repository, add the displayed ssh key as a secret named `PAGES_SSH_KEY`.
+Now you should be fine to use the action as described in [actions/pages][action-pages].
+
+[git]: https://git.abstractnonsen.se
+[gl-pages]: https://docs.gitlab.com/ee/user/project/pages/
+[action-pages]: https://git.abstractnonsen.se/actions/pages
+[pages]: https://pages.abstractnonsen.se