diff --git a/README.md b/README.md
index 054800572e086244d6e8c8fbd6ec84ad609baef4..14ef303aba06916ea515358d875e812b1cf65893 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,112 @@
-The CoreManager is a server component that acts as a front end to the VIPSCore system.
-The main tasks are authencication, authorization, scaling and logging of activities
-in the VIPSCore system. All requests to VIPSCore are routed through VIPSCoreManager.
\ No newline at end of file
+# VIPSCoreManager
+The CoreManager is a server component that acts as a frontend to the VIPSCore system.
+
+The main tasks of the manager are authencication, authorization, scaling and logging of activities in the VIPSCore system. All requests to VIPSCore are (or rather, may be) routed through VIPSCoreManager.
+
+![How VIPSCore and VIPSCoreManager fits into the whole VIPS architecture](./docs/illustrations/VIPS_whole_architecture.png "All VIPS system parts")
+
+Requests to and replies from VIPSCoreManager are identical to VIPSCore, except that you need to provide credentials as part of the request body.
+
+## Build and deploy
+
+### Database
+So make sure you have PostgreSQL >= 10 installed. As the db superuser (`postgres` on Ubuntu), create a user/role `vipscoremanager`. Then, initialize the database as in the example below:
+
+```sql
+--
+-- PostgreSQL database dump
+--
+
+-- Dumped from database version 14.4 (Ubuntu 14.4-0ubuntu0.22.04.1)
+-- Dumped by pg_dump version 14.4 (Ubuntu 14.4-0ubuntu0.22.04.1)
+
+SET statement_timeout = 0;
+SET lock_timeout = 0;
+SET idle_in_transaction_session_timeout = 0;
+SET client_encoding = 'UTF8';
+SET standard_conforming_strings = on;
+SELECT pg_catalog.set_config('search_path', '', false);
+SET check_function_bodies = false;
+SET xmloption = content;
+SET client_min_messages = warning;
+SET row_security = off;
+
+DROP DATABASE vipscoremanager;
+--
+-- Name: vipscoremanager; Type: DATABASE; Schema: -; Owner: vipscoremanager
+--
+
+CREATE DATABASE vipscoremanager WITH TEMPLATE = template0 ENCODING = 'UTF8' LOCALE = 'en_US.UTF-8';
+
+
+ALTER DATABASE vipscoremanager OWNER TO vipscoremanager;
+
+```
+
+### The code
+
+You need Maven installed.
+
+Clone and build the [VIPSCommon package](https://gitlab.nibio.no/VIPS/VIPSCommon)
+
+Clone and build this project
+
+Download and install [WildFly](https://www.wildfly.org/) >= 25.0.1
+
+Add the db credentials to Wildfly's configuration file `[WILDFLY_HOME]/standalone/configuration/standalone.xml`, e.g. like this:
+
+```xml
+<profile>
+    <!-- [...] -->
+    <subsystem xmlns="urn:jboss:domain:datasources:6.0">
+        <datasource jta="true" jndi-name="java:jboss/datasources/vipscoremanager" pool-name="Postgres-vipscoremanager-pool" enabled="true" use-java-context="true" use-ccm="true">
+            <connection-url>jdbc:postgresql://localhost:5432/vipscoremanager</connection-url>
+            <driver>postgresql</driver>
+            <security>
+                <user-name>vipscoremanager</user-name>
+                <password>foobar</password>
+            </security>
+        </datasource>
+        <drivers>
+        <!-- [...] -->
+        <driver name="postgresql" module="org.postgresql">
+            <driver-class>org.postgresql.Driver</driver-class>
+        </driver>
+        </drivers>
+    </subsystem>
+    <!-- [...] -->
+</profile>
+```
+
+Also, install the JDBC driver for PostgreSQL in `[WILDFLY_HOME]`/modules/ (See [Wildfly's class loading documentation](https://docs.wildfly.org/25/Developer_Guide.html#Class_Loading_in_WildFly))
+
+Deploy the build from this project in Wildfly. Wildfly should run on Java >= 11.
+
+### Configuration
+These system properties must be set in the WildFly config file `[WILDFLY_HOME]/standalone/configuration/standalone.xml`: 
+
+```xml
+<system-properties>
+        <property name="no.nibio.vips.coremanager.VIPSCORE_URL" value="http://localhost:8080/VIPSCore"/>
+        <property name="no.nibio.vips.coremanager.VIPSBATCH_ALLOWED_IPS" value="127.0.0.1"/>
+        <property name="no.nibio.vips.coremanager.MD5_SALT" value="FooBarFooBarFooBar"/>
+        <!-- [...] -->
+</system-properties>
+```
+Explanation of the properties:
+
+```properties
+# Where to find the VIPSCore service
+no.nibio.vips.coremanager.VIPSCORE_URL=http://localhost:8080/VIPSCore
+# From which IP adresses we accept batch operation requests
+no.nibio.vips.coremanager.VIPSBATCH_ALLOWED_IPS=127.0.0.1
+# Password hash salt
+no.nibio.vips.coremanager.MD5_SALT=FooBarFooBarFooBar
+```
+
+
+### Initialization
+The code includes database migrations by Flyway, so the database structure will be created automatically on the first successfull deployment.
+
+In order to use the service, you need to add at least one organization and at least one user. This is done by SQL directly in the database.
+
diff --git a/docs/illustrations/VIPS_whole_architecture.png b/docs/illustrations/VIPS_whole_architecture.png
new file mode 100644
index 0000000000000000000000000000000000000000..6b4f1d748bac1f713206b8204ce343a000883f02
Binary files /dev/null and b/docs/illustrations/VIPS_whole_architecture.png differ