tools-compose/README.md

# Tools compose
Docker compose sources to start planete-casio's wiki and tools


## Volumes

The wiki is the only statefull tool of this setup. All the data will be stored in volumes that will be in the `volumes` directory.

* `mariadb-wiki` : This is the raw storage of the db. Don't delete this. Avoid copying this between mysql versions, use SQL dumps instead.
* `wiki-fr-images` and `wiki-en-images` : Upload storages of the wiki. You have to restore this if you restore the db. It also contains some image caches.
* `wiki-fr-cache` and `wiki-en-caches` : This is a cache used by the wiki to avoid recomputing all pages for all users. You can safely delete this volume.

## Deployment

First, install the last version of [docker](https://docs.docker.com/install/) and [docker-compose](https://docs.docker.com/compose/install/) on the server.

### Clone the repo

Then clone this repository onto the server, cd into it and pull submodules

```
# Put this somewhere only root can access, you weel need to keep this directory for production
sudo su
cd /srv/
git clone https://gitea.planet-casio.com/devs/tools-compose
cd tools-compose

# Enable git credential cache because there is multiple submodules that need your password multiple times
git config --global credential.helper cache

# Now init an pull submodules
git submodule init
git submodule update
```

### Configuration

The docker-compose configuration is stored into a `.env` file at the root of the repository. You need to copy the `.env.example` file into `.env` and fill it with a valid configuration.

```
cp .env.example .env
# Then edit .env
```

The following keys are required:

* `WIKI_BASE_URI`: Wiki base uri with protocol, hostname and port. For instance `https://wiki.planet-casio.com` or `http://wiki.local:8080`
* `WIKI_EN_SECRET_KEY` and `WIKI_FR_SECRET_KEY`: [Secret key](https://www.mediawiki.org/wiki/Manual:$wgSecretKey) of the wiki. Should be a 64-character random string.
* `WIKI_DB_ROOT_PASSWORD`: Password of the `root` user on the database that can, for instance, create other users on the DB.
* `WIKI_DB_WIKI_PASSWORD`: Password of the `wiki` user on the database. This account is used by the application and can only edit the `wiki` database.
* `HTTP_BIND`: Port and address on which we will bind the http server
  * This docker compose doesn't support https, so we will generally expose it only to localhost on a given port to have another local server http using it on the host. For instance on port `8000`: `127.0.0.1:8000`.
  * If you want to test the server remotely without having another http server, you can expose it directly to the outside world by giving only a port number : `8000`.
* `WIKI_HOSTNAME`: Hostname(s) on which the wiki will be hosted. You can use multiple hostnames by splitting them with spaces.
* `TOOLS_HOSTNAME`: Hostname(s) on which the tools will be hosted. You can use multiple hostnames by splitting them with spaces.

The following keys are optionnal:

* `WIKI_EN_UPGRADE_KEY` and `WIKI_FR_UPGRADE_KEY`: [Upgrade password](https://www.mediawiki.org/wiki/Manual:$wgUpgradeKey) of the wiki. Should be a random non-guessable password. Should be left empty when upgrade is not in progress.
* `WIKI_DEBUG`: Enable the debug mode of the wiki if set to 1. To disable debug mode,  leave it empty. When enabled it activates:
  * The debug log in `(fr|en)/cache/debug.log`
  * Show php and sql errors
  * Show details and backtrace of exceptions

### Start the server for the first time

We will now use the `docker-compose` utility. To make it work you have to `cd` at the root of this repository.

```
docker-compose up --build
# Always keep the --build part, it will avoid you cache trouble if you play with the configuration of docker-compose
```

You should see everything starting, if something wrong in logs, just to a `Ctrl+C`, fix it and try again. You might also need to clean the `volues` directory which contains the persistent data of containers (wiki database and uploads) to reset everything.

MariaDB take generraly a few seconds to really get started (because it has to start a temp server first to initialize the db), so wait for the following lines to know when it is ready.

```
mariadb-wiki_1     | 2020-01-02 23:15:08+00:00 [Note] [Entrypoint]: Starting temporary server
...
mariadb-wiki_1     | 2020-01-02 23:15:09 0 [Note] mysqld: ready for connections.
...
mariadb-wiki_1     | 2020-01-02 23:16:21+00:00 [Note] [Entrypoint]: Temporary server stopped
...
mariadb-wiki_1     | 2020-01-02 23:16:21+00:00 [Note] [Entrypoint]: MySQL init process done. Ready for start up.
...
mariadb-wiki_1     | 2020-01-02 23:16:21 0 [Note] mysqld: ready for connections.
```

Once the database started, the tools should work as expected. However you should get the following error on the wiki

```
MediaWiki internal error.
```

This is generally because the wiki database has not been filled with a structure. If you want to get more details, you can restart the `docker-compose` with `DEBUG=1` in the `.env` file.

### Init the wiki

To init the wiki you will need a mysql dump of the current wiki. We don't have one without personnal data, but if really needed this might be created and upload to this repo.

First, dump the current database with somehting like this

```
# This should ask you the password of the use `wiki` and create the dump
mysqldump -h old-pc-sql.net.labate.me -u wiki -p wiki > dump-wiki.sql
# This might take some time..
```

Second, restore it to the container. Note that the `wikì` database should already be created so you have to ̀`use` it.

```
# We will first copy the dump into the container
docker cp dump-wiki.sql tools-compose_mariadb-wiki_1:/

# Then start restore the file into the db
docker exec -it tools-compose_mariadb-wiki_1 bash -c 'mysql -u root -p wiki < /dump-wiki.sql' 
# Give the WIKI_DB_ROOT_PASSWORD as password

# If it worked, we can delete the file from the container
docker exec -it tools-compose_mariadb-wiki_1 rm /dump-wiki.sql
```

Third, we also need to restore images from the current server

```
# In my case I will use direct rsync, but we don't care about the method, we only need to copy them
# take /var/www/main/(fr|en)/images content and put it into ./volumes/wiki-(fr|en)-images
rsync -vr old-pc-wiki.net.labate.me:/var/www/main/fr/images/ ./volumes/wiki-fr-images/
rsync -vr old-pc-wiki.net.labate.me:/var/www/main/en/images/ ./volumes/wiki-en-images/
```

Once everything has been copied, restart the `docker-compose up` to fix permissions on images directories.

We can also ask MediaWiki to purge caches for all pages

```
docker exec -it tools-compose_phpfpm-wiki_1 php /www/wiki/fr/maintenance/purgeList.php --purge --all
docker exec -it tools-compose_phpfpm-wiki_1 php /www/wiki/en/maintenance/purgeList.php --purge --all
```

### Start it for real

If you want to start containers without beeing locked into the logs, start

```
docker-compose up --build -d
```

You can still go watch the logs by doing

```
docker-compose logs -f 
```

## Troubleshoot

TODO explain password set in mysql
TODO Debug mode + Phpmyadmin
TODO port exposition