Spring Boot / Docker Deployment Diagnostic

If your Spring Boot application fails after a Docker, VPS, Nginx or CI/CD deployment, the fastest first step is usually not a call. It is a structured review of the evidence: logs, run command, Dockerfile, docker-compose.yml, environment mapping, CI output and the expected behavior.

This repository is a public proof-of-work sample for that workflow.

It shows how I handle focused Java/Spring Boot + Docker/DevOps troubleshooting from written scope, logs, configs, repository context and clear acceptance criteria.

This is not a production SaaS and not a client case. It is a proof-of-work repository for how I document, verify and hand off scoped technical work.

When This Is Useful

Use this as a reference if you have a small backend/deployment problem like:

• Spring Boot app starts locally but fails in Docker or on a VPS;
• Docker Compose service cannot reach PostgreSQL or another dependency;
• /health works locally but fails behind Nginx or a reverse proxy;
• deploy returns 500/502/504 and logs/configs need narrowing down;
• GitHub Actions or GitLab CI fails while local build works;
• environment variables, Spring profiles or ports are mapped incorrectly.

How I Work Async

Written symptom -> logs/config/repo review -> likely cause -> fix plan or PR -> verification commands -> handoff note

What I usually need:

• expected behavior and current symptom;
• exact command used to run or deploy;
• last 100-200 relevant log lines;
• Dockerfile, docker-compose.yml and .env.example without secrets;
• Spring profile and environment variable mapping;
• CI workflow output if build/deploy differs from local;
• Nginx/server config only if the issue is 502/504/reverse proxy related.

What you get back:

• written root-cause or narrowed-cause notes;
• assumptions and remaining risks;
• exact commands to verify the result;
• focused fix plan, PR/config patch option or next-scope quote;
• short runbook/handoff note.

Main Offer This Supports

Spring Boot / Docker / Deployment Diagnostic
EUR 150 fixed diagnostic, usually 1-2 business days after complete context.

Good fit:

• Spring Boot app does not start after deploy;
• Docker Compose mismatch or health check failure;
• CI build/test failure;
• unclear 500/502/504 deployment symptom;
• VPS/Nginx/PostgreSQL config issue that can be diagnosed from written context.

Typical deliverables:

• written root-cause report or narrowed-cause report;
• reviewed files/logs/config notes;
• exact verification commands;
• fix plan or PR/patch quote;
• short handoff/runbook note.

No call is required for well-scoped tasks. I work best from written requirements, logs, configs, repo context and reproducible commands.

Client Proof Map

What a client needs	Where this repo proves it
Fast overview of the working method	docs/client-facing-proof-summary.md
Clear async intake	docs/intake.md
Safe no-secret workflow	Security notes
Reproducible Spring Boot app	/health + source
Docker run path	Dockerfile + docker-compose.yml
CI build/test path	.github/workflows/ci.yml
Diagnostic reasoning style	simulated diagnostic case - not client work
Delivery handoff style	docs/sample-handoff-report.md
Verification discipline	docs/verification.md

Async Workflow

The delivery model is deliberately written and traceable:

Client context -> diagnostic checks -> written findings -> fix plan or PR -> handoff/runbook

Deployment Diagnostic Map

For unclear deployment issues, the first paid step is usually a written diagnostic. The goal is to turn scattered symptoms into reviewed evidence, likely causes, risks and a concrete next step.

Open the diagrams directly:

• Async delivery workflow
• Deployment diagnostic map
• Verification proof

Mini Handoff Preview

Reviewed: Dockerfile, docker-compose.yml, .env.example, startup logs, health check.
Found: app/container runtime contract was unclear; health endpoint failed from host.
Verified: app starts via Docker Compose, curl /health returns UP after startup.
Delivered: run commands, port-conflict notes, remaining risks and next fix option.
Next step: implement bounded config fix or continue with deeper app/database diagnostics.

What You Can Verify In 2 Minutes

docker compose up --build
curl http://localhost:8080/health
docker compose logs app
docker compose down

Expected health response:

{
  "status": "UP",
  "service": "no-call-demo"
}

Start Here

• Service menu
• Client-facing proof summary
• Client proof notes
• Async intake checklist
• Async delivery workflow
• Sample handoff report
• Simulated diagnostic case - not client work
• Verification notes

