feat: Add CI/CD with Docker deployment and automated releases (#8)

toddeTV · web-flow · commit 5000adfc55d3 · 2025-10-07T13:27:04.000+02:00
diff --git a/.dockerignore b/.dockerignore
@@ -0,0 +1,32 @@
+# project specific
+data
+
+# Git
+.git
+.github
+.gitignore
+
+# Node
+node_modules
+
+# Build output
+.output
+.nuxt
+
+# IDE
+.vscode
+
+# Docs
+docs
+
+# Local files
+.env
+
+# Log files
+pnpm-debug.log*
+
+# Docker
+Dockerfile
+docker-compose.yml
+docker-build.sh
+.dockerignore
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -0,0 +1,76 @@
+name: Release and Publish
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
+      - name: Release Please Action
+        id: release
+        uses: google-github-actions/release-please-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          release-type: node
+
+  publish-docker-image:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            latest=auto
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -0,0 +1,3 @@
+{
+  ".": "1.0.0"
+}
diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1,51 @@
+# --- Build Stage ---
+# This stage builds the application. It installs all dependencies (including dev)
+# and creates the optimized production output in the /.output directory.
+FROM node:22-alpine AS build
+
+# Set working directory
+WORKDIR /app
+
+# Install pnpm version 10
+# Enable corepack and activate pnpm
+RUN corepack enable
+RUN corepack prepare pnpm@10 --activate
+
+# Copy package.json and pnpm-lock.yaml
+COPY package.json pnpm-lock.yaml ./
+
+# Install dependencies with caching
+RUN --mount=type=cache,id=pnpm-store,target=/root/.local/share/pnpm/store pnpm install --frozen-lockfile
+
+# Copy the rest of the application source code
+COPY . .
+
+# Build the application for production
+RUN pnpm build
+
+# --- Production Stage ---
+# This is the final, minimal image. It only copies the built application
+# from the 'build' stage and installs production-only dependencies.
+# No source code or development dependencies are included.
+FROM node:22-alpine AS production
+
+# Set working directory
+WORKDIR /app
+
+# Enable corepack and activate pnpm in production stage
+RUN corepack enable
+RUN corepack prepare pnpm@10 --activate
+
+# Copy the built output from the build stage
+COPY --from=build /app/.output ./.output
+
+# Copy production dependencies
+COPY --from=build /app/package.json ./
+COPY --from=build /app/pnpm-lock.yaml ./
+RUN pnpm install --prod --frozen-lockfile
+
+# Expose the port the app runs on
+EXPOSE 3000
+
+# Set the command to start the application
+CMD ["node", ".output/server/index.mjs"]
diff --git a/docker-build.sh b/docker-build.sh
@@ -0,0 +1,14 @@
+#!/bin/bash
+
+# Exit immediately if a command exits with a non-zero status.
+set -e
+
+# Define variables
+IMAGE_NAME="stage-flow-tools"
+DOCKERFILE="Dockerfile"
+
+# Build the Docker image
+echo "Building Docker image: $IMAGE_NAME..."
+docker build -t "$IMAGE_NAME" -f "$DOCKERFILE" .
+
+echo "Docker image '$IMAGE_NAME' built successfully."
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -0,0 +1,26 @@
+version: '3.9'
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: stage-flow-tools
+    container_name: stage-flow-tools
+    restart: unless-stopped
+    networks:
+      - traefik-public
+    volumes:
+      - ./data:/app/data
+    environment:
+      - NUXT_JWT_SECRET=${NUXT_JWT_SECRET}
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.stage-flow-tools.rule=Host(`quiz.your-domain.com`)"
+      - "traefik.http.routers.stage-flow-tools.entrypoints=websecure"
+      - "traefik.http.services.stage-flow-tools.loadbalancer.server.port=3000"
+      - "traefik.http.routers.stage-flow-tools.tls.certresolver=myresolver"
+
+networks:
+  traefik-public:
+    external: true
diff --git a/docs/deployment-docker.md b/docs/deployment-docker.md
@@ -0,0 +1,88 @@
+# Production Deployment with Docker
+
+This guide describes how to deploy the application to a production environment on a Linux server using Docker and Docker Compose.
+
+## Prerequisites
+
+- A Linux server with Docker and Docker Compose installed.
+- A Traefik reverse proxy instance running and configured on the same server.
+- The `traefik-public` Docker network must exist.
+- A domain or subdomain pointed to the server's IP address.
+
+## Setup
+
+### 1. Clone the Repository
+
+Connect to your server and clone the repository:
+
+```bash
+git clone <repository-url>
+cd stage-flow-tools
+```
+
+### 2. Configure Environment
+
+Copy the example environment file and customize it:
+
+```bash
+cp .env.example .env
+```
+
+Edit the `.env` file and set a strong, unique `NUXT_JWT_SECRET`. You can generate one with:
+
+```bash
+openssl rand -base64 48
+```
+
+### 3. Configure Docker Compose
+
+Open the `docker-compose.yml` file and update the Traefik `Host` rule to match your domain:
+
+```yaml
+services:
+  app:
+    # ...
+    labels:
+      - "traefik.http.routers.quiz-app.rule=Host(`quiz.your-domain.com`)" # Change this
+      # ...
+```
+
+### 4. Build and Start the Container
+
+Build the Docker image and start the container in detached mode:
+
+```bash
+docker compose up --build -d
+```
+
+The application will be accessible at your configured domain. Traefik will automatically handle SSL certificate provisioning via Let's Encrypt.
+
+## Data Persistence
+
+The `docker-compose.yml` file is configured to mount the local `./data` directory into the container at `/app/data`. This ensures that all application data (questions, answers, etc.) is persisted on the host machine, even if the container is removed or recreated.
+
+## Maintenance
+
+### Updating the Application
+
+To update the application to the latest version:
+
+```bash
+git pull
+docker compose up --build -d
+```
+
+### Viewing Logs
+
+To view the application logs:
+
+```bash
+docker compose logs -f
+```
+
+### Stopping the Application
+
+To stop the application:
+
+```bash
+docker compose down
diff --git a/docs/local-testing.md b/docs/local-testing.md
@@ -0,0 +1,44 @@
+# Local Docker Testing
+
+This guide provides minimal instructions for building and testing the Docker container locally. This process simulates the image creation step of the CI/CD workflow.
+
+## 1. Build the Docker Image
+
+Ensure the Docker daemon is running on your machine. Then, from the project root, execute the build script:
+
+```bash
+./docker-build.sh
+```
+
+This command builds the image and tags it as `stage-flow-tools`.
+
+## 2. Run the Container
+
+### Prerequisites
+
+Before running the container, make sure you have a `.env` file in your project root. If you don't have one, create it by copying the example file:
+
+```bash
+cp .env.example .env
+```
+
+Ensure the `NUXT_JWT_SECRET` and other variables are set correctly in this file.
+
+### Command
+
+To test the built image, run the following command. It mounts the local `.env` file and the `data` directory into the container.
+
+```bash
+docker run --rm -it \
+  -p 3000:3000 \
+  --env-file ./.env \
+  -v "$(pwd)/data:/app/data" \
+  --name test-stage-flow \
+  stage-flow-tools
+```
+
+The application will be available at `http://localhost:3000`. The container will be automatically removed when you stop it (`Ctrl+C`).
+
+### A Note on Versioning
+
+The local build script tags the image with `:latest`. The automated GitHub Actions workflow handles versioning for releases by automatically tagging the image with the correct semantic version (e.g., `1.2.3`, `1.2`, `1`) based on the release created by the `release-please` bot.
diff --git a/docs/release-flow.md b/docs/release-flow.md
@@ -0,0 +1,36 @@
+# Release Flow
+
+This document outlines the automated release process for the application, which is managed by GitHub Actions and the `release-please` bot.
+
+## Overview
+
+The release process is triggered automatically when commits are pushed to the `main` branch. It handles versioning, changelog generation, GitHub releases, and Docker image publishing.
+
+## Workflow
+
+### 1. Development
+
+Developers work on feature or fix branches and create pull requests to merge their changes into the `main` branch. Commit messages must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+
+### 2. Release Proposal
+
+After one or more pull requests are merged into `main`, the `release-please` GitHub Action runs automatically. It analyzes the commit history since the last release and determines the next semantic version number.
+
+If a new release is warranted, the bot creates a new pull request titled `chore(main): release [version]`. This PR includes:
+
+- An updated `CHANGELOG.md` file.
+- The new version number bumped in `package.json`.
+
+### 3. Human Approval
+
+A project maintainer reviews the release pull request. If everything is correct, the PR is merged into the `main` branch. This merge action is the trigger for the next step.
+
+### 4. Release and Publication
+
+Upon merging the release PR, the GitHub Actions workflow performs the following tasks:
+
+1. **Creates a GitHub Release**: A new release is created on GitHub with the tag `v[version]`. The release notes are populated from the `CHANGELOG.md`.
+2. **Builds Docker Image**: A new Docker image is built based on the state of the `main` branch at the release tag.
+3. **Pushes to Registry**: The Docker image is pushed to the GitHub Container Registry (`ghcr.io`) with tags corresponding to the release version (e.g., `1.2.3`, `1.2`, `1`, `latest`).
+
+The `main` branch is now updated with the latest version, and a new, versioned Docker image is available for deployment.
diff --git a/release-please-config.json b/release-please-config.json
