DEV Community: Majedul Islam

Deploy a Polyglot Stack (Spring Boot + FastAPI) on GCP with Cloud Run, Cloud SQL, and Memorystore

Majedul Islam — Sat, 04 Oct 2025 15:39:41 +0000

Deploy a Polyglot Stack on Google Cloud

Deploying multiple services written in different languages can be tricky, but with Google Cloud managed services, you can run a polyglot stack efficiently. In this guide, we’ll deploy:

Backend: Spring Boot (Java)
AI/Service: FastAPI (Python)
Database: Cloud SQL (PostgreSQL)
Cache: Memorystore (Redis)
Networking: Serverless VPC Access Connector
CI/CD: Cloud Build + Artifact Registry
Hosting: Cloud Run (serverless)

This setup ensures production-grade isolation, scalability, private networking, and clean CI/CD pipelines.

All commands use placeholders like PROJECT_ID and REGION. Replace them with your own values. Store sensitive values in Secret Manager, never in shell history.

1. Install the Google Cloud CLI

To install the Google Cloud CLI on your system, follow the official guide for your platform: Google Cloud SDK Installation

Initialize:

gcloud init

2. Set Environment Variables

export PROJECT_ID="your-gcp-project-id"
export REGION="asia-southeast1"
export ARTIFACT_REGION="asia-southeast1"

# Networking
export NETWORK="default"
export SUBNET="default"
export VPC_CONNECTOR="serverless-connector-01"
export VPC_CONNECTOR_RANGE="10.8.0.0/28"

# Cloud SQL (Postgres)
export SQL_INSTANCE_NAME="app-postgres"
export SQL_TIER="db-f1-micro"
export SQL_DB_BACKEND="backend_db"
export SQL_DB_AI="ai_db"
export SQL_USER="app_user"
export SQL_PASS="$(openssl rand -base64 24)" # store in Secret Manager

# Memorystore (Redis)
export REDIS_INSTANCE="app-redis"
export REDIS_TIER="BASIC"
export REDIS_SIZE_GB=1

# Artifact Registry
export REPO_BACKEND="apps-backend"
export REPO_AI="apps-ai"

# Images and services
export BACKEND_IMAGE="${ARTIFACT_REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_BACKEND}/backend:$(git rev-parse --short HEAD)"
export AI_IMAGE="${ARTIFACT_REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_AI}/ai:$(git rev-parse --short HEAD)"
export SERVICE_BACKEND="backend"
export SERVICE_AI="ai"

Enable required APIs:

gcloud services enable run.googleapis.com sqladmin.googleapis.com redis.googleapis.com \
  artifactregistry.googleapis.com vpcaccess.googleapis.com secretmanager.googleapis.com

3. Create Cloud SQL (PostgreSQL)

# Create instance
gcloud sql instances create ${SQL_INSTANCE_NAME} \
  --project=${PROJECT_ID} \
  --region=${REGION} \
  --database-version=POSTGRES_15 \
  --tier=${SQL_TIER}

# Create databases
gcloud sql databases create ${SQL_DB_BACKEND} --instance=${SQL_INSTANCE_NAME}
gcloud sql databases create ${SQL_DB_AI} --instance=${SQL_INSTANCE_NAME}

# Create user
gcloud sql users create ${SQL_USER} --instance=${SQL_INSTANCE_NAME} --password="${SQL_PASS}"

# Get connection name for Cloud Run
export SQL_CONNECTION_NAME=$(gcloud sql instances describe ${SQL_INSTANCE_NAME} --format='value(connectionName)')

Tip: Use Private IP for production and connect via a VPC connector for better security.

4. Create Memorystore (Redis)

gcloud redis instances create ${REDIS_INSTANCE} \
  --size=${REDIS_SIZE_GB} \
  --region=${REGION} \
  --tier=${REDIS_TIER} \
  --network=${NETWORK}

export REDIS_HOST=$(gcloud redis instances describe ${REDIS_INSTANCE} --region=${REGION} --format='value(host)')
export REDIS_PORT=$(gcloud redis instances describe ${REDIS_INSTANCE} --region=${REGION} --format='value(port)')

