Mahjong Pantheon: automated statistics & assistance for japanese riichi mahjong sessions.

You may use github issues for error reports and feature requests. Pull requests are especially welcome :)

Pantheon can be run in production or in development mode. Please don't use development build for your production setup.

Production build

⚠ For the detailed guide of setting up Pantheon on clean VPS, refer to Production Setup Guide. Brief instructions on production setup are listed below.

Clone the pantheon repository to your own server. Make sure repo folder is not accessible for the outer world.

To deploy pantheon on your own VPS or personal environment on production mode:

  1. Make sure you have GNU Make installed on your system. Also one of the following should be installed:
    • [recommended] Docker with compose plugin - to run containers via docker runtime.
    • Podman and podman-compose - to run containers over OCI runtime.
      • Pantheon scripts use docker detection, so if you have both docker and podman installed, docker will be used.
      • Podman has better security and doesn't have privileges problem with dependencies (e.g. you might need to remove node_modules as root when using docker).
      • Podman has some gotchas to be considered to run properly. See podman notes below.
  2. Create new environment config file Env/.env.production. There are examples in Env folder. Fill the file with proper settings for your setup.
  3. Fill new environment file with proper values, mostly it's about hosts, where you want the services to be accessible from the outer internet. Please note: setting up Nginx or any other reverse proxy is your responsibility. You may refer to nginx-reverse-proxy.example.conf file for basic nginx setup.
  4. Set up your reverse proxy, add SSL certificates (optionally). Please use included nginx-reverse-proxy.example.conf as reference of what host to point where. Note that *.pantheon.internal hosts are used to distinguish the services inside container network. Optionally, you can also point PgAdmin4 host to port 5632.
  5. Run make pull to fetch fresh containers from registry.
    • As an option, you can run make container to build containers from scratch, but it's not recommended for production environment.
  6. Run make prod_start to start containers
  7. Run the following command: make prod_compile. This will build all static files for Tyr/Forseti/Sigrun and Sigrun server.
  8. If you're making a fresh setup, run make bootstrap_admin to bootstrap a super-administrator account (admin@localhost.localdomain with password 123456). Be careful doing this on the database that already has users or admins, as it will potentially create a security breach (e.g. superadmin account with default login and password).
    • Use https://{yourhost}/profile/editPlayer/{player_id} link to edit the email, and then use password reset feature to set the new password.
    • On fresh setup, player_id will be 1, in general you can find the player_id on https://{yourhost}/profile/manage page after logging in with default username and password.
  9. Basically, you're done :)

To update code on production server you will need to do the following:

Quick way

Use make prod_update to fetch all changes from master branch. Please note that your setup and intentions must meet the following requirements:

Long way

Basically these are the same commands that are done inside make prod_update but performed one-by-one for better control.

  1. Get new code from the repository (e.g. run git fetch && git checkout origin/master in repo folder)
  2. Pull new containers using make pull
  3. Restart containers with make prod_restart (please use this exact command, otherwise email service will be started with wrong environment settings)
  4. Run make prod_compile to build newer versions of the static code.

If you ever change the environment variables in your current Env/.env.production file, you should also restart the containers using make prod_restart. After that, if VITE_* variables have been changed, you should also run make prod_compile for changes to take effect.

Please note that db and pgadmin containers are not restarted during make prod_restart. To stop these containers as well, use make prod_stop_all. This is rarely needed, though.

Email agent

Pantheon provides container with pre-installed email agent (Hermod). If you want to send emails signed with DKIM, you will need to place your private keys to Hermod/opendkim_keys folder. Also following setting are required:

HTTPS

You may use bin/letsencrypt-scripts and nginx-reverse-proxy.example.conf as an example and reference to set up your SSL certificates using Let's Encrypt. If you're not intending to use https, please disable corresponding directives in your reverse proxy nginx config.

Setting up database backups

Pantheon provides built-in database backups using git. By default, it just stores database dump as new commits in /var/lib/postgresql/backup folder of the Database container (you can get to shell using make shell_db). If you want to set up some remote backups, you should do the following:

Every 15 minutes the database dump is made. You may view history of backups using make backup_show_history in Database folder. To rollback your database to previous state you may use either included pgadmin4 container (running at 5632 port) or the one-liner command from the Database folder: COMMIT=1234567 make backup_restore, where 1234567 should be replaced with target commit hash (which can be found using make backup_show_history command). Please note that one-liner will rollback both mimir and frey databases!

Please note that backups will consume quite much disk space. To clean up some space you may consider deleting the /var/lib/postgresql/backup/.git directory and changing the BACKUP_GIT_REMOTE variable, followed by containers restart.

Development environment

Pantheon developer environment works on *nix hosts (mac, linux, *bsd). Windows-based systems are not supported (while it still MAY work, it is not tested at all, also you may want to try using it under WSL in Windows 10+).

