From 1a4bfa53168b11ac90556d22653646480702f165 Mon Sep 17 00:00:00 2001
From: Brutus5000 <Brutus5000@gmx.net>
Date: Sun, 14 Oct 2018 15:02:09 +0200
Subject: [PATCH] Improve the readme

---
 README.md | 48 ++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 38 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 056c2a8d..cbf57a4e 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,19 @@
 # FAForever DB project
 
-Provides the Docker container and migration tools for a production-ready FAF database.
+This project contains the FAF database structure for the core faf database used by API and server. (Other databases like forums or wiki are not part of this repository.)
 
-## Creating a new database
-
-We highly recommended to use [faf-stack](https://github.com/FAForever/faf-stack) to create a new database container, like so:
+## Usage with faf-stack
+We highly recommended to use [faf-stack](https://github.com/FAForever/faf-stack) to interact with the database!
 
+### Creating a new database
     docker-compose up -d faf-db
 
-## Updating the database
-
+### Updating the database
 In order to update an existing database to the newest schema version, execute:
 
-    docker exec -ti faf-db ./migrate.sh
-
-## Connecting to the database
+    docker-compose run faf-db-migrations migrate
 
+### Connecting to the database
 In order to connect to the database using the mysql client, execute:
 
     docker exec -ti faf-db mysql -uroot -pbanana
@@ -23,5 +21,35 @@ In order to connect to the database using the mysql client, execute:
 Where you have to replace `root` and `banana` with your custom credentials.
 
 
+## Usage with plain docker
+
+### Create a network
+Create a network to connect the docker containers to each other. The old `--link` method is deprecated.
+
+    docker network create faf
+
+If you want to connect other docker containers to connect to the database, put them into the same network.
+
+### Creating a new database
+    docker run --network="faf" --network-alias="faf-db" -p 3306:3306 \
+               -e MYSQL_ROOT_PASSWORD=banana \
+               -e MYSQL_DATABASE=faf \
+               -d --name faf-db \
+               mysql:5.7
+
+### Updating the database
+In order to update an existing database to the newest schema version, execute:
+
+    docker run --network="faf" \
+               -e FLYWAY_URL=jdbc:mysql://faf-db/faf?useSSL=false \
+               -e FLYWAY_USER=root \
+               -e FLYWAY_PASSWORD=banana \
+               faf-db-migrations migrate
+
 ## How to Contribute
-https://github.com/FAForever/db/wiki/How-to-Contribute
+
+To make changes to the database, add a new .sql file to the migrations folder. Each file needs to have a unique version prefix and be one version higher than the latest one.
+
+For more information how the migration works please consult the [flyway tutorial](https://flywaydb.org/getstarted/how).
+
+Please also follow our [general contribution guidelines](https://github.com/FAForever/db/wiki/How-to-Contribute).