DIR : /home/kozerus/public_html/go/dgs/deploy/local/README.md

/home/kozerus/public_html/go/dgs/deploy/local


# Install DGS on local machine with Docker

This document describes how to install DGS locally on your machine with Docker.

You'll find a lot of references to the main installation [INSTALL document](../../INSTALL)
like (INSTALL:4a).  In here only the differences are described.

# Prerequisites

The local ports 80, 1025, 3307, 8025, 8080 must not be taken by other applications.

Port 80 may be taken by another webserver.  Either you stop it or you have
to adjust the docker compose file to expose other ports.

The same applies for the other ports.

# Install Docker Environment

The basic requirement is to install a docker environment with:

* docker >= 17 : https://docs.docker.com/install/
* docker-compose >= 1.17 : https://docs.docker.com/compose/install/

# Install & Configure DGS

## Download the sources

do step (INSTALL:1)

Every following step assumes to be in the DGS\_ROOT directory.

## Configure DGS

* do steps (INSTALL: 4d, 4e, 4f)
* do steps (INSTALL: 4a, 4c)<br/>
  Use the following configurations for a local docker-based setup in the file `./include/config-local.php`:
  - required:
    ```
    define('MYSQLHOST', 'local_db');
    define('MYSQLUSER', 'dragon');
    define('MYSQLPASSWORD', 'dragon');
    define('DB_NAME', 'dragon');
    ```
  - recommended:
    ```
    define('FRIENDLY_LONG_NAME', 'Dragon Go Server (local-dev)');
    define('FRIENDLY_SHORT_NAME', 'ldDGS');
    define('SEND_ACTIVATION_MAIL', false);
    define('RESTRICT_SHOW_GAMES_ALL', 600);
    ```
* skip steps (INSTALL: 4j, 4k, 4m) - those will be done implicitly with docker
  - (INSTALL:4j) additional mariadb configuration can be added / changed in file `./deploy/local/mariadb/conf.d/dgs-maria.cnf`
  - (INSTALL:4k,4m) additional PHP ini directives can be added / changed in `*.ini` files in directory `./deploy/local/web/`
* optionally do steps (INSTALL: 4b, 4g, 4h, 4i, 4n)

## Create webserver & database

In this step the docker images for DGS are created,
the webserver (apache) & database (maria db) will be started,
the DGS database will be created and initialized with db users (INSTALL:2),
and the DGS tables will be initialized (INSTALL:3a,3b).
```
# create directory for data-exchange & apache logs
mkdir -p ./local-data/db ./local-data/apache-logs

cd deploy/local/

# create docker images for webserver & database-server
docker-compose pull
docker-compose build

# startup DGS containers
# - start mariadb (db-server)
# - only on first startup:
#   - create "dragon"-database
#   - create "dragon_admin"-user
#   - create "dragon"-user
#   - initialize db tables with DDL & initial data
docker-compose up -d
```

## Finalize installation

* do steps (INSTALL: 3c, 3d) - for translations
* optionally do step (INSTALL:5) - locally the cron pages can be called on demand
  - Example: `http://localhost/tournaments/cron_tournaments.php`
* optionally do step (INSTALL:6) - for protection of `./scripts` directory
* test installation:
  - DGS: open http://localhost/ & login as guest or admin user (INSTALL:3d)
  - DB GUI adminer: open http://localhost:8080/ & login to db (use `local_db` as hostname)

### Recreate database from scratch

If you have started DGS before or there was an error on startup
and you want to wipe the database, you'll have to create the database
from scratch again.

IMPORTANT NOTE: All changes in the database will be lost with this step!

This will be accomplished by deleting the persistent volume of the docker container.
```
cd deploy/local/

docker-compose down

docker volume ls
docker volume rm local_dgs_db

docker-compose up -d
```

# Commands for operating & debugging

## Startup & Shutdown DGS

```
cd deploy/local/

# startup DGS containers
docker-compose up -d

# shutdown DGS
docker-compose down
```

## Checking logs

```
# check all container logs
docker-compose logs -f

# check database logs
docker logs local_db -f

# check apache & mail logs
tail -n 500 -f ./local-data/apache-logs/DGS-*
```

## Execute SQL in DGS database

Run mysql-client in existing local DGS mariadb container:
```
# open mysql-client
docker exec -it local_db mysql -hlocal_db -udragon_admin -padmin dragon

# import gzipped data file into DGS db
cp data-file.gz ./local-data/db/
docker exec -it local_db sh -c 'zcat /mnt/data/data-file.gz | mysql -hlocal_db -udragon_admin -padmin dragon'
```

Alternatively start new container with connection to local DGS db:
```
docker run -it --network=local_dgs --rm mariadb:5.5 mysql -hlocal_db -udragon_admin -padmin dragon

docker run -it --network=local_dgs --link local_db:mysql --rm mariadb:5.5 sh -c 'exec mysql -hlocalhost -P3307 -udragon_admin -padmin dragon'
```

## Execute PHP in DGS webserver

```
docker exec -it local_web sh -c '(cd /var/www/html/code_examples && php print_timezone.php)'
```

## Look into containers

```
# look into container with PHP Apache webserver
docker exec -it local_web bash

# look into container with mariadb
docker exec -it local_db bash
```

If the terminal (with the exec in the docker containers above) is messed up in size,
then execute the script 'fix-docker-terminal-size.sh' from outside the container.


## Debug sending mails

For local debugging & testing purposes a mail catcher is used.  It's configured in the 'php.ini'
config file with setting the 'sendmail\_path' directive.

Mails sent via PHP are catched by mailhog and can be viewed with the UI: http://localhost:8025/


# References

* Dockerfile reference: https://docs.docker.com/engine/reference/builder/
* docker compose reference: https://docs.docker.com/compose/compose-file/
* mariadb on docker-hub: https://hub.docker.com/_/mariadb/
* php-apache on docker-hub: https://github.com/docker-library/docs/tree/master/php
* mailhog on docker-hub: https://hub.docker.com/r/mailhog/mailhog/
  mailhog installation: https://blog.philipphauer.de/test-mail-server-php-docker-container/