5. Set Up Serverless VPC Access Connector

gcloud compute networks vpc-access connectors create ${VPC_CONNECTOR} \
  --region=${REGION} \
  --network=${NETWORK} \
  --range=${VPC_CONNECTOR_RANGE}

This allows Cloud Run services to reach private resources like Cloud SQL and Redis.

6. Artifact Registry

gcloud artifacts repositories create ${REPO_BACKEND} \
  --repository-format=docker \
  --location=${ARTIFACT_REGION}

gcloud artifacts repositories create ${REPO_AI} \
  --repository-format=docker \
  --location=${ARTIFACT_REGION}

gcloud auth configure-docker ${ARTIFACT_REGION}-docker.pkg.dev

7. Build and Push Docker Images

Spring Boot Backend:

docker build -t ${BACKEND_IMAGE} -f backend/Dockerfile.cloudrun backend
docker push ${BACKEND_IMAGE}

FastAPI AI Service:

docker build -t ${AI_IMAGE} -f backend-ai/Dockerfile.cloudrun backend-ai
docker push ${AI_IMAGE}

8. Deploy on Cloud Run

Use VPC connector, Cloud SQL, and Secret Manager for secure connections.

Spring Boot Backend

gcloud run deploy ${SERVICE_BACKEND} \
  --image=${BACKEND_IMAGE} \
  --region=${REGION} \
  --platform=managed \
  --allow-unauthenticated \
  --min-instances=0 \
  --vpc-connector=${VPC_CONNECTOR} \
  --vpc-egress=all-traffic \
  --add-cloudsql-instances=${SQL_CONNECTION_NAME} \
  --set-env-vars=SPRING_PROFILES_ACTIVE=prod \
  --set-env-vars=CLOUD_SQL_CONNECTION_NAME=${SQL_CONNECTION_NAME} \
  --set-env-vars=SPRING_DATASOURCE_URL="jdbc:postgresql://${SQL_DB_BACKEND}?cloudSqlInstance=${SQL_CONNECTION_NAME}&socketFactory=com.google.cloud.sql.postgres.SocketFactory" \
  --set-env-vars=SPRING_DATASOURCE_USERNAME=${SQL_USER} \
  --set-secrets=SPRING_DATASOURCE_PASSWORD=sql-db-password:latest \
  --set-env-vars=SPRING_DATA_REDIS_HOST=${REDIS_HOST} \
  --set-env-vars=SPRING_DATA_REDIS_PORT=${REDIS_PORT} \
  --set-secrets=SPRING_CUSTOM_SECURITY_JWTSECRET=jwt-secret:latest

FastAPI AI Service

gcloud run deploy ${SERVICE_AI} \
  --image=${AI_IMAGE} \
  --region=${REGION} \
  --platform=managed \
  --allow-unauthenticated \
  --min-instances=0 \
  --vpc-connector=${VPC_CONNECTOR} \
  --vpc-egress=all-traffic \
  --add-cloudsql-instances=${SQL_CONNECTION_NAME} \
  --set-env-vars=DEBUG=False \
  --set-env-vars=DATABASE_URL="postgresql+psycopg2://${SQL_USER}:<from-secret>@/${SQL_DB_AI}?host=/cloudsql/${SQL_CONNECTION_NAME}" \
  --set-env-vars=REDIS_URL="redis://${REDIS_HOST}:${REDIS_PORT}/0" \
  --set-secrets=JWT_SECRET_KEY=jwt-secret:latest \
  --set-env-vars=JWT_ALGORITHM=HS256 \
  --set-env-vars=JWT_ACCESS_TOKEN_EXPIRE_MINUTES=60

Replace <from-secret> with Secret Manager reference.

9. CI/CD with Cloud Build

Automate builds and deployment using Cloud Build triggers on main branch.

Backend cloudbuild.yaml (template):

steps:
- name: gcr.io/cloud-builders/docker
  args: ['build','-t','${ARTIFACT_REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_BACKEND}/backend:$COMMIT_SHA','-f','backend/Dockerfile.cloudrun','backend']
