⬅️ Back to Architecture Index

Deployment Architecture & Operations

Overview

Smart Supply Pro backend deployment follows a fully automated, immutable infrastructure approach:

Source Code → Maven Build → Docker Image → Fly.io Production

Every commit to main triggers a streamlined pipeline that builds, tests, packages, and deploys the backend service automatically. This documentation explains each stage and the files involved.

Deployment Flow Diagram

Key Files & Folders

Build & Packaging

• pom.xml – Maven project configuration; defines dependencies, plugins, build steps
• Dockerfile – Multi-stage Docker build: compile stage → runtime stage
• start.sh – Container entrypoint script; launches Spring Boot app with environment variables

Infrastructure as Code

• fly.toml – Fly.io app configuration: machine size, regions, environment variables, secrets
• .github/workflows/ – GitHub Actions workflow files for CI/CD automation
  • 1-ci-test.yml – Build, test, Docker image, Trivy scan
  • 3-deploy-fly.yml – Deploy to Fly.io (automatic + manual options)
  • docs-pipeline.yml – Build API/architecture documentation

Configuration & Secrets

• .env.example – Template for local development environment variables
• /ops/nginx/ – Nginx configuration (reverse proxy, routing, TLS if applicable)
• /oracle_wallet/ – Oracle Wallet encrypted credentials (mounted at runtime)
• /lib/ojdbc11.jar – Oracle JDBC driver (included in Docker image)

Scripts & Utilities

• /scripts/ – Automation scripts:
  • build-openapi-docs.sh – Generate OpenAPI documentation from code
  • build-architecture-docs.sh – Convert architecture markdown to HTML
  • Various utility scripts for deployment and CI/CD

Deployment Architecture at a Glance

Pipeline Stages

1️⃣ CI Build & Test (1-ci-test.yml)

• Trigger: Push to main/develop
• Steps:
  1. Checkout code
  2. Set up JDK 17 + Maven cache
  3. Run mvn clean verify (compile, tests, integration tests)
  4. Generate JaCoCo coverage report
  5. Build Docker image (prod profile)
  6. Push to Docker Hub (tags: SHA + latest)
  7. Trivy security scan (blocks on HIGH/CRITICAL)
• Output: Immutable Docker image in registry, JaCoCo report artifact

2️⃣ Documentation Pipeline (docs-pipeline.yml)

• Trigger: After CI success OR docs-only push
• Steps:
  1. Download JaCoCo artifact from CI
  2. Generate OpenAPI docs (Swagger/ReDoc)
  3. Convert architecture markdown to HTML (Pandoc + Lua filter)
  4. Assemble docs-site artifact
• Output: docs-site artifact (consumed by 2-deploy-ghpages.yml)

2️⃣ Publish Docs to GitHub Pages (2-deploy-ghpages.yml)

• Trigger: After docs-pipeline success
• Steps:
  1. Checkout gh-pages branch
  2. Download docs-site artifact
  3. Preserve existing JaCoCo coverage (if not in current build)
  4. Commit and push to gh-pages
• Output: Live documentation at GitHub Pages

3️⃣ Deploy to Fly.io (3-deploy-fly.yml)

• Trigger: After CI success on main (automatic) OR manual via workflow_dispatch
• Steps:
  1. Validate Docker image exists in registry
  2. Verify Fly.io app exists
  3. Deploy using flyctl deploy --image <SHA>
  4. Poll /health endpoint (5-minute timeout)
  5. Run smoke tests (validate /health and / endpoints)
  6. Capture logs if health check fails
• Output: Running backend service at https://inventoryservice.fly.dev

Immutable Deployment Strategy

Every Docker image is tagged by commit SHA (e.g., ckbuzin/inventory-service:a1b2c3d4), enabling:

• Reproducible deployments – Same code always produces same image
• Easy rollback – Deploy previous commit SHA anytime
• Audit trail – Git history = deployment history
• No “latest” fragility – “latest” tag is convenience reference only

Environment Configuration

Spring Boot selects profile via SPRING_PROFILES_ACTIVE environment variable (set in fly.toml).

Key Documentation Files

This deployment documentation is organized as follows:

Core Deployment Guides

• Build & Docker Image – How backend is compiled and packaged
• CI/CD & Docs Pipeline – GitHub Actions automation and documentation generation
• Fly.io Infrastructure – Cloud hosting, regions, machine resources, scaling

Configuration & Networking

• Nginx & Routing – Reverse proxy configuration and request routing
• Environments & Secrets – Configuration management across environments
• Logs & Observability – Logging architecture and debugging

Quick Reference: From Commit to Production

Troubleshooting Quick Links

Related Documentation

• Architecture Overview – High-level system design and components
• Resources & Configuration – Application properties, Spring profiles, database config
• Backend Layers – Controller, Service, Repository architecture
• DevOps & Infrastructure – Container orchestration, CI/CD best practices

Last Updated: November 2025
Audience: DevOps engineers, backend developers, SRE, deployment operators