What This Demonstrates

This project is useful as a portfolio sample for:

• Spring Boot troubleshooting;
• Dockerfile and Docker Compose setup;
• GitHub Actions build/test workflow;
• backend/DevOps diagnostic handoff;
• documented delivery with verification commands.

Expected client deliverables for similar work:

• PR or patch with the fix/configuration;
• exact run and verification commands;
• short README/runbook update;
• notes about assumptions, risks, and next steps.

Tech Stack

• Java 17
• Spring Boot
• Maven
• Docker
• Docker Compose
• GitHub Actions

Project Contents

.
|-- .github/workflows/ci.yml
|-- .env.example
|-- Dockerfile
|-- SERVICES.md
|-- docker-compose.yml
|-- docs/
|   |-- assets/
|   |-- async-workflow.md
|   |-- client-proof.md
|   |-- intake.md
|   |-- sample-handoff-report.md
|   |-- verification.md
|   `-- cases/
|       `-- docker-compose-app-not-starting.md
|-- pom.xml
`-- src/

Key endpoint:

GET /health

Expected response:

{
  "service": "no-call-demo",
  "status": "UP"
}

JSON field order may differ depending on runtime serialization.

Run Locally Without Docker

Requirements:

• Java 17
• Maven 3.9+ or a compatible Maven version

Run tests:

mvn test

Start the application:

mvn spring-boot:run

Check the health endpoint:

curl http://localhost:8080/health

Run With Docker Compose

Build and start:

docker compose up --build

Check the health endpoint:

curl http://localhost:8080/health

Show logs:

docker compose logs -f app

Stop:

docker compose down

Environment Variables

Example configuration is stored in .env.example:

SERVER_PORT=8080
SPRING_PROFILES_ACTIVE=local

Do not store real secrets in .env.example, Git history, screenshots, issue comments, or pull requests.

CI Workflow

The GitHub Actions workflow runs on push to main and on pull requests:

.github/workflows/ci.yml

It checks out the repository, sets up Java 17, caches Maven dependencies, and runs:

mvn test

Troubleshooting Notes

Port 8080 Is Already In Use

For local Maven run:

SERVER_PORT=8081 mvn spring-boot:run

For Docker Compose, change the host port mapping in docker-compose.yml:

ports:
  - "8081:8080"

Docker Build Cannot Find The JAR

This Dockerfile builds the JAR inside the build stage. If you change artifactId or version in pom.xml, check the copied JAR path:

target/no-call-demo-0.1.0.jar

Health Endpoint Does Not Respond

Check the container state and logs:

docker compose ps
docker compose logs app
curl -v http://localhost:8080/health

Common causes:

• application did not start;
• wrong host port mapping;
• stale container after changing config;
• local firewall or another service using the same port.

Environment Variables Are Not Applied

Check that Docker Compose passes the variables through either env_file or environment:

env_file:
  - .env.example

For real client work, use a sanitized .env.example and keep actual secrets in the deployment platform, CI secret store, or server environment.

Security Notes

• Do not commit real secrets.
• Do not paste production .env files into issues or chat.
• Do not give clients access to your own infrastructure.
• Run unknown third-party repositories in an isolated VM/container, not on your main machine.
• This repository demonstrates backend/DevOps delivery style; it is not a formal security audit.

Verification Status

Verified with Docker Compose on 2026-05-14:

docker compose build --no-cache
docker compose up -d
docker compose ps
curl -sS http://localhost:8080/health
docker compose down

Expected health response:

{
  "status": "UP",
  "service": "no-call-demo"
}

Local mvn test was not run on the host machine because Maven CLI is not installed locally. The Docker build stage ran Maven tests inside the container image build.

See verification notes for the current verification checklist and test status.

How To Use This Repository

This repository can be linked from LinkedIn, Upwork, Malt, and GitHub profile sections as a compact proof of delivery style for small Java/Spring Boot + Docker/DevOps tasks.

Suggested context when sharing it:

This is a small public demo of my async delivery format for Spring Boot + Docker/DevOps tasks: intake checklist, health endpoint, Dockerfile, Docker Compose, .env.example, CI, sample handoff, simulated diagnostic case, and README/runbook with verification steps.