- name: gcr.io/cloud-builders/docker
  args: ['push','${ARTIFACT_REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_BACKEND}/backend:$COMMIT_SHA']
- name: gcr.io/google.com/cloudsdktool/cloud-sdk
  entrypoint: gcloud
  args: ['run','deploy','backend','--image','${ARTIFACT_REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_BACKEND}/backend:$COMMIT_SHA','--region','${REGION}','--platform','managed']
options:
  logging: CLOUD_LOGGING_ONLY
timeout: '1200s'

AI cloudbuild.yaml (template):

steps:
- name: gcr.io/cloud-builders/docker
  args: ['build','-t','${ARTIFACT_REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_AI}/ai:$COMMIT_SHA','-f','backend-ai/Dockerfile.cloudrun','backend-ai']
- name: gcr.io/cloud-builders/docker
  args: ['push','${ARTIFACT_REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_AI}/ai:$COMMIT_SHA']
- name: gcr.io/google.com/cloudsdktool/cloud-sdk
  entrypoint: gcloud
  args: ['run','deploy','ai','--image','${ARTIFACT_REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_AI}/ai:$COMMIT_SHA','--region','${REGION}','--platform','managed']
options:
  logging: CLOUD_LOGGING_ONLY
timeout: '1200s'

Ensure the Cloud Build service account has access to Artifact Registry and Cloud Run.

Create a Cloud Build trigger

Create a GitHub-based trigger that runs on main and uses your cloudbuild.yaml:

gcloud beta builds triggers create github \
  --name="polyglot-deploy" \
  --repo-owner="GITHUB_OWNER" \
  --repo-name="GITHUB_REPO" \
  --branch-pattern="^main$" \
  --build-config="cloudbuild.yaml" \
  --substitutions=_REGION=${REGION},_ARTIFACT_REGION=${ARTIFACT_REGION},_REPO_BACKEND=${REPO_BACKEND},_REPO_AI=${REPO_AI}

10. Best Practices

Use Secret Manager for DB passwords, JWTs, API keys.
Prefer Private IP for Cloud SQL and Redis; connect via VPC connector.
Lock down Cloud Run ingress and enforce IAM roles.
Tune min/max instances and concurrency to balance cost and cold starts.
Monitor using Cloud Logging and Cloud Monitoring dashboards.

With this setup, you have a scalable, secure, and production-ready polyglot deployment with CI/CD and private networking. Both Java and Python services can now run efficiently on GCP serverless infrastructure.

Cloud HPC: How Google Scales High-Performance Computing

Majedul Islam — Sun, 28 Sep 2025 12:59:45 +0000

Cloud HPC: How Google Scales High-Performance Computing

When you think of Google Cloud, the first thing that comes to mind is usually hosting apps, databases, or analytics. But behind the scenes, Google runs some of the most advanced high-performance computing (HPC) clusters in the world. These clusters power everything from AI training to scientific simulations, using a mix of CPUs, GPUs, and custom TPUs.

In this post, we’ll break down how Google Cloud’s architecture works at scale, why different workloads need different hardware, and what it means for performance and sustainability.

From CPUs to Specialized Accelerators

The days of relying solely on CPUs are long gone. Modern cloud platforms mix different types of hardware, each optimized for different workloads:

CPUs – General-purpose workhorses. Google’s C4 machine types scale up to 288 vCPUs and ~2.2 TB DDR5 RAM, with NVMe SSDs (up to 18 TiB) for scratch storage. They are best for request-heavy services, analytics, and orchestration tasks.
GPUs – Built for massive data-parallelism. GCP offers A2 instances with up to 16× NVIDIA A100s (40/80 GB HBM2e) or A3 instances with H100/H200 GPUs. NVLink/NVSwitch interconnects provide intra-node bandwidth, while RoCE NICs deliver 100–400 Gbps for multi-node HPC jobs.
TPUs – Google’s custom ASICs. A TPU v3 chip contains two 128×128 systolic arrays of MAC units plus 32 GB of on-chip HBM. At cluster scale, a TPU v4 pod has 4096 chips (~1.1 exaFLOPS bf16), while TPU v5p pods scale to 8960 chips with 95 GB each (~4.1 exaFLOPS).

