Deployment & Installation

Docker Compose (Recommended)

The simplest way to run OpenDataMask in any environment:

git clone https://github.com/MaximumTrainer/OpenDataMask.git
cd OpenDataMask

# Generate and export secrets
export JWT_SECRET=$(openssl rand -base64 32)
export ENCRYPTION_KEY=$(openssl rand -base64 32 | head -c 32)

# Start all services
docker-compose up -d

# Check status
docker-compose ps
docker-compose logs -f backend

Services started:

• frontend — Vue 3 UI served by nginx on port 80
• backend — Spring Boot REST API on port 8080
• postgres — PostgreSQL 16 database on port 5432

Docker Images

Pre-built images are published to the GitHub Container Registry on every push to main:

# Backend
docker pull ghcr.io/maximumtrainer/opendatamask/backend:latest

# Frontend
docker pull ghcr.io/maximumtrainer/opendatamask/frontend:latest

# CLI
docker pull ghcr.io/maximumtrainer/opendatamask/cli:latest

Building locally

docker build -t opendatamask-backend ./backend
docker build -t opendatamask-frontend ./frontend
docker build -t opendatamask-cli ./cli

Environment Variables

Database Setup

OpenDataMask uses PostgreSQL 15+ for its metadata store. On first startup, Hibernate automatically creates the required schema (ddl-auto: update). No manual migration is needed.

# Create database manually (if not using docker-compose)
psql -U postgres -c "CREATE DATABASE opendatamask;"
psql -U postgres -c "CREATE USER opendatamask WITH PASSWORD 'secret';"
psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE opendatamask TO opendatamask;"

Terraform (AWS)

The infra/ directory provides Terraform configuration to provision a complete AWS environment — VPC, EC2 instance, security groups, Elastic IP, and S3/DynamoDB remote state. Everything runs as docker-compose on a single t3.small EC2 instance (Amazon Linux 2023), keeping costs low while remaining production-upgradeable.

Prerequisites

• Terraform 1.6+ installed — install guide
• AWS account with IAM credentials (EC2, VPC, S3, DynamoDB permissions)
• AWS CLI configured: aws configure

One-time: Bootstrap Remote State

# Create S3 bucket for Terraform state
aws s3api create-bucket --bucket my-opendatamask-tfstate --region us-east-1
aws s3api put-bucket-versioning \
  --bucket my-opendatamask-tfstate \
  --versioning-configuration Status=Enabled

# Create DynamoDB table for state locking
aws dynamodb create-table \
  --table-name opendatamask-tf-locks \
  --attribute-definitions AttributeName=LockID,AttributeType=S \
  --key-schema AttributeName=LockID,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

Deploy

cd infra
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars — add your SSH public key

terraform init \
  -backend-config="bucket=my-opendatamask-tfstate" \
  -backend-config="dynamodb_table=opendatamask-tf-locks" \
  -backend-config="region=us-east-1"

terraform plan
terraform apply

# Get the server's public IP
terraform output server_public_ip

GitHub Secrets for CI/CD Pipeline

Configure in GitHub → Settings → Secrets and variables → Actions:

Kubernetes

A basic Kubernetes deployment uses standard Deployment and Service resources. Store secrets with kubectl create secret:

kubectl create secret generic opendatamask-secrets \
  --from-literal=JWT_SECRET="$(openssl rand -base64 32)" \
  --from-literal=ENCRYPTION_KEY="$(openssl rand -base64 32 | head -c 32)" \
  --from-literal=DATABASE_PASSWORD="your-db-password"

Reference the secret in your Deployment envFrom block. A PostgreSQL StatefulSet or a managed cloud database (AWS RDS, Azure Database for PostgreSQL, Google Cloud SQL) is recommended for production.

CI / CD Pipelines

OpenDataMask ships with six GitHub Actions workflows delivering a complete build → deploy → verify → docs pipeline:

Deploy Pipeline Flow

push to main
  └─► CI (build + test + Docker push → GHCR)
        └─► deploy.yml:
              ├─ Job 1: terraform apply   ← provision/update AWS infra
              ├─ Job 2: SSH deploy         ← docker-compose pull && up
              └─ Job 3: verify             ← curl /actuator/health → 200 ✅
                    └─► Sandbox Masking Verification
                              └─► Playwright E2E Tests
                                        └─► Deploy Website (GitHub Pages)

GitHub Environments (staging, production) track each deployment — enabling deployment status, history, and environment URLs in the GitHub UI.

Security Notes

• Never commit JWT_SECRET or ENCRYPTION_KEY to source control. Use GitHub Secrets or a secrets manager.
• The health endpoint (/actuator/health) is publicly accessible by default. Restrict it at the network level in production.
• All connection passwords are encrypted at rest using AES-256 keyed by ENCRYPTION_KEY.
• HTTPS termination should be handled by a reverse proxy (nginx, Cloudflare, ALB) in front of the backend.
• JWT tokens expire after 24 hours by default (JWT_EXPIRATION).