diff --git a/README.md b/README.md
index 7db80e4..da0723e 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,115 @@
-# README
+# Sharedlists
 
-This README would normally document whatever steps are necessary to get the
-application up and running.
+[![Docker Status](https://img.shields.io/docker/build/foodcoops/sharedlists.svg)](https://hub.docker.com/r/foodcoops/sharedlists)
 
-Things you may want to cover:
+Sharedlists is a simple rails driven database for managing multiple product lists of various suppliers.
 
-* Ruby version
+This app is used in conjunction with [foodsoft](https://github.com/foodcoops/foodsoft).
+Recommended [Ruby](http://ruby-lang.org/) version is 2.3 (note that 2.4 does not work).
 
-* System dependencies
 
-* Configuration
+## Development
 
-* Database creation
+### Setup
 
-* Database initialization
+Copy `config/database.yml.SAMPLE` to `config/database.yml` and
 
-* How to run the test suite
+    docker-compose run --rm app bundle
+    docker-compose run --rm app rake db:setup
 
-* Services (job queues, cache servers, search engines, etc.)
+### Run
 
-* Deployment instructions
+    docker-compose up
 
-* ...
+### Creating a user
+
+To access sharedlists, you'll need to create a user (and I guess you want admin access).
+
+    docker-compose run --rm app rails c
+    > u = User.new(email: 'admin@example.com', password: 'secret')
+    > u.admin = true
+    > u.save!
+    > exit
+
+## Production
+
+Either fetch the image, or build it:
+
+    docker pull sharedlists:latest
+    # or
+    docker build --tag sharedlists:latest --rm .
+
+Then set environment variables `SECRET_TOKEN` and `DATABASE_URL` and run:
+
+    docker run --name sharedlists_web \
+      -e SECRET_TOKEN -e DATABASE_URL -e RAILS_FORCE_SSL=false \
+      sharedlists:latest
+
+To run cronjobs, start another instance:
+
+    docker run --name sharedlists_cron \
+      -e SECRET_TOKEN -e DATABASE_URL \
+      sharedlists:latest  ./proc-start cron
+
+If you want to process incoming mails, add another instance like the previous,
+substituting `mail` for `cron`.
+
+To put this all together, you may want to wrap this in docker-compose. See
+the [foodcoops.net setup](https://github.com/foodcoops/foodcoops.net/) for a real-world example.
+
+
+## Connecting Foodsoft
+
+To use shared suppliers from this sharedlists instance from within Foodsoft, you need
+to configure the [`shared_lists` option](https://github.com/foodcoops/foodsoft/blob/31689dfb75d203ab39405c313817e8c40e2cab36/config/app_config.yml.SAMPLE#L154)
+in its `config/app_config.yml`. Don't forget to grant the Foodsoft database user
+`SELECT` access on sharedlists' `suppliers` and `articles` tables.
+
+
+## Updating articles
+
+Articles in the database can be updated regularly. There are currently two options to
+do this automatically.
+
+### FTP
+
+Some suppliers distribute article lists via FTP. You can use the rake task
+called `sync_ftp_files` in order to download and parse those article
+lists. First, you need to enable FTP synchronization for a certain supplier by
+activating the checkbox _Synchronize FTP files_. Fill out all corresponding form
+fields. In particular, make sure to adjust the *file filter (regular
+expression)* such that it matches the files of interest; non-matching files are
+ignored. The two supported file formats and sensible choices for a corresponding
+*file filter* are shown in the following table.
+
+| file format                 | example file filter           |
+|-----------------------------|-------------------------------|
+| [BNN3][bnn3-format]         | `\A(?:[.]/)?PL.{0,6}[.]BNN\z` |
+| [foodsoft][foodsoft-format] | `\A(?:[.]/)?.+[.]csv\z`       |
+
+[bnn3-format]: https://github.com/foodcoops/foodsoft/wiki/File-formats-for-article-lists#user-content-format-bnn3
+[foodsoft-format]: https://github.com/foodcoops/foodsoft/wiki/File-formats-for-article-lists#user-content-format-foodsoft
+
+Once you have the `sync_ftp_files` task working, you may wish to setup a
+[cron](https://en.wikipedia.org/wiki/Cron)job using
+[`whenever`](https://github.com/javan/whenever).
+
+### Email
+
+Some suppliers send a regular email with an article list in the attachment. For this, an
+email server needs to be run using the rake task `mail:smtp_server`.
+On production, you may want to run this on localhost on an unprivileged port, with a
+proper [MTA](https://en.wikipedia.org/wiki/Message_transfer_agent) in front that
+does message routing.
+
+To enable this for a certain supplier, tick the checkbox _Update articles by email_. Then
+select a file format to use for importing, and the supplier's email address from which the
+email is sent. If you only want to import for mails with a subject that contains a certain
+text (e.g. _Articles in week_), fill in the subject field as well.
+
+What email address does the supplier need to send to? Users will find this after saving
+the supplier after _Send to_.
+
+This needs setting up of the environment variable `MAILER_DOMAIN`, on which you receive the
+emails. It is allowed to prefix the address, you may want to set the prefix in `MAILER_PREFIX`.
+This is useful when you're running an email server in front to route mails.