This spectrum of compute nodes allows workloads to be mapped to the most suitable hardware instead of relying on a one-size-fits-all processor.

Hardware at a Glance

Node Type	Specs	Networking	Best For
CPU Node	Up to 288 vCPUs, 2.2 TB DDR5, NVMe SSD	25–100 Gbps NICs	Web services, orchestration, control plane, analytics
GPU Node	1–16 GPUs (A100/H100/H200), 40–80 GB HBM per GPU	NVLink/NVSwitch + RoCE (100–400 Gbps)	ML training, HPC simulations, CUDA/OpenCL workloads
TPU Pod	4096–8960 TPU chips (32–95 GB HBM2e each)	Custom 3D torus (4800 Gbps links) + PCIe host	Large-scale deep learning (TensorFlow/XLA)

Networking at Scale: Google’s Jupiter Fabric

Fast accelerators alone aren’t enough — interconnect bandwidth is the real bottleneck in distributed HPC.

Google’s Jupiter fabric solves this with multi-petabit per second bisection bandwidth, enabling:

All-reduce operations for deep learning training with minimal synchronization overhead.
MPI scaling for tightly-coupled scientific simulations (e.g., CFD, weather modeling).
Dataflow workloads (MapReduce, Spark, Dataflow) that rely on shuffling massive datasets.

By minimizing tail latency, Jupiter allows CPUs, GPUs, and TPUs to communicate at speeds impossible with commodity Ethernet.

Trade-Offs: Throughput vs. Latency

Google’s heterogeneous design reflects workload trade-offs:

Throughput-focused workloads (training GPT-style models or running large HPC simulations) thrive on batch parallelism with GPUs/TPUs. However, the overhead of distributing data can raise latency.
Latency-sensitive workloads (search queries, request routing, API responses) map better to CPUs, which can respond in microseconds without batch setup.

This balance highlights the principle: use TPUs/GPUs when FLOPS/watt is the goal, CPUs when milliseconds matter.

The Energy Challenge

Pushing HPC to exascale introduces energy and cooling challenges:

Rack density – AI racks today draw 30–100 kW each, often requiring liquid cooling.
Cooling overhead – Cooling consumes 40–50% of data center power if unmanaged.
Carbon footprint – Global data centers consume ~2% of electricity, projected to double by 2030.

Google mitigates this by:

Running with an industry-leading PUE ≈ 1.10 vs. ~1.58 average.
Making TPUs 67% more energy-efficient per chip than previous generations.
Committing to 24/7 carbon-free energy by 2030, aligning compute growth with renewables.

This ensures scaling to exaFLOP-level compute doesn’t scale emissions at the same rate.

Cloud HPC Architecture Diagram

Since Dev.to doesn’t natively render Mermaid diagrams, here’s the architecture as an embedded image:

Why This Matters

For developers and researchers, Google Cloud’s HPC design offers:

Faster training and simulations by matching workloads to the right hardware.
Lower latency services thanks to CPU-optimized nodes.
Better cost efficiency by reducing wasted compute cycles.
A greener footprint through efficient chips and renewable energy.

Under the hood:

Schedulers (Borg/Kubernetes) dynamically allocate jobs to CPUs, GPUs, or TPUs, ensuring utilization without starving latency-sensitive tasks.
Memory hierarchy (DDR5 vs. GPU HBM vs. TPU HBM2e) is optimized for bandwidth, not just capacity.
Topology-aware placement ensures data-parallel jobs run on nodes physically closer in the Jupiter network, reducing cross-rack congestion.
Elastic scaling lets users spin up single VMs or entire TPU pods with APIs that abstract parallelism complexity.

Final Thoughts

Cloud HPC may sound like something only AI labs and scientists care about, but the reality is it underpins much of the technology we use every day.

