To begin with, download the code for the test platform onto your machine. To do this using git, run:
Certain configuration files must be created to customise the test platform to
your own environment. To get you started, you can copy the
included in the codebase. Alternatively, you can run the
make init command if
make installed on your machine. The files to copy are:
.env: In this file, you can configure the ports that the test platform should listen for connections on, as well as defining credentials for the MySQL database, and setting appropriate user permissions.
src/.env: In this file, you can configure the URL for the test platform, as well as the URLs that the platform will use to contact other simulator components.
Once the configuration files have been added, you should be able to launch all microservices using the following command:
At this point,
docker-compose has launched all services required for the test
platform, but they will require further set-up. You can now set up the database
and install any missing dependencies by running the following
In a future version of the test platform, the images used by Docker will be pre-configured, so this step will not be necessary.
This installation script may fail if the
mysql service is unable to write
files to your host machine. Check that the
runtime/mysql directory exists and
is writable by your user. Another common cause of this is forgetting to update
UID field inside the
.env file. The value should be equal to your user
and group ID. To find out your user id, run
id -u and to find out your primary
group ID, run
id -g. In the example below,
UID should be set to
Once you have set up all simulator components, you must add the URLs for the
simulators into the
src/.env file. When these URLs are updated, the
installation script above should be re-run to ensure that the URLs are persisted
to the database.
It is a current limitation of the test platform that this process will also erase other contents of the database. To work around this, it is possible to update the
componentstable of the MySQL database directly.
At this point, all services are set up, and you should be able to log in. If you
did not change the default port in
.env, then you will be able to browse to
http://localhost:8084 in your web browser and see a login page.
By default, the test platform does not connect to a real SMTP server, but emails
are instead intercepted and shown on a test email server, which you will be able
to access on
http://localhost:8086. Using this mail server, you will be able
to register a new account and verify your email address to log in to the
To set up the test platform for production use, a few changes are recommended:
mailhogservice should be disabled and a real SMTP server connected to allow user registration emails.
- Other services should be configured to restart on failure by adding
restart: alwaysinto the docker-compose configuration.
- You may choose to add a reverse proxy (for example using
nginx) to make the platform available on other hostnames.
Updating the test platform is very straightforward and unlikely to cause any data loss. Before you proceed, you may nonetheless choose to make a backup of your database with the following command:
This will place a
.sql dump file inside the
runtime/mysql directory. You may
also choose to backup any modifications you have made to configuration files or
code (including the mysql backup just made) using
To update the project code, simply pull the latest changes using git. You can
also update service images (such as those used for mysql and redis) with
Once you have obtained the latest code, you can restart the services, install
any missing dependencies and update the database structure using another