CI/CD Pipeline Documentation

This document explains the GitHub Actions workflows in this repository, how they run, the required secrets, and how deployments work. The workflows live in .github/workflows/ and the helper scripts are in .github/bash-scripts/.

Overview

Automated pipeline for building, testing, packaging, and deploying the application.

Stack: Java 21, Maven, PostgreSQL 16, Docker, GitHub Container Registry (GHCR).

High-level flow

PR → develop (CI) → merge to develop PR → master (CI) → on merge to master run Dockerize → Deploy

Workflows

CI (ci.yml)

• Triggers: pull requests to develop and master and pushes to develop.
• Runs JDK 21, starts PostgreSQL service (Postgres 16), and runs:

mvn -B clean verify

• Purpose: compile, run unit and integration tests, and fail fast on regressions.

Dockerize (docker.yml)

• Triggers: push/merge to master (or a tag depending on workflow config).
• Steps: run CI, build production Docker image, tag, and push to GHCR (ghcr.io/{owner}/{repo}/bitelo-api:latest).
• Requires: GHCR_TOKEN or GITHUB_TOKEN with packages:write permissions.

Deploy (deploy.yml)

• Triggers: manual or workflow run-on-success after Dockerize (see workflow file).
• Steps: SSH to production server and run the deployment script.
• The repo contains a helper deploy script at .github/bash-scripts/deploy.sh which can be used or copied to the server.

Deploy script and server setup

Recommended server location for deploy.sh: /opt/burgerman/deploy.sh (this is where the production server script is expected to live).

What deploy.sh typically does:

• Pull latest image from GHCR
• Create Docker network if missing
• Ensure PostgreSQL container exists/starts (persistent data volume)
• Stop old app container and start the new one on port 8080

Quick server bootstrap (run on the server):

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Create deployment directory
sudo mkdir -p /opt/burgerman
sudo chown $USER:$USER /opt/burgerman

# Place the deploy script and make it executable
chmod +x /opt/burgerman/deploy.sh

Required secrets (set in the repository Settings → Secrets and variables → Actions)

• DB_USER — PostgreSQL username used by containers or the app.
• DB_PASSWORD — PostgreSQL password.
• DB_DATABASE — Database name.
• GHCR_TOKEN — GitHub Package/Container Registry token (or use GITHUB_TOKEN with appropriate permissions).
• SERVER_HOST — Production server host/IP for SSH deploy.
• SERVER_USER — SSH username for deploy.
• SERVER_SSH_KEY — Private SSH key (set as ssh secret) for the deploy user.

Additional secrets may be required by the application itself (DB URL, JWT secrets, Cloudinary keys, Tron node RPC credentials). Keep those in the repository or environment-specific secret stores.

Development and local testing

Run the build and tests locally with Maven:

mvn clean verify

Build the Docker image locally:

docker build -t bitelo-api:local -f Dockerfile .

Troubleshooting

• PostgreSQL health checks fail: increase the startup timeout in the workflow or ensure the service image tag matches the workflow config.
• Docker push denied: confirm the token has packages:write and read:packages as required.
• SSH connection refused: validate SERVER_HOST, SERVER_USER, and SERVER_SSH_KEY values.
• Container won't start: inspect logs with docker logs <container>.

Useful commands on the server:

docker logs bitelo-api
docker logs bitelo-db
docker ps -a

To re-run deployment manually on the server:

ssh $SERVER_USER@$SERVER_HOST
cd /opt/burgerman
./deploy.sh

Where to look next

• Workflow files: .github/workflows/ci.yml, .github/workflows/docker.yml, .github/workflows/deploy.yml
• Deploy script: .github/bash-scripts/deploy.sh

If you want, I can:

• Generate a checklist of repository secrets from application.yml.
• Update the workflows to use a centralized deploy job with environment protection rules.