Whether it’s smarter search results, real-time translation, or massive generative AI training runs, the infrastructure Google builds affects millions of users worldwide.

For engineers, the takeaways are clear:

Heterogeneous compute will only grow — CPUs, GPUs, TPUs, and new accelerators (genomics, video codecs, even quantum).
Energy-aware orchestration will be as important as performance in the coming decade.
Networking fabrics like Jupiter redefine what’s possible at datacenter scale — bandwidth is as critical as FLOPS.
Domain-specific hardware (like TPUs) shows that specialization beats general-purpose silicon at hyperscale.

As cloud providers race toward exascale and beyond, staying current with these architectures is key — not just for researchers but for any developer building applications that rely on scalable, efficient compute.

Polyglot Dockerization: Java + Python + Vue in Local and Production

Majedul Islam — Wed, 24 Sep 2025 18:14:08 +0000

Polyglot Dockerization: Java + Python + Vue in Local and Production

Why these services: A polyglot stack where Spring Boot powers core business workflows, FastAPI powers AI/RAG, and Vue powers the frontend.
Why dockerization matters: Containers keep Java, Python, and Node toolchains consistent everywhere, eliminating cross-language environment drift.
Two goals: (1) frictionless local development with one command, (2) production-grade images and configuration for reliable deploys.

Keep secrets and configuration in .env files. Compose reads values like POSTGRES_PASSWORD, JWT_SECRET, GOOGLE_API_KEY, etc., from a local .env placed next to docker-compose.yml.

Local Dockerization with Docker Compose

Spring Boot service

Dockerfile (multi-stage: build with Maven, run on JRE):

# ---------- Build stage ----------
FROM maven:3.9-eclipse-temurin-21 AS builder
WORKDIR /workspace/legalconnect

# Copy Maven wrapper and pom.xml first for better caching
COPY legalconnect/mvnw legalconnect/mvnw.cmd ./
COPY legalconnect/.mvn ./.mvn
COPY legalconnect/pom.xml ./

# Download dependencies
RUN ./mvnw dependency:go-offline -B

# Copy source code and build
COPY legalconnect/src ./src
RUN ./mvnw clean package -DskipTests -B

# ---------- Runtime stage ----------
FROM eclipse-temurin:21-jre-alpine
WORKDIR /app

# Non-root user + logs dir
RUN addgroup -g 1001 -S spring && adduser -S spring -u 1001 \
    && mkdir -p /app/logs && chown -R spring:spring /app

# Copy fat jar
COPY --from=builder /workspace/legalconnect/target/legalconnect-0.0.1-SNAPSHOT.jar /app/app.jar
RUN chown spring:spring /app/app.jar
USER spring

ENV JAVA_OPTS="-Xms512m -Xmx1024m -XX:+UseG1GC -XX:+UseContainerSupport"
ENV SERVER_PORT=8080
EXPOSE 8080
ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar /app/app.jar"]

FastAPI service

Dockerfile (Python slim base, pinned requirements, uvicorn):

FROM python:3.12-slim
WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir --upgrade pip \
    && pip install --no-cache-dir -r requirements.txt

COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Frontend (Vue) service

Dockerfile (build with Node 22, serve static with serve):

# ---- Build stage ----
FROM node:22-alpine AS builder
WORKDIR /app

# Install deps first (better layer caching)
COPY package*.json ./
RUN npm ci

# Copy source
COPY . .

# Accept build-time envs for Vite
ARG VITE_API_BASE_URL
ARG VITE_AI_CHAT_BASE_URL
ARG VITE_JAAS_URL
ARG VITE_JITSI_APP_ID
ENV VITE_API_BASE_URL=${VITE_API_BASE_URL}
ENV VITE_AI_CHAT_BASE_URL=${VITE_AI_CHAT_BASE_URL}
ENV VITE_JAAS_URL=${VITE_JAAS_URL}
ENV VITE_JITSI_APP_ID=${VITE_JITSI_APP_ID}

# Build
RUN npm run build