Prerequisites

First, please add the following entries to your /etc/hosts file so you could access pantheon services locally:

127.0.0.1   bragi.pantheon.local
127.0.0.1   forseti.pantheon.local
127.0.0.1   frey.pantheon.local
127.0.0.1   gullveig.pantheon.local
127.0.0.1   hermod.pantheon.local
127.0.0.1   hugin.pantheon.local
127.0.0.1   mimir.pantheon.local
127.0.0.1   meili.pantheon.local
127.0.0.1   sigrun.pantheon.local
127.0.0.1   skirnir.pantheon.local
127.0.0.1   tyr.pantheon.local
127.0.0.1   pga.pantheon.local
127.0.0.1   grafana.pantheon.local
127.0.0.1   dozzle.pantheon.local

Second, make sure your local port 80 is not used by any other software (like nginx, apache or another web server).

Installing and running

Make sure you have Docker, Docker compose plugin and Docker buildx plugin installed and daemon running on your system. For debugging, please make sure all the php extensions are installed as well, see Dockerfile for a complete list.

Note: on some linux distros almost every container-related command should be run as root. If nothing happens, or error is displayed, try adding sudo before make.

  1. Run make pull to fetch all the containers from registry. This is optional, though, it will allow you to skip container build process.
    • As an option, you can run make container_dev to build containers from scratch on you local machine. This may take a long time.
  2. Run make dev to start all containers, install dependencies for all projects, run database migrations and start webpack dev servers for Tyr and Forseti.
  3. After everything is build, you can use make logs and make php_logs in each subsystem folder to view logs in real-time. Also you may use make shell to get to container shell, if you want to. Notice that killing php-fpm, postgres or nginx will ruin the container entirely.
  4. You can use make pantheon_stop to stop all containers (without deleting the data) and make kill to stop the container AND clean images (e.g. this will remove all db data).

Please note: if you're using podman, trying to stop a single service container will result in also stopping all containers it depends on. Docker has no such issue.

To create an event and fill it with some data, run make seed, make seed_bigevent or make seed_tournament (with sudo if required). Note that users are re-seeded on each command run. To log in as one of the created users, you may need the id and client hash emitted in the console. Note that dump is output in development mode only. Created users' data is saved to temporary file inside Frey container, so you may also access this data using make dump_users.

A separate guide about debugging in PhpStorm IDE is available.

Local port 5532 will available for PostgreSQL connections - if you want to use external pgAdmin3/4 or any other client to access your databases.

Services will be available at:

Mimir and Frey use twirp interface to communicate with other services. See protocol description files in Common folder. Please note:

Upgrade to Frey v2

Frey has been rewritten from scratch for better maintainability. To migrate to new version you'll need to:

After the steps are completed, you may want to remove old frey database. To do so, use make shell_db and drop the database using psql.

End-to-end tests

Pantheon services include e2e testing framework based on Playwright. To run it locally, make sure pantheon development environment is running (make dev) and use make e2e_dev command in separate terminal window. Note that it will run tests against development build, so no SSR is tested locally.

If you want to test full production build locally, you may stop the development environment and use following commands:

make e2e_run
make e2e_compile
make e2e

Remember to remove all the files created during the run before committing changes.

Email agent

Pantheon provides container with pre-installed email agent (Hermod). You can view last sent email in CLI using make dump_last_mail command. This is useful to test registration and password recovery, because emails sent from the developer environment will most likely be rejected by target email relay (e.g. gmail rejects it in 100% of cases).

Notifications agent

Pantheon supports realtime notifications (currently only via Telegram, but Discord may also be added soon). To use this functionality you should register a bot in Telegram and set its nickname and secret token in Env/.env.production:

BOT_TOKEN=yourtoken
VITE_BOT_NICKNAME=bot_nickname

After that your users should open the bot, start the conversation and follow the link it sends. After pressing the confirmation button, bot will be enabled for this particular user.

Podman notes

Basic all-in-one script for all the notes above:

sudo aa-teardown || true
sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER
sudo systemctl disable --now apparmor.service
sudo rm -f /etc/containers/storage.conf || true
podman system reset -f
sudo podman system reset -f

Pull requests

Any pull request should pass all current code style checks; also all unit tests should pass. Don't forget to run make check (with sudo if required) before sending your pull request. To fix all code style issues automatically (in php code only), run make autofix (also sudo may be required).

External services

One may want to use Pantheon API in some own external service. Please make sure you have protoc v3.21.9-r0 so generated binary code matches our protocol version.

License

All Pantheon code except protocol files is licensed under the GNU GPL v3 License. See the LICENSE file for details. Protocol files are licensed under the Apache License, Version 2.0. See the LICENSE file in Common/proto folder for details.