diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -13,33 +13,128 @@
 This uses docker with docker-compose, so ensure you have a working
 docker environment and docker-compose is installed.
 
-## How to use
+## Quick start
+
+First, start containers:
 
 ```
-docker-compose up
+~/swh-environment/swh-docker-dev$ docker-compose up -d
+[...]
+Creating swh-docker-dev_amqp_1               ... done
+Creating swh-docker-dev_zookeeper_1          ... done
+Creating swh-docker-dev_kafka_1              ... done
+Creating swh-docker-dev_flower_1             ... done
+Creating swh-docker-dev_swh-scheduler-db_1   ... done
+[...]
 ```
 
 This will build docker images and run them.
 
-Press Ctrl-C when you want to stop it.
+Check everything is running fine with:
+
+```
+~/swh-environment/swh-docker-dev$ docker-compose ps
+                         Name                                       Command               State                                      Ports
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+swh-docker-dev_amqp_1                                    docker-entrypoint.sh rabbi ...   Up      15671/tcp, 0.0.0.0:5018->15672/tcp, 25672/tcp, 4369/tcp, 5671/tcp, 5672/tcp
+swh-docker-dev_flower_1                                  flower --broker=amqp://gue ...   Up      0.0.0.0:5555->5555/tcp
+swh-docker-dev_kafka_1                                   start-kafka.sh                   Up      0.0.0.0:9092->9092/tcp
+swh-docker-dev_swh-deposit-db_1                          docker-entrypoint.sh postgres    Up      5432/tcp
+swh-docker-dev_swh-deposit_1                             /entrypoint.sh                   Up      0.0.0.0:5006->5006/tcp
+[...]
+```
+
+Note: if a container failed to start, it's status will be marked as `Exit 1`
+instead of `Up`. You can check why using the `docker-compose logs` command. For
+example:
+
+```
+~/swh-environment/swh-docker-dev$ docker-compose logs swh-lister-debian
+Attaching to swh-docker-dev_swh-lister-debian_1
+[...]
+swh-lister-debian_1                      | Processing /src/swh-scheduler
+swh-lister-debian_1                      | Could not install packages due to an EnvironmentError: [('/src/swh-scheduler/.hypothesis/unicodedata/8.0.0/charmap.json.gz', '/tmp/pip-req-build-pm7nsax3/.hypothesis/unicodedata/8.0.0/charmap.json.gz', "[Errno 13] Permission denied: '/src/swh-scheduler/.hypothesis/unicodedata/8.0.0/charmap.json.gz'")]
+swh-lister-debian_1                      |
+```
+
+Once all the containers are running, you can use the web interface by opening
+http://localhost:5080/ in your web browser.
+
+At this point, the archive is empty and needs to be filled with content. To do
+so, you can create tasks that will scrape a forge. For example, to inject the
+code from the https://0xacab.org gitlab forge:
+
+```
+$ ~/swh-environment/swh-docker-dev$ docker-compose run swh-scheduler-api \
+    swh-scheduler -c remote -u http://swh-scheduler-api:5008/ \
+	    task add swh-lister-gitlab-full -p oneshot api_baseurl=https://0xacab.org/api/v4
+
+Created 1 tasks
+
+Task 1
+  Next run: just now (2018-12-19 14:58:49+00:00)
+  Interval: 90 days, 0:00:00
+  Type: swh-lister-gitlab-full
+  Policy: oneshot
+  Args:
+  Keyword args:
+    api_baseurl=https://0xacab.org/api/v4
+```
+
+This task will scrape the forge's project list and create subtasks to inject
+each git repository found there.
 
-To run them in a detached (background) mode:
+This will take a bit af time to complete, but you can follow Celery activity on
+the flower instance: http://localhost:5080/flower/
+
+To increase the speed at wich git repositories are imported, you can spawn more
+`swh-loader-git` workers:
 
 ```
-docker-compose up -d
+~/swh-environment/swh-docker-dev$ export CELERY_BROKER_URL=amqp://:5072//
+~/swh-environment/swh-docker-dev$ celery status
+mercurial@8f63da914c26: OK
+debian@8a1c6ced237b: OK
+debian@d4be158f1759: OK
+pypi@41187053b90d: OK
+dir@52a19b9ba606: OK
+pypi@9be0cdcb484c: OK
+github@101d702d6e1d: OK
+bitbucket@1770d3b81da8: OK
+svn@9b2e473d466b: OK
+git@ae6ddafca382: OK
+tar@e17c0bc4392d: OK
+npm@ccfc73f73c4b: OK
+gitlab@280a937595f3: OK
+
+~/swh-environment/swh-docker-dev$ celery control pool_grow 3 -d git@ae6ddafca382
+-> git@ae6ddafca382: OK
+        pool will grow
+~/swh-environment/swh-docker-dev$ celery inspect -d git@ae6ddafca382 stats | grep prefetch_count
+       "prefetch_count": 4,
 ```
 