# ---- Runtime stage (serve) ----
FROM node:22-alpine
WORKDIR /app

ENV NODE_ENV=production
RUN npm i -g serve@14
COPY --from=builder /app/dist /app

# Use port 5173 to match development server
ENV PORT=5173
EXPOSE 5173

# Bind to 0.0.0.0 and use port 5173
CMD ["sh","-c","serve -s /app -l tcp://0.0.0.0:${PORT}"]

docker-compose.yml (all services)

One Compose file orchestrates everything locally: Postgres, Redis, Elasticsearch, Spring Boot, FastAPI, and the frontend. Services depend on each other with health checks. Environment variables are injected from .env.

services:
  postgres:
    image: postgres:17.5
    environment:
      - POSTGRES_DB=${POSTGRES_DB:-legalconnect}
      - POSTGRES_USER=${POSTGRES_USER:-root}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    ports: ["5432:5432"]
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./backend/legalconnect/src/main/resources/quartz_tables.sql:/docker-entrypoint-initdb.d/10_quartz.sql:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-root} -d ${POSTGRES_DB:-legalconnect}"]

  redis:
    image: redis:7
    command: ["redis-server", "--appendonly", "yes"]
    ports: ["6379:6379"]
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]

  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:9.1.1
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
      - ES_JAVA_OPTS=-Xms512m -Xmx512m
    ports: ["9200:9200"]

  backend:
    build: { context: ./backend, dockerfile: Dockerfile }
    environment:
      - SPRING_DATASOURCE_URL=jdbc:postgresql://postgres:5432/${POSTGRES_DB:-legalconnect}
      - SPRING_DATASOURCE_USERNAME=${POSTGRES_USER:-root}
      - SPRING_DATASOURCE_PASSWORD=${POSTGRES_PASSWORD}
      - SPRING_DATA_REDIS_HOST=redis
      - SPRING_DATA_REDIS_PORT=6379
      - SPRING_ELASTICSEARCH_URIS=http://elasticsearch:9200
      - SPRING_CUSTOM_SECURITY_JWTSECRET=${JWT_SECRET}
      - FRONTEND_URL=${FRONTEND_URL:-http://localhost:5173}
    ports: ["8080:8080"]
    depends_on:
      postgres: { condition: service_healthy }
      redis: { condition: service_healthy }
      elasticsearch: { condition: service_healthy }

  backend-ai:
    build: { context: ./backend-ai, dockerfile: Dockerfile }
    environment:
      - DATABASE_URL=postgresql://${POSTGRES_USER:-root}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-legalconnect}
      - REDIS_URL=redis://redis:6379/0
      - QDRANT_URL=${QDRANT_URL}
      - QDRANT_API_KEY=${QDRANT_API_KEY}
      - QDRANT_COLLECTION_NAME=${QDRANT_COLLECTION_NAME}
      - GOOGLE_API_KEY=${GOOGLE_API_KEY}
      - JWT_SECRET_KEY=${JWT_SECRET}
    ports: ["8000:8000"]
    depends_on:
      postgres: { condition: service_healthy }
      redis: { condition: service_healthy }

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
      args:
        - VITE_API_BASE_URL=${VITE_API_BASE_URL:-http://localhost:8080/v1}
        - VITE_AI_CHAT_BASE_URL=${VITE_AI_CHAT_BASE_URL:-http://localhost:8000/api/v1}
    ports: ["5173:5173"]

volumes:
  postgres_data: {}

What this compose does
- Brings up stateful services (Postgres, Redis, Elasticsearch) first, then app services.
- Uses container DNS for internal networking (postgres, redis, elasticsearch).
- Exposes only required ports to the host, keeping service internals private.
- Injects configuration via .env and built-in defaults for quick start.
Benefits: One command (docker compose up -d) to bring the entire stack up; reproducible environments; isolated dependencies; easy resets via volumes.
Challenges: Service-to-service networking (use container names like postgres, redis); managing env vars across services (centralize in .env); ensuring startup order (use depends_on + health checks); volume mounts for logs/data; port collisions.

Run Only One Backend (single-service Compose files)

Sometimes you need to run just one backend service for focused development.

Spring Boot only (backend/docker-compose.yml):

authors-note: run only Spring Boot with Postgres/Redis locally
services:
  db:
    image: postgres:17.5
    environment:
      - POSTGRES_DB=${POSTGRES_DB:-legalconnect}
      - POSTGRES_USER=${POSTGRES_USER:-root}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    ports: ["5432:5432"]
  redis:
    image: redis:7
    ports: ["6379:6379"]
  backend:
    image: maven:3.9-eclipse-temurin-21
    working_dir: /workspace/backend/legalconnect
    command: ./mvnw spring-boot:run
    environment:
      - SPRING_DATASOURCE_URL=jdbc:postgresql://db:5432/${POSTGRES_DB:-legalconnect}
      - SPRING_DATASOURCE_USERNAME=${POSTGRES_USER:-root}
      - SPRING_DATASOURCE_PASSWORD=${POSTGRES_PASSWORD}
      - SPRING_DATA_REDIS_HOST=redis
      - SPRING_DATA_REDIS_PORT=6379
    volumes:
      - ./legalconnect:/workspace/backend/legalconnect
      - ~/.m2:/root/.m2
    ports: ["8080:8080"]
    depends_on:
      db: { condition: service_started }
      redis: { condition: service_started }

What this compose does
- Runs Spring Boot directly via Maven wrapper inside the container for fast feedback.
- Mounts your project folder and local Maven cache for quick rebuilds.
- Provides local Postgres + Redis with simple default credentials.
FastAPI only (backend-ai/docker-compose.yml):

authors-note: run only FastAPI with Postgres/Redis locally
services:
  db:
    image: postgres:17.5
    environment:
      - POSTGRES_DB=${POSTGRES_DB:-legal_connect_db}
      - POSTGRES_USER=${POSTGRES_USER:-legal}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    ports: ["5432:5432"]
  redis:
    image: redis:7
    ports: ["6379:6379"]
  fastapi-app:
    build: { context: ., dockerfile: Dockerfile }
    environment:
      - DATABASE_URL=postgresql://${POSTGRES_USER:-legal}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB:-legal_connect_db}
      - REDIS_URL=redis://redis:6379/0
    ports: ["8000:8000"]
    depends_on:
      db: { condition: service_started }
      redis: { condition: service_started }

What this compose does
- Builds your FastAPI app image and runs it with DB/Redis dependencies.
- Uses the standard DATABASE_URL/REDIS_URL patterns for twelve-factor configuration.
- Exposes only the FastAPI port to your host for API testing.

How to run locally

1) Prepare environment

Keep you environment variables and secrets (DB password, JWT secrets, API keys) in a .env file.
Ensure no local services are occupying ports: 5432, 6379, 9200, 8080, 8000, 5173. Stop them or free ports.

2) Run the full stack

Build and start: docker compose up -d --build
Check health: docker compose ps and docker compose logs -f backend backend-ai frontend
App URLs: backend http://localhost:8080, AI http://localhost:8000, frontend http://localhost:5173

3) Run only one backend

