MapGuesser

This is the MapGuesser Application project. This is a game about guessing where you are based on a street view panorama - inspired by existing applications.

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.

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.

API keys

You should set the API keys that enable playing the game. Without these API keys the application cannot work well. To get Google API keys visit this page: https://console.developers.google.com/

Required Google APIs:

• Maps JavaScript API: for the interactive maps and street views
• Maps Static API: for the static map images
• Street View Static API: for the backend metadata requests

Required API keys:

• GOOGLE_MAPS_SERVER_API_KEY: this it used by the backend and should have access to Street View Static API
• GOOGLE_MAPS_JS_API_KEY: this is used by the frontend and should have access to Maps JavaScript API and Maps Static API

Additionally, a tile provider is also needed for map editor. This should be configured by LEAFLET_TILESERVER_URL, LEAFLET_TILESERVER_SUBDOMAINS and LEAFLET_TILESERVER_ATTRIBUTION. You can find some providers here: https://wiki.openstreetmap.org/wiki/Tile_servers. OpenStreetMap's tile server is fine for testing. Example:

LEAFLET_TILESERVER_URL=https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png
LEAFLET_TILESERVER_SUBDOMAINS=abc
LEAFLET_TILESERVER_ATTRIBUTION="&copy; <a href=\"https://www.openstreetmap.org/copyright\">OpenStreetMap</a> contributors"

(Production only) Create cron job

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:

0 * * * * /path/to/your/installation/mapg db:maintain >>/var/log/cron-mapguesser.log 2>&1

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:

./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.

---

License: GNU AGPL 3.0. Full license text can be found in file LICENSE.