From 716494f614753d65106546d2a491562f12589a9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C5=91cze=20Bence?= Date: Sat, 16 Sep 2023 23:06:39 +0200 Subject: [PATCH] update readme --- README.md | 115 +++++++++++++++++++++++++++--------------------------- 1 file changed, 57 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index 1b072f3..a7d679a 100644 --- a/README.md +++ b/README.md @@ -6,53 +6,11 @@ This is the MapGuesser Application project. This is a game about guessing where ## Installation -### Clone the Git repository - -The first step is obviously cloning the repository to your machine: - -``` -git clone https://gitea.e5tv.hu/esoko/mapguesser.git -``` - -All the commands listed here should be executed from the repository root. - -### Setup Docker stack (recommended) - -The easiest way to build up a fully working application with web server and database is to use Docker Compose with the included `docker-compose.yml`. - -All you have to do is executing the following command: - -``` -docker-compose up -d -``` - -Attach shell to the container of `mapguesser_app`: - -``` -docker exec -it mapguesser_app_1 bash -``` - -All of the following commands should be executed there. - -### Manual setup (alternative) - -If you don't use the Docker stack you need to install your environment manually. Check `docker-compose.yml` and `docker/Dockerfile` to see the system requirements. - -### Initialize project - -This command installes all of the Composer requirements and creates a copy of the example `.env` file. - -``` -composer create-project -``` - ### Set environment variables -The `.env` file contains several environment variables that are needed by the application to work properly. These should be configured for your environment. +The `.env` file contains several environment variables that are needed by the application to work properly. These should be configured for your environment. Check `.env.example` for reference. -One very important variable is `DEV`. This indicates that the application operates in development (staging) and not in production mode. - -**Hint:** If you install the application in the Docker stack for development (staging) environment, only the variables for external dependencies (API keys, map attribution, etc.) should be adapted. All other variables (for DB connection, static root, mailing, multiplayer, etc.) are fine with the default value. +**Important: `DEV` should NOT be set for production! See section Development if you want to use the application in development mode.** #### API keys @@ -75,31 +33,72 @@ LEAFLET_TILESERVER_SUBDOMAINS=abc LEAFLET_TILESERVER_ATTRIBUTION="© OpenStreetMap contributors" ``` -### (Production only) Create cron job +### Docker Compose -To maintain database (delete inactive users, old sessions etc.), the command `db:maintain` should be regularly executed. It is recommended to create a cron job that runs every hour: +Create a `docker-compose.yml` file. The example code below assumes that `.env` is placed in the same folder. + +```yml +version: '3' +services: + app: + image: git.esoko.eu/esoko/mapguesser:latest + depends_on: + mariadb: + condition: service_healthy + ports: + - 80:80 + - 8090:8090 + volumes: + - .env:/var/www/mapguesser/.env + mariadb: + image: mariadb:10.3 + volumes: + - mysql:/var/lib/mysql + environment: + MYSQL_ROOT_PASSWORD: 'root' + MYSQL_DATABASE: 'mapguesser' + MYSQL_USER: 'mapguesser' + MYSQL_PASSWORD: 'mapguesser' + healthcheck: + test: ["CMD-SHELL", "mysqladmin -u $$MYSQL_USER -p$$MYSQL_PASSWORD ping -h localhost || exit 1"] + start_period: 5s + start_interval: 1s + interval: 5s + timeout: 5s + retries: 5 +volumes: + mysql: ``` -0 * * * * /path/to/your/installation/mapg db:maintain >>/var/log/cron-mapguesser.log 2>&1 + +Execute the following command: +```bash +docker compose up -d ``` -### Finalize installation -After you followed the above steps, execute the following command: - -``` -scripts/install.sh -``` - -**Warning: Because of a known issue the image `mapguesser_multi` fails to run without the installation steps. You have to relauch `docker-compose up -d` after you finished the installation process.** - -**And you are done!** The application is ready to use and develop. In development mode an administrative user is also created by the installation script, email is **mapg@mapg.dev**, password is **123456**. In production mode you should create the first administrative user with the following command: +**And you are done!** The application is ready to use. You can create the first administrative user with the following command after attaching to the `app` container: ``` ./mapg user:add EMAIL PASSWORD admin ``` -If you installed it in the Docker stack, you can reach it on http://localhost. The mails that are sent by the application can be found on http://localhost:8080/. If needed, the database server can be directly reached on localhost:3306. +## Development + +### Set environment variables + +`.env.example` should be copied to `.env` into the repo root. Only the variables for external dependencies (API keys, map attribution, etc.) should be adapted in. All other variables (for DB connection, static root, mailing, multiplayer, etc.) are fine with the default value. **`DEV=1` should be set for development!** + +### Docker Compose + +Execute the following command from the repo root: +```bash +docker compose up -d +``` + +**And you are done!** You can reach the application on http://localhost. The mails that are sent by the application can be found on http://localhost:8080. If needed, the database server can be directly reached on localhost:3306, or you can use Adminer web interface on http://localhost:9090 + +You might have to attach to the `app` container, e.g. for creating users, `composer update`, etc. ---