Spring Boot only: docker compose -f backend/docker-compose.yml up -d
FastAPI only: docker compose -f backend-ai/docker-compose.yml up -d

4) Tear down and reset

Stop: docker compose down
Stop + remove volumes (DB reset): docker compose down -v

Production Dockerization

Spring Boot optimized Dockerfile (multi-stage, smaller image)

# Build stage
FROM maven:3.9-eclipse-temurin-21 AS builder
WORKDIR /workspace/legalconnect
COPY legalconnect/mvnw legalconnect/mvnw.cmd ./
COPY legalconnect/.mvn ./.mvn
COPY legalconnect/pom.xml ./
RUN ./mvnw dependency:go-offline -B
COPY legalconnect/src ./src
RUN ./mvnw clean package -DskipTests -B

# Runtime stage
FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
RUN addgroup -g 1001 -S spring && adduser -S spring -u 1001 \
    && mkdir -p /app/logs && chown -R spring:spring /app
COPY --from=builder /workspace/legalconnect/target/legalconnect-0.0.1-SNAPSHOT.jar /app/app.jar
USER spring
ENV SPRING_PROFILES_ACTIVE=prod
ENV JAVA_OPTS="-XX:+UseContainerSupport -XX:MaxRAMPercentage=75.0 -XX:+UseG1GC -XX:+UseStringDeduplication"
ENV PORT=8080
EXPOSE 8080
ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -Dserver.port=$PORT -jar /app/app.jar"]

FastAPI optimized Dockerfile (lightweight base, non-root, healthcheck)

FROM python:3.12-slim
WORKDIR /app

RUN apt-get update && apt-get install -y gcc g++ \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --no-cache-dir --upgrade pip \
    && pip install --no-cache-dir -r requirements.txt

COPY . .
RUN groupadd -r appuser && useradd -r -g appuser appuser \
    && mkdir -p /app/logs /app/bdcode_json \
    && chown -R appuser:appuser /app
USER appuser

ENV PYTHONPATH=/app
ENV PYTHONUNBUFFERED=1
ENV PYTHONDONTWRITEBYTECODE=1
ENV PORT=8000
EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD python -c "import requests; requests.get('http://localhost:$PORT/health')" || exit 1

CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port $PORT --workers 1"]

Config differences vs local: In production, deploy images directly (Cloud Run/Kubernetes). Prefer managed services: Cloud SQL (Postgres), Memorystore (Redis), Elastic Cloud. Service discovery and autoscaling are handled by the platform.
Handling env vars + secrets: Use Secret Manager/Key Vault and runtime env vars. Keep .env for local only; mirror variable names across environments for parity.

Comparing Local vs Prod Setup

Service	Local	Production
Spring Boot	Compose + Postgres/Redis/Elasticsearch	Multi-stage image, managed Postgres (Cloud SQL), managed Redis (Memorystore), Elastic Cloud
FastAPI	Compose + Postgres + Redis	Lightweight image, managed Postgres/Redis, scale-to-zero via Cloud Run
Frontend	Compose-built image (Vite args)	Static hosting or container image served behind CDN
Config	`.env` + docker compose	Secret manager + platform env vars
Networking	Container DNS names (`postgres`, `redis`)	Platform service URLs, VPC connectors if needed

Potential Issues to Watch For

Port conflicts: Stop anything already running on 5432 (Postgres), 6379 (Redis), 9200 (Elasticsearch), 8080 (Spring), 8000 (FastAPI), 5173 (Frontend). Use lsof -i :PORT or sudo fuser -k PORT/tcp to free ports.
Stale volumes/config: Remove volumes when schema or config changes: docker compose down -v.
Env var drift: Missing .env keys cause startup errors (DB auth, JWT, API keys). Keep sample .env.example in sync.
Service startup race: Ensure DB/Redis are healthy before app starts (health checks + depends_on).
Memory limits: Elasticsearch can fail on low memory; adjust ES_JAVA_OPTS or allocate more resources.
File permissions: Volume-mounted logs or cache dirs may need proper ownership for non-root users.
Networking visibility: Containers resolve by service name (e.g., postgres); don’t use localhost from inside containers.

Lessons Learned

Image size optimization: Multi-stage builds; slim base images; --no-cache-dir; remove build tools from runtime.
Isolate configs per environment: Same variable names across .env, CI/CD, and prod reduce drift.
FastAPI vs Spring Boot: Python starts fast and is small; JVM needs warm-up but offers strong concurrency and tooling.
Debug container networking: Use container names, verify health checks, confirm exposed ports, and tail logs with docker compose logs -f.

Dockerizing a polyglot stack ensures reliable, reproducible environments end-to-end. With Compose locally and optimized images for production, we can iterate quickly and deploy confidently. Next up: deploying both services on Cloud Run with a CI/CD pipeline that builds, scans, and rolls out images automatically.

Tip: Keep sensitive values in .env locally and in a secret manager in production. Validate required vars early and fail fast when missing.