Deployment Guide

tip

• Ensure that you have updated the docker-compose.yml file include the services that you want to deploy.
• Ensure that you have updated the Jenkinsfile file to include the services that you want to deploy.

This comprehensive guide covers the deployment of the Data Viz Example project, which is a multi-service application comprising a React frontend, Java Spring Boot microservices, WordPress customization, documentation site, and supporting infrastructure.

Architecture Overview

The Data Viz Example project consists of the following components:

Core Services

• Frontend (UI): React Router V7 (Remix) application built with Vite
• API Gateway: Routes requests to microservices
• Eureka Service Discovery: Service registry for microservice discovery
• Security Service: Authentication and authorization
• Starter Service: Base configuration service
• Custom Services: Custom services that you want to deploy

Infrastructure Services

• PostgreSQL: Primary database for microservices
• MySQL/MariaDB: Database for WordPress
• Redis: Caching layer
• Nginx: Reverse proxy and static file server

Content Management

• WordPress: Content management with custom blocks
• WordPress Customizer: Custom Gutenberg blocks for data visualization

Prerequisites

Development Environment

• Docker: Version 24.0.0 or higher
• Docker Compose: Version 2.0 or higher
• Node.js: Version 22 or higher (for building frontend and WordPress blocks)
• Java: Version 21 (Eclipse Temurin recommended)
• Maven: Version 3.x
• Git: For version control

Docker Image Recommendations

For backend services, we recommend using Eclipse Temurin-based Docker images. See the Recommended Docker Images guide for details on which images to use for building and running Java services.

Production Environment

• Docker: Version 24.0.0 or higher
• Docker Compose: Version 2.0 or higher
• Container Registry Access: Access to registry.developmentgateway.org
• Ansible: For automated deployment (if using CI/CD pipeline)
• Firewall: HTTP/HTTPS ports open (80, 443)

Environment Configuration

Environment Variables

The following environment variables must be configured:

# Registry and tagging
export REPO=registry.developmentgateway.org/data-viz-example
export TAG=staging  # or your target environment tag

# Build optimization
export DOCKER_BUILDKIT=1
export BUILDKIT_INLINE_CACHE=1
export COMPOSE_BAKE=true

Database Configuration

PostgreSQL (Microservices)

• Database: viz
• Username: postgres
• Password: admin
• Port: 5432

MySQL (WordPress)

• Database: wordpress
• Username: wordpress
• Password: wordpress
• Root Password: somewordpress
• Port: 3306

Frontend Configuration

The UI service accepts several environment variables for customization:

VITE_REACT_APP_DEFAULT_LOCALE=en
VITE_REACT_APP_USE_HASH_LINKS=false
VITE_REACT_APP_WP_HOSTS=localhost
VITE_REACT_APP_API_ROOT=http://localhost
VITE_REACT_APP_WP_SEARCH_END_POINT=/dg/v1/search
VITE_REACT_APP_LOAD_DEFAULT_THEME=false

Deployment Methods

1. Development Deployment

For local development and testing:

# Clone the repository
git clone --recurse-submodules <repository-url>
cd data-viz-example

# Set environment variables
export REPO=registry.developmentgateway.org/data-viz-example # Replace with your registry URL
export TAG=main

# Build and start services
./dev_services.sh

This will start all services using the development configuration with:

• Hot reload enabled
• Debug ports exposed
• Local volume mounts for development
• JSON file logging

2. Staging Deployment

For staging environment deployment:

# Set environment variables
export REPO=registry.developmentgateway.org/data-viz-example # Replace with your registry URL
export TAG=main

# Build specific services first
docker compose build ui-customizer wp-customizer

# Start core services
docker compose up mysql postgres eureka gateway wordpress nginx starter example-service docs

3. Production Deployment via CI/CD

The project uses Jenkins for automated CI/CD with the following pipeline stages:

Stage 1: Build WordPress Customizer

• Uses Node.js 22-slim image
• Installs pnpm package manager
• Builds WordPress custom blocks

Stage 2: Build Services (Matrix)

Builds multiple services in parallel:

• starter: Java Spring Boot starter service (uses Eclipse Temurin images)
• docs: Docusaurus documentation site
• example-service: Custom data service (uses Eclipse Temurin images)
• ui: React frontend application

Docker Image Updates

Backend services should use Eclipse Temurin images (maven:3-eclipse-temurin-21 for builds, eclipse-temurin:21-jre-alpine for runtime). See Recommended Docker Images for migration guidance.

Note: Update your Jenkinsfile to use maven:3-eclipse-temurin-21 instead of maven:3-amazoncorretto-21 if you haven't already migrated.

Stage 3: Deploy

• Uses Ansible for automated deployment
• Deploys to target environment based on branch name
• Updates Docker images and restarts services

Configuration Management

Docker Images

Backend services should use Eclipse Temurin-based Docker images:

• Build images: maven:3-eclipse-temurin-21 for building Java applications
• Runtime images: eclipse-temurin:21-jre-alpine for production (recommended) or eclipse-temurin:21-jdk-alpine for development

OpenJDK Deprecation

OpenJDK images have been removed from Docker Hub. If your services use openjdk:* images, you must migrate to Eclipse Temurin images. See Recommended Docker Images for migration guidance.

Docker Compose Files

• docker-compose.yml: Production configuration
• docker-compose.override.yml: Development overrides (automatically applied in development)

Nginx Configuration

The reverse proxy configuration (custom/deploy/nginx.conf) handles:

• Routing /api/* requests to the API gateway
• Serving /wp/* requests to WordPress
• Serving root requests to the React UI
• Static file caching and optimization

WordPress Customization

WordPress custom blocks are built separately and mounted as volumes:

# Build WordPress blocks
cd custom/wp-customizer/blocks
pnpm install
pnpm run build

Monitoring and Health Checks

Service Health Checks

The deployment includes health checks for critical services:

• Eureka: http://localhost:8761/actuator/health
• Starter: http://localhost:8083/actuator/info
• PostgreSQL: pg_isready command

Port Mapping

Service	Internal Port	External Port (Dev)
Nginx	80	80
WordPress	80	8080
UI	4173	4173
Docs	4200	4200
Eureka	8761	8761
Gateway	8762	8762
PostgreSQL	5432	5432
MySQL	3306	3307

Data Persistence

Volumes

The following volumes persist data across container restarts:

• postgres: PostgreSQL data
• mysql: MySQL/MariaDB data
• wordpress: WordPress files and uploads
• cache: Redis cache data

Troubleshooting

Common Issues

1. Service Discovery Issues

If services can't find each other:

# Check Eureka registry
curl http://localhost:8761/eureka/apps

# Restart Eureka and dependent services
docker compose restart eureka gateway example-service

2. Database Connection Issues

# Check database connectivity
docker compose exec gateway ping postgres
docker compose exec wordpress ping mysql

# Check database logs
docker compose logs postgres
docker compose logs mysql

3. Build Issues

# Clean Docker build cache
docker builder prune -f

# Rebuild specific service
docker compose build --no-cache <service-name>

Docker Image Compatibility

If you encounter build issues with Java services, ensure you're using the recommended Eclipse Temurin images. OpenJDK images have been deprecated and removed from Docker Hub. See Recommended Docker Images for migration details.

4. WordPress Block Issues

# Rebuild WordPress blocks
cd custom/wp-customizer/blocks
rm -rf node_modules build
pnpm install
pnpm run build

# Restart WordPress
docker compose restart wordpress

Log Access

Access service logs using:

# View logs for specific service
docker compose logs -f <service-name>

# View logs for all services
docker compose logs -f

# View logs with timestamps
docker compose logs -t <service-name>

Security Considerations

Production Security Checklist

• Change default database passwords
• Use environment-specific configuration files
• Enable HTTPS with SSL certificates
• Configure firewall rules
• Regular security updates
• Monitor service logs for anomalies
• Implement proper backup encryption
• Use secrets management for sensitive data

Network Security

In production:

• Services communicate over internal Docker networks
• Only Nginx is exposed to external traffic
• Database ports are not exposed externally
• Use secrets for sensitive environment variables

Performance Optimization

Resource Allocation

Default JVM settings for Java services:

JAVA_OPTS: "-Xmx512m -Xms512m -XX:+UseG1GC -XX:InitialHeapSize=512m -XX:MaxHeapSize=512m -XX:+ParallelRefProcEnabled"

Adjust based on your server resources and load requirements.

Caching Strategy

• Nginx: Static file caching and proxy caching
• Redis: Application-level caching
• WordPress: FastCGI caching (can be enabled in nginx.conf)

Considerations

For high-traffic deployments:

1. Horizontal Scaling: Deploy multiple instances behind a load balancer
2. Database Scaling: Consider read replicas for PostgreSQL
3. CDN: Use a CDN for static assets
4. Container Orchestration: Consider Kubernetes for large-scale deployments

Production Deployment Tips

• Remove unused services from the docker-compose.yml file to speed up deployment
• Pre-build services in your CI/CD pipeline to reduce deployment time
• Use health checks to ensure services are ready before marking deployment as successful

Important Notes

• Always test deployments in a staging environment first
• Keep regular backups of both databases and uploaded files
• Monitor disk space usage, especially for log files and database storage