diff --git a/README.md b/README.md
new file mode 100644
index 00000000..33ed9781
--- /dev/null
+++ b/README.md
@@ -0,0 +1,136 @@
+# MirageOS Taler Exchange
+
+OCaml-based unikernel implementation of a GNU Taler exchange.
+
+# Implementation status
+
+MTE is still experimental and under development.
+
+Currently supported Exchange API endpoint (protocol version v31):
+- /terms
+- /privacy
+- /seed
+- /config
+- /management/*
+- /keys
+
+# Developement setup
+
+Because MTE compile to an unikernel, it requires to be given a TAP interface for network connectivity, and a file (formated to FAT) to use for cryptographic keys storage.
+It also require a connection to a PostgreSQL database.
+
+## Network
+
+We need to make a bridge device and asign it the `10.0.0.1` address, then attach a TAP device to it.
+To create the appropriate virtual network run `network.sh`.
+
+Be sure that your firewall (e.g. iptables) allows to reach the server and for the server and database to comunicate.
+
+## Database
+
+To setup PostgreSQL, first you will need to initialize a database cluster, create a user and a database.
+For that we recommand to follow the archlinuxwiki documentation `https://wiki.archlinux.org/title/PostgreSQL` .
+It is important to set the database username to 'mte' and the database name to 'taler-exchange', as those value 
+are hardcoded in setup scripts/config.
+
+PostgreSQL need to be configured to listen and accept connection at address `10.0.0.1` on port `5432` (same address as our virtual network bridge, this is for simplicity, as network configuration can be quite cubersome).
+Edit PostgreSQL's configuration file to allow that (PostgreSQL's configuration file location may vary depending on your system).
+
+```
+/var/lib/postgres/data/postgresql.conf
+
+listen_addresses = '10.0.0.1'
+```
+
+```
+/var/lib/postgres/data/pg_hba.conf
+
+# TYPE  DATABASE        USER            ADDRESS                 METHOD
+# IPv4 local connections:
+host    all             all             10.0.0.1/24           trust
+```
+
+You may need to restart PostgreSQL after configuration change, or if the bridge at `10.0.0.1` was not yet UP.
+
+Futhermore the database must be initialized (with sql tables, etc) before starting the server.
+We aim for database compatibility with GNU Taler exchange.
+To initialize the database use the `tools/dbinit.sh` script, it aggregates together the GNU Taler exchange's SQL files required to initialize the database and send commands to the PostgreSQL server with `psql`.
+(Or directly use a compatible version of GNU Taler Exchange's `taler-exchange-dbinit` tool)
+
+Prepare SQL queries and create the various elements (e.g. sql tables) required to be in the database.
+
+```
+./tools/dbinit fetch
+./tools/dbinit build
+./tools/dbinit init
+```
+
+## Dependencies
+
+MTE use the opam package manager and the dune build system.
+
+Create a dedicated opam switch, pin libraries to the required version and install them.
+
+```
+make setup-switch
+```
+
+For compilation to a solo5 unikernel, we also need to "vendor" some libraries.
+
+```
+make vendors
+```
+
+## Assets, configuration file and keys
+
+Create a `keys/` folder, generate a fresh master key for the server (and also a file with the required postgres_password to connect to the database).
+
+```
+make keys
+```
+
+Create `keys/secmod.fat` file that will be the FAT block storage given to MTE.
+MTE will use it to store it's signatures and denominations keys.
+
+```
+make secmod.fat
+```
+
+Create a `assets/` folder containing default terms of use files and a default configuration file.
+
+```
+make assets
+```
+
+Complete the configuration file by writing master public key of the server we previously generated into it.
+
+```
+make config
+```
+
+## Build and run
+
+Now everything should be in place to build and run MTE:
+
+```
+make build
+make run
+```
+
+Access the server on `http://10.0.0.2:3434/`
+
+# Tests
+
+Run tests with
+
+```
+dune runtest
+```
+
+This will run tests for various utility functions, binary formats and cryptographic functions.
+It also test that MTE's binary formats and cryptographic signature on the various fields of `/keys` API are consistent with the reference implementation.
+
+It is also possible to run a test scenario of the `/management` API with the `/test/management.sh` script.
+It uses `mte-offline-tool` executable to produce various keys, signatures and JSON objects used in the `/management` API.
+Note that this script assumes a server is already running at `http://10.0.0.2:3434`, and that it will write changes to the database.
+