Web service to store Terasology client identities, powered by PostgreSQL and node.js.
See this forum thread for more information.
How to install
This application is designed to be deployed using Docker and docker-compose. These are the only dependencies you need on the server machine. To run the application, look in the .env file at the repository root and consider if it's necessary to override some variables, then run
docker-compose up; in a production environment, most importantly you need to set the reCAPTCHA keys. If your docker-compose version supports it, it's not necessary to modify the .env file, all the customizations can be passed as environment variables - for example, your startup command may look like
HTTPS_ENABLED=false RECAPTCHA_SITE_KEY=yoursitekey RECAPTCHA_SECRET_KEY=yoursecretkey docker-compose up.
Note: destroying (
docker rm or similar) the database container will delete the database data too. If you have relevant data in the database (i.e. some users actually registered and uploaded client identities) you first need to ensure you have an updated backup (see below for more information).
Setting up outgoing mail
The default docker-compose file sets up a local mail server (postfix) to send registration and password recovery emails without having to use an account on an external service. However, some services may not trust your server and messages coming from it, thus putting the emails sent by the identity storage server in the Spam folder or not delivering them at all. As an alternative, you can use an external SMTP server to send the emails; to do this, set the
EXT_SMTP_PASSWORD variables to the appropriate values (either by modifying the
.env file or setting them as environment variables) and use the
docker-compose-externalMail.yml file instead of the default one with the
-f switch to docker-compose (e.g.
docker-compose -f docker-compose-externalMail.yml up). If using a Gmail account as sender, be sure to read the instructions on this page; you probably need to enable access to "unsafe applications" for that account.
Starting and stopping
Since v1.1 stopping and restarting the containers (i.e.
docker-compose stop followed by
docker-compose up) works correctly. Remember however, that you always need to specify the environment variables you want to override when running
Since v1.1 an automated backup script is included. Backups, in the form of SQL database dumps (with data only, no schema), are performed daily at 00:00 and kept for 7 days (meaning you should be able to restore the database at the state of any day in the past week).
The dump files are put in a directory which is shared between the database container and the host machine. By default, the host directory is
./db-dumps, relative to the directory
docker-compose up is run from; it's recommended you customize it by overriding the
DB_BACKUP_VOLUME environment variable (perhaps using an absolute path). Backup files are named in the form
backup_<date and time>.sql. If an error occurs while performing a backup, a file with the standard error produced by the script is placed in the directory.
sql/scripts/backup.sh for more details.
It's possible to manually launch a backup by executing the
backup.sh script placed in the
app-scripts directory of the database container.
You need to execute the script as the
terasologykeys_backup user (not as root). In other words, simply use this command:
docker exec -it terasologykeyserver_database_1 gosu terasologykeys_backup /app-scripts/backup.sh
You may need to change
terasologykeyserver_database_1 if the container name is different (use
docker ps to see a list of the running containers).
Restoring a backup
To restore a backup, ensure there is no database container (if necessary, remove it with
docker rm terasologykeyserver_database_1 or similar, according to the container name, but again warning: this will destroy the current database, so ensure your backups are updated to the latest changes if doing this - you probably want to run a manual backup as described above). Then, start the application with
docker-compose up after setting
DB_RESTORE_BACKUP_FILENAME to the backup file name you want to restore, which must be in the backups folder (specified by
DB_RESTORE_BACKUP_FILENAME=backup_2017-08-12T09:48:25+0000.sql [other variables such as reCAPTCHA keys] docker-compose up
If this variable is set, when the database container is created, it will import the data from the specified file after creating the schema (tables, functions, etc).