DataMasque Portal

DataMasque Installation with Docker

This guide describes the process for deploying DataMasque with Docker Compose on a Linux server.

System requirements

Minimum requirements

  • Supported Operating Systems:

    • Ubuntu 18.04 or 20.04 LTS, x86 64-bit
    • RHEL 7 or 8, x86 64-bit
  • 4 vCPUs

  • 8 GiB RAM

  • 40 GiB available disk space

  • A static external IP or hostname

  • Ingress requests allowed on port 443 (and optionally port 80)

    • These ports are used to serve DataMasque's web interface.
    • If HTTP traffic is allowed on port 80, it will be automatically upgraded to HTTPS on port 443.
  • For admin access (SSH), ingress requests allowed on port 22.

DataMasque Ingress requests

  • Client web browser: Google Chrome 85 or above

  • Docker 19.03 to 20.10 (installation instructions - for RHEL, follow the CentOS installation instructions)

    • Docker should be installed from packages, not a convenience script.
    • You should ensure the user account that will be performing the DataMasque installation and administrative actions is added to the docker group. If you do not complete this step, all docker and docker-compose commands will require elevation to root privileges via sudo.

Note: The docker service starts automatically on Debian based distributions. On RPM based distributions, such as CentOS or RHEL, you need to start it manually using the appropriate systemctl command: sudo systemctl start docker or refer to Configure Docker to start on boot guide

  • Docker Compose 1.17 to 1.29
docker-compose Installation

DataMasque requires the standalone docker-compose command, not the docker compose that is integrated into Docker. Follow these instructions to install docker-compose:

  • Download docker-compose using curl:

    • sudo curl -SL https://github.com/docker/compose/releases/download/1.29.2/docker-compose-Linux-x86_64 -o /usr/local/bin/docker-compose
  • Make docker-compose executable:

    • sudo chmod +x /usr/local/bin/docker-compose
  • Test docker-compose by printing out its version to make sure it's installed correctly.

    • docker-compose --version
  • You should see output like this:

    • docker-compose version 1.29.2, build 5becea4c

Recommendations

  • Scaling: If you intend to run masking tasks in parallel or to perform multiple masking runs simultaneously, you should allocate 1 vCPU and at least 1 GiB of RAM per concurrent masking task.
  • Network and I/O: Refer to Network and I/O best practices for server networking recommendations.
  • Host security: It is recommended to deploy DataMasque on a dedicated VM/server with appropriate access control and enable host filesystem encryption.

Installing DataMasque with Docker Compose

Extract the provided DataMasque Docker Compose package on the server, and run the included installation script:

tar -xvzf datamasque-docker-v<version>.pkg
cd datamasque/<version>/
sudo ./install.sh

During installation, a new datamasque user and group will be created and assigned ownership of the DataMasque configuration files under /usr/local/etc/datamasque/. You can manually select the uid and gid for the datamasque user and group by providing --uid and --gid options to install.sh:

sudo ./install.sh --uid 1010 --gid 1010

Once the installation script has run, you can confirm the DataMasque Docker containers are running with the following command:

docker ps --format "table {{.ID}}\t{{.Status}}\t{{.Names}}"

If installation was successful, you should see five DataMasque containers listed:

CONTAINER ID        STATUS              NAMES
60114d0c370d        Up 3 minutes        datamasque_admin-frontend_1
da8bacfbbe48        Up 3 minutes        datamasque_admin-server_1
c9555bf98017        Up 3 minutes        datamasque_agent-worker_1
d46296fd5b3b        Up 3 minutes        datamasque_agent-queue_1
1d5516575e1c        Up 3 minutes        datamasque_admin-db_1

You can now access your DataMasque instance from a client web browser at: https://<instance-ip-or-hostname>. Follow the Initial Setup guide to complete the installation of DataMasque.

Note: The first time you visit DataMasque, your browser will display a security warning because the self-signed certificate generated by DataMasque will be untrusted by your browser. You may proceed past this warning for now, and install your own trusted certificate after installation is complete (refer to Installing SSL Credentials). If you are unable to proceed past the warning due to HSTS being enabled for your domain, refer to Installation with HSTS enabled.

Upgrading DataMasque with Docker Compose

It is recommended that you take backups of all rulesets, connections and uploaded files before upgrading your DataMasque instance.

To upgrade your DataMasque instance, extract the new DataMasque Docker Compose package, and run the included installation script with the --upgrade option:

tar -xvzf datamasque-docker-v<version>.pkg
cd datamasque/<version>/
sudo ./install.sh --upgrade

Note: If your user belongs to the docker and datamasque groups, root privilege escalation via sudo is not necessary.

Troubleshooting and maintenance

Installation with HSTS enabled

On browsers with HSTS enforced on the domain used to access DataMasque, the browser will block access to DataMasque if the default self-signed SSL certificate is in use. In this case it is recommended to install your own SSL credentials which are valid and trusted on your network.

To access DataMasque prior to installing your own trusted SSL certificate, you may replace the instance hostname with the server's IP address in the browser's address bar.

For example, if your instance hostname is my-datamasque-server.internal.org.domain, and HSTS is enforced your organisation's internal.org.domain, you would replace https://my-datamasque-server.internal.org.domain with https://<datamasque-server-ip> where <datamasque-server-ip> is the external IP address of your server.

Data protection

It is recommended to take regular backups of your DataMasque EC2 instance. It is also recommended to periodically save copies of your Run Logs, as well as Ruleset and Connection configurations.

Restarting DataMasque

To restart the DataMasque Docker containers, run the following command (if your user does not belong to the docker and datamasque groups, you will need to escalate to root privileges by prefixing the command with sudo):

docker-compose -f /usr/local/etc/datamasque/docker-compose.yml restart

You can verify that all five DataMasque containers have successfully restarted by running the following command:

docker ps --format "table {{.ID}}\t{{.Status}}\t{{.Names}}"

DataMasque logs

Important DataMasque logs can be extracted from the Docker containers with the following commands:

  • To copy the DataMasque web application logs to a <target-file-path>:
  docker cp datamasque_admin-server_1:/files/logs/uwsgi.log <target-file-path>
  • To copy the DataMasque masking agent logs to a <target-file-path>:
  docker cp datamasque_agent-worker_1:/files/logs/celery.log <target-file-path>

DataMasque start on boot

DataMasque's containers are configured with Docker Compose to always restart, so DataMasque will start automatically after system boot if the Docker daemon is configured to start on boot (which is the default configuration for a standard installation of Docker). For more information on configuring Docker to start on boot, refer to: https://docs.docker.com/engine/install/linux-postinstall/#configure-docker-to-start-on-boot.

How to fix installation if DataMasque images are deleted

If one or more of DataMasque's Docker images are removed from the Docker engine, you can use the docker load command to manually reload the images from the DataMasque Docker Compose package:

tar -xvzf DataMasque-<version>.pkg
cd DataMasque-<version>/
for image_name in ./images/*; do
  docker load -i "$image_name"
done

Once you have reloaded the images, you can recreate the Docker containers and restart DataMasque by running:

docker-compose -f /usr/local/etc/datamasque/docker-compose.yml up -d

Note that reloading the Docker images and recreating Docker containers with docker-compose will not delete DataMasque's application data, as long as DataMasque's Docker volumes are not removed.