[docs] info on db server configurations

docs/index.md

@@ -1,4 +1,4 @@
-# How to use the fish book
+# How to use the fishbook
 
 ## Requirements
 
@@ -31,32 +31,88 @@
   >> sudo pip3 install fishbook
   ```
 
-### 3) Connecting to the database
 
-#### Installing a local database
+### 3) Installing a local database server
 
 When you want to run *fishbook* locally you need to install a local database server (either mariaDB or mysql).
 
 On Ubuntu or Linux mint use *apt* to install the server
 
 ```bash
-sudo apt install mysql
+sudo apt update
+sudo apt install mariadb-server
+sudo mysql_secure_installation
 ```
 
 On Fedora use *dnf*
 
 ```bash
-sudo dnf install mysql
+sudo dnf update
+sudo dnf install mariadb-server
+sudo mysql_secure_installation
 ```
 
-On MacOS the most convenient way is to use [*homebrew*](https://brew.sh)
+On MacOS the most convenient way is to use [*homebrew*](https://brew.sh) see also [mariadb documentation](https://mariadb.com/kb/en/installing-mariadb-on-macos-using-homebrew/)
 
 ```bash
-brew install mysql
+brew install mariadb
+mysql.server start
+brew services start mariadb  # to automatically start the server upon boot
 ```
 
 On Windows you probably need to download an installer...
 
-#### Database connection
+Upon installation you should be able to log into the database as root without a password. 
+
+```bash
+mysql -u root 
+``` 
+
+To allow *datajoint* to store stuff on the server you need to:
+1. Create a database on the server.
+2. Add a user and grant this user read and write access.
+
+### Creating a database
+
+At the moment *fishbook* assumes that your database is called **fish_book**. To create it log into the server 
+
+```bash
+mysql -u root -p
+```
+
+And and execute the following commands
+
+```sql
+MariaDB [(none)]> CREATE DATABASE fish_book CHARACTER SET = utf8;
+MariaDB [(none)]> GRANT ALL ON fish_book.* TO 'foo'@'localhost' IDENTIFIED BY 'password';
+MariaDB [(none)]> FLUSH PRIVILEGES;
+```
+
+The first command creates the empty database and sets the Character set to utf8. This is important at least when it comes to *fishbook*. The second row creates a user **foo** and grants that user all rights on all tables of **fish_book**. So far **foo** can only log in from the local machine. In order to grant access also from outsides you need to issue a second command:
+
+```sql
+MariaDB [(none)]> GRANT ALL ON fish_book.* TO 'foo'@'%' IDENTIFIED BY 'password';
+MariaDB [(none)]> FLUSH PRIVILEGES;
+```
+
+From localhost you should now be able to log into the **fish_book** database by 
+
+```bash
+mysql fish_book -u foo -p
+```
+
+From outsides use
+
+```shell
+mysql fish_book -h yourhost.yourdomain -u foo -p
+```
+
+### Things to remember
+
+* Database engine must be InnoDB, which is default in MariaDB
+* **OperationalError: (1071, 'Specified key was too long; max key length is 3072 bytes')**
+Caused by a wrong character set check that it is set to utf8:
+```sql
+ALTER DATABASE `fish_book` CHARACTER SET utf8;
+```
 
-Suppose that you intend to work on a project named `foo` use the terminal to navigate to the project directory: `cd foo`