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.
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:
- Make sure you have GNU Make installed on your system. Also one of the following should be installed:
- Docker with compose plugin - to run containers via docker runtime
- Podman-docker wrapper and podman-compose - to run containers over kubernetes setup.
- If you're using podman, please make sure you have
ip_tablesmodule inserted into your kernel on the host. Otherwise, containers will fail to start.
- 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.
- If you're using podman, please make sure you have
- Create new environment config file
Env/.env.production. There are examples in
Envfolder. Fill the file with proper settings for your setup.
- 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.conffile for basic nginx setup.
- Set up your reverse proxy, add SSL certificates (optionally). Point your reverse proxy entry points to following ports:
- Game API (Mimir) to port 4001
- User API (Frey) to port 4004
- Ratings service (Sigrun) to port 4002
- Mobile assistant (Tyr) to port 4103
- Admin panel (Forseti) to port 4107
- System logger and statistics system (Hugin) to port 4010
- (optional) System monitoring (Munin) to port 4011
- (optional) PgAdmin4 host to port 5632
make pullto fetch fresh containers from registry.
make prod_startto start containers
- Run the following command:
make prod_compile. This will build all static files for Tyr/Forseti/Sigrun and Sigrun server.
- If you're making a fresh setup, run
make bootstrap_adminto bootstrap a super-administrator account (firstname.lastname@example.org with password 123456). Don't do this on database that already has users!
- Basically, you're done :)
To update code on production server you will need to do the following:
make prod_update to fetch all changes from master branch. Please note that your setup and intentions must meet the following requirements:
- You use git-based version of code (cloned repository)
- You want to use code from master branch (please note - master is not always stable!)
- You don't have any changes is your working copy (except
Sigrun-dist/server.js- this file is a result of
prod_compile). If there are any changes, they will be discarded. You can check changes in your working copy using
git statuscommand. Production environment config is excluded from git, so it's guaranteed to be left untouched.
Basically these are the same commands that are done inside
make prod_update but performed one-by-one for better control.
- Get new code from the repository (e.g. run
git fetch && git checkout origin/masterin repo folder)
- Pull new containers using
- Restart containers with
make prod_restart(please use this exact command, otherwise email service will be started with wrong environment settings)
make prod_compileto 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,
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.
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
Hermod/opendkim_keys folder. Also following setting are required:
- Some unique key in
MAIL_ACTION_KEYvariable in your environment config.
- Mailer root host in
ALLOWED_SENDER_DOMAINSvariable in your environment config. Mailer address also will be set to
You may use
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
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:
- Set the
BACKUP_GIT_REMOTEvariable in your environment config to point to your backup remote repository. There is an example included in the env file.
- Go to
Databasefolder and call
make backup_dump_pubkeycommand to get ssh public key.
- Add this key to trusted keys in your account in Github, Gitlab or wherever your remote repository will reside.
- Restart the containers with
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
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
and changing the
BACKUP_GIT_REMOTE variable, followed by containers restart.
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+).
Make sure you have Docker and Docker Compose 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 docker-related command should be run as root. If nothing happens, or error
is displayed, try adding
make pullto fetch all the containers from registry. This is optional, though, it will allow you to skip container build process.
make devto build and start all containers, install dependencies for all projects, run database migrations and start webpack dev servers for Tyr and Forseti.
- After everything is build, you can use
make php_logsin each subsystem folder to view logs in real-time. Also you may use
make shellto get to container shell, if you want to. Notice that killing php-fpm, postgres or nginx will ruin the container entirely.
- You can use
make pantheon_stopto stop all containers (without deleting the data) and
make killto stop the container AND clean images (e.g. this will remove all db data).
To create an event and fill it with some data, run
make seed_bigevent or
make seed_tournament (with
sudo if required). Note that users are
re-seeded on each command run.
A separate guide about debugging in PhpStorm IDE is available.
Default ports for services are:
- 4001 for Mimir game management API (http://localhost:4001/)
- 4002 for Sigrun public interface (http://localhost:4002/)
- 4003 for Tyr mobile interface (http://localhost:4003/)
- 4004 for Frey user management backend (http://localhost:4004/)
- 4007 for Forseti management interface (http://localhost:4007/)
- 5532 for PostgreSQL connections - if you want to use external pgAdmin3/4 or any other client to access your databases.
- 5632 for pgAdmin4 container (http://localhost:5632/), which is run for convenience. You will need to setup initial connections using following credentials:
- PgAdmin login:
- Mimir database host:
- Mimir database port:
- Mimir database user:
- Mimir database password:
- Frey database host:
- Frey database port:
- Frey database user:
- Frey database password:
- PgAdmin login:
Mimir and Frey use twirp interface to communicate with other services.
See protocol description files in
- If you change the protocols, you should run
make proto_genin root repo folder to regenerate all protocol related code.
- You always should change the proto files and never should change the generated code by hand.
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).
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).
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.