-To run only the objstorage API:
+Note: this later command assumes you have `celery` available on your host
+machine.
+
+Now there are 4 workers ingesting git repositories.
+You can also increase the number of `swh-loader-git` containers:
 
 ```
-docker-compose up swh-objstorage
+~/swh-environment/swh-docker-dev$ docker-compose up -d --scale swh-loader-git=4
+[...]
+Creating swh-docker-dev_swh-loader-git_2        ... done
+Creating swh-docker-dev_swh-loader-git_3        ... done
+Creating swh-docker-dev_swh-loader-git_4        ... done
 ```
 
+
 ### Install a package from sources
 
-It is possible to run a docker with some swh packages installed from sources
-instead of from pypi. To do this you must write a docker-compose override
-file. An example is given in docker-compose.override.yml.example:
+It is possible to run a docker container with some swh packages installed from
+sources instead of using lastest published packages from pypi. To do this you
+must write a docker-compose override file (`docker-compose.override.yml`). An
+example is given in the `docker-compose.override.yml.example` file:
 
 ```
 version: '2'
@@ -50,12 +145,12 @@
       - "/home/ddouard/src/swh-environment/swh-objstorage:/src/swh-objstorage"
 ```
 
-A file named docker-compose.override.yml will automatically be loaded by
-docker-compose.
+The file named `docker-compose.override.yml` will automatically be loaded by
+`docker-compose`.
 
-This example shows the simple case of the swh-objstorage package: you just have to
-mount it in the container in /src and the entrypoint will ensure every
-swh-* package found in /src/ is installed (using `pip install -e` so you can
+This example shows the simple case of the `swh-objstorage` package: you just have to
+mount it in the container in `/src` and the entrypoint will ensure every
+swh-* package found in `/src/` is installed (using `pip install -e` so you can
 easily hack your code. If the application you play with have autoreload support,
 there is even no need for restarting the impacted container.)
 
@@ -88,21 +183,82 @@
 
 That means, you can start doing the ingestion using those services
 using the same setup described in the getting-started starting
-directly at [1].  Yes, even browsing the web app!
+directly at [1].
 
 [1] https://docs.softwareheritage.org/devel/getting-started.html#step-4-ingest-repositories
 
+### Exposed Ports
 
-## Importing contents
+Several services have their listening ports exposed on the host:
 
+- amqp: 5072
+- kafka: 5092
+- nginx: 5080
+
+And for SWH services:
+
+- scheduler API: 5008
+- storage API: 5002
+- object storage API: 5003
+- indexer API: 5007
+- web app: 5004
+- deposit app: 5006
+
+Beware that these ports are not the same as the ports used from within the
+docker network. This means that the same command executed from the host or from
+a docker container will not use the same urls to access services. For example,
+to use the `celery` utility from the host, you may type:
+
+```
+~/swh-environment/swh-docker-dev$ CELERY_BROKER_URL=amqp://:5072// celery status
+dir@52a19b9ba606: OK
+[...]
+```
+
+To run the same command from within a container:
+
+```
+~/swh-environment/swh-docker-dev$ celery-compose exec swh-scheduler-api bash
+root@01dba49adf37:/# CELERY_BROKER_URL=amqp://amqp:5672// celery status
+dir@52a19b9ba606: OK
+[...]
+```
+
+## Managing tasks
+
+One of the main components of the Software Heritage platform is the task system.
+These are used to manage everything related to background process, like
+discovering new git repositories to import, ingesting them, checking a known
+repository is up to date, etc.
+
+The task system is based on Celery but uses a custom database-based scheduler.
+
+So when we refer to the term 'task', it may designate either a Celery task or a
+SWH one (ie. the entity in the database). When we refer to simply a "task" in
+the documentation, it designates the SWH task.
+
+When a SWH task is ready to be executed, a Celery task is created to handle the
+actual SWH task's job. Note that not all Celery tasks are directly linked to a
+SWH task (some SWH tasks are implemented using a Celery task that spawns Celery
+subtasks).
+
+A (SWH) task can be `recurring` or `oneshot`. `oneshot` tasks are only executed
+once, whereas `recurring` are regularly executed. The scheduling configuration
+of these recurring tasks can be set via the fields `current_interval` and
+`priority` (can be 'high', 'normal' or 'low') of the task database entity.
 
 
 ### Inserting a new lister task
 
-To list the content of a source code provider like github or the Debian
+To list the content of a source code provider like github or a Debian
 distribution, you may add a new task for this.
 
-This task should then spawn a series of loader tasks.
+This task will (generally) scrape a web page or use a public API to identify
+the list of published software artefacts (git repos, debian source packages,
+etc.)
+
+Then, for each repository, a new task will be created to ingest this repository
+and keep it up to date.
 
 For example, to add a (one shot) task that will list git repos on the
 0xacab.org gitlab instance, one can do (from this git repository):
@@ -202,8 +358,9 @@
 
 ### Monitoring activity
 
-You can monitor the workers activity by connecting to the RabbitMQ console
-on `http://localhost:5018`
+You can monitor the workers activity by connecting to the RabbitMQ console on
+`http://localhost:5002` or the Celery dashboard (flower) on
+`http://localhost:5003`.
 
 If you cannot see any task being in fact executed, check the logs of the
 `swh-scheduler-runner` service (here is an ecample of failure due to the