Merge develop into main

.env.sample

@@ -9,3 +9,16 @@ HOST_NAME=umil.linkedmusic.ca
 POSTGRES_DB=virtual_instrument_museum
 #POSTGRES_USER=ADD USER HERE
 #POSTGRES_PASSWORD=ADD PASSWORD HERE
+
+# TEST DATABASE
+TEST_POSTGRES_DB=vim_test_db
+TEST_POSTGRES_USER=test_user
+TEST_POSTGRES_PASSWORD=test_password
+
+## EMAIL ##
+# PROD MODE ONLY
+# EMAIL_HOST=
+# EMAIL_PORT=
+# EMAIL_HOST_USER=
+# EMAIL_HOST_PASSWORD=
+# DEFAULT_FROM_EMAIL=

.github/workflows/auto_release.yml

@@ -0,0 +1,24 @@
+name: Auto Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Semantic Release
+        uses: cycjimmy/semantic-release-action@v4
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          extra_plugins: |
+            @semantic-release/changelog
+            @semantic-release/git

.github/workflows/cd_prod.yml

@@ -1,13 +1,24 @@
 name: Deploy to Production Server
-on: workflow_dispatch
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version to deploy (e.g., v1.0.0). Leave empty for latest main."
+        required: false
+        type: string
 
 concurrency:
   group: production
-  cancel-in-progress: true
+  cancel-in-progress: false # In prod, queue the deployment if multiple are requested
 
 jobs:
   deploy-production:
     runs-on: ubuntu-latest
+    env:
+      DEPLOY_VERSION: ${{ github.event.inputs.version || github.event.release.tag_name || 'main' }}
     steps:
       - name: Checkout the current repo
         uses: actions/checkout@v5
@@ -16,30 +27,77 @@ jobs:
         with:
           key: ${{ secrets.KEY }}
           known_hosts: ${{ secrets.KNOWN_HOSTS }}
-      - name: Stop the current Docker containers running
+      - name: Validate deploy version input
+        run: |
+          set -euo pipefail
+          if [[ "$DEPLOY_VERSION" == "main" ]]; then
+            echo "SAFE_DEPLOY_VERSION=$DEPLOY_VERSION" >> "$GITHUB_ENV"
+            exit 0
+          fi
+          if [[ "$DEPLOY_VERSION" =~ ^v[0-9]+(\.[0-9]+){2}(-[0-9A-Za-z.-]+)?$ ]]; then
+            echo "SAFE_DEPLOY_VERSION=$DEPLOY_VERSION" >> "$GITHUB_ENV"
+            exit 0
+          fi
+          if [[ "$DEPLOY_VERSION" =~ ^[0-9a-f]{7,40}$ ]]; then
+            echo "SAFE_DEPLOY_VERSION=$DEPLOY_VERSION" >> "$GITHUB_ENV"
+            exit 0
+          fi
+          echo "::error::Invalid deploy version format: $DEPLOY_VERSION"
+          exit 1
+      - name: Record current deployed version for rollback
         run: |
           ssh -J ${{ secrets.PROXY_USERNAME }}@${{ secrets.PROXY_HOST1 }},${{ secrets.PROXY_USERNAME }}@${{ secrets.PROXY_HOST_PROD }} ${{ secrets.USERNAME }}@${{ secrets.HOST_PROD }} \
             "cd /virtual-instrument-museum &&
-             sudo docker compose stop"
-      - name: Fetch new updates from remote `origin` and log current branches
+             sudo bash -c 'CURRENT_VERSION=\$(git describe --tags --exact-match 2>/dev/null || git rev-parse HEAD); echo \"\$CURRENT_VERSION\" > /virtual-instrument-museum/.last_deployed'"
+      - name: Fetch updates and validate target version
         run: |
           ssh -J ${{ secrets.PROXY_USERNAME }}@${{ secrets.PROXY_HOST1 }},${{ secrets.PROXY_USERNAME }}@${{ secrets.PROXY_HOST_PROD }} ${{ secrets.USERNAME }}@${{ secrets.HOST_PROD }} \
-            "cd /virtual-instrument-museum &&
-             sudo git fetch origin -v &&
-             sudo git branch -v"
-      - name: Checkout to `main` branch and pull new changes 
+            "set -euo pipefail;
+             VERSION=\"${SAFE_DEPLOY_VERSION}\";
+             cd /virtual-instrument-museum;
+             sudo git fetch origin -v --tags;
+             if [ \"\$VERSION\" != 'main' ]; then
+               if ! sudo git rev-parse --verify --quiet \"\$VERSION^{commit}\" >/dev/null; then
+                 echo \"::error::Invalid deploy version: \$VERSION\";
+                 exit 1;
+               fi;
+             fi"
+      - name: Stop the current Docker containers running
         run: |
           ssh -J ${{ secrets.PROXY_USERNAME }}@${{ secrets.PROXY_HOST1 }},${{ secrets.PROXY_USERNAME }}@${{ secrets.PROXY_HOST_PROD }} ${{ secrets.USERNAME }}@${{ secrets.HOST_PROD }} \
             "cd /virtual-instrument-museum &&
-             sudo git checkout main &&
-             sudo git pull origin main"
-      - name: Build docker images
+             sudo docker compose stop"
+      - name: Deploy target version
+        id: deploy_target
+        continue-on-error: true
         run: |
           ssh -J ${{ secrets.PROXY_USERNAME }}@${{ secrets.PROXY_HOST1 }},${{ secrets.PROXY_USERNAME }}@${{ secrets.PROXY_HOST_PROD }} ${{ secrets.USERNAME }}@${{ secrets.HOST_PROD }} \
-            "cd /virtual-instrument-museum &&
-             sudo docker compose -f docker-compose-deployment.yml build --no-cache"
-      - name: Start the services
+            "set -euo pipefail;
+             VERSION=\"${SAFE_DEPLOY_VERSION}\";
+             cd /virtual-instrument-museum;
+             sudo git checkout \"\$VERSION\";
+             if [ \"\$VERSION\" = 'main' ]; then sudo git pull origin main; fi;
+             sudo docker compose -f docker-compose-deployment.yml build --no-cache;
+             sudo docker compose -f docker-compose-deployment.yml up -d --wait --wait-timeout 180"
+      - name: Roll back to last deployed version
+        if: ${{ steps.deploy_target.outcome != 'success' }}
+        run: |
+          ssh -J ${{ secrets.PROXY_USERNAME }}@${{ secrets.PROXY_HOST1 }},${{ secrets.PROXY_USERNAME }}@${{ secrets.PROXY_HOST_PROD }} ${{ secrets.USERNAME }}@${{ secrets.HOST_PROD }} \
+            "set -euo pipefail;
+             cd /virtual-instrument-museum;
+             if [ ! -f /virtual-instrument-museum/.last_deployed ]; then
+               echo 'No rollback version found';
+               exit 1;
+             fi;
+             ROLLBACK_VERSION=\$(cat /virtual-instrument-museum/.last_deployed);
+             sudo git checkout \$ROLLBACK_VERSION;
+             sudo docker compose -f docker-compose-deployment.yml build --no-cache;
+             sudo docker compose -f docker-compose-deployment.yml up -d --wait --wait-timeout 180;
+             echo '::error::Rollback executed; marking workflow as failed.';
+             exit 1"
+      - name: Record successful deploy version
+        if: ${{ steps.deploy_target.outcome == 'success' }}
         run: |
           ssh -J ${{ secrets.PROXY_USERNAME }}@${{ secrets.PROXY_HOST1 }},${{ secrets.PROXY_USERNAME }}@${{ secrets.PROXY_HOST_PROD }} ${{ secrets.USERNAME }}@${{ secrets.HOST_PROD }} \
             "cd /virtual-instrument-museum &&
-             sudo docker compose -f docker-compose-deployment.yml up -d"
+             sudo bash -c 'CURRENT_VERSION=\$(git describe --tags --exact-match 2>/dev/null || git rev-parse HEAD); echo \"\$CURRENT_VERSION\" > /virtual-instrument-museum/.last_deployed; echo \"Deployed: \$CURRENT_VERSION\"'"

.github/workflows/ci_build_deployment.yml

@@ -2,17 +2,17 @@ name: CI - Test Docker build for deployment
 
 on:
   push:
-    branches: [ develop, main ]
+    branches: [develop, main]
   pull_request:
-    branches: [ develop ]
+    branches: [develop]
   workflow_dispatch:
 
 jobs:
   ci-build-deployment:
     runs-on: ubuntu-latest
     env:
       HOST_NAME: umil.linkedmusic.ca
-      DJANGO_SECRET_KEY:  ${{ secrets.CI_DJANGO_SECRET_KEY }}
+      DJANGO_SECRET_KEY: ${{ secrets.CI_DJANGO_SECRET_KEY }}
       POSTGRES_DB: virtual_instrument_museum
       POSTGRES_USER: ${{ secrets.CI_POSTGRES_USER }}
       POSTGRES_PASSWORD: ${{ secrets.CI_POSTGRES_PASSWORD }}
@@ -25,11 +25,11 @@ jobs:
         uses: docker/setup-compose-action@v1
         with:
           version: latest
-      
+
       - name: Build UMIL with Production compose file
         run: |
           docker compose -f docker-compose-deployment.yml build
-      
+
       - name: List built Docker images
         run: |
-          docker images
+          docker images

.github/workflows/e2e-tests.yml

@@ -0,0 +1,95 @@
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  e2e-tests:
+    name: Run E2E Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      # Step 1: Checkout the repository
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      # Step 2: Set up Node.js
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: web-app/frontend/package-lock.json
+
+      # Step 3: Install frontend dependencies
+      - name: Install dependencies
+        working-directory: web-app/frontend
+        run: npm ci
+
+      # Step 4: Install Playwright browsers
+      - name: Install Playwright Browsers
+        working-directory: web-app/frontend
+        run: npx playwright install --with-deps chromium firefox webkit
+
+      # Step 4.5: Build frontend assets
+      # Nginx mounts ./web-app/frontend/assets/ from the host,
+      # so we need to build assets BEFORE starting Docker containers.
+      # Otherwise CSS/JS won't load properly in tests.
+      - name: Build frontend assets
+        working-directory: web-app/frontend
+        run: |
+          npm run sass:build
+          npm run build
+          echo "Verifying build output..."
+          ls -la assets/css/ dist/
+          test -f dist/manifest.json || (echo "ERROR: manifest.json not found!" && exit 1)
+          test -d assets/css || (echo "ERROR: CSS directory not found!" && exit 1)
+
+      # Step 5: Create environment file for Docker Compose
+      - name: Create .env file
+        run: |
+          cat > .env << EOF
+          # Test Database Configuration
+          TEST_POSTGRES_DB=vim_test
+          TEST_POSTGRES_USER=vim_test_user
+          TEST_POSTGRES_PASSWORD=vim_test_password
+
+          # Application Configuration
+          HOST_NAME=localhost
+          DJANGO_SECRET_KEY=test-secret-key-for-ci-only-not-for-production
+          EOF
+
+      # Step 6: Start Docker Compose services and wait for healthchecks
+      - name: Start Docker Compose
+        run: docker compose -f docker-compose-test.yml up -d --wait
+
+      # Step 7: Check Docker services status
+      # - name: Check Docker services
+      #   run: docker compose -f docker-compose-test.yml ps
+
+      # Step 8: Run E2E tests
+      - name: Run Playwright tests
+        working-directory: web-app/frontend
+        run: npm run test:e2e
+
+      # Step 9: Upload Playwright report (on failure)
+      - name: Upload Playwright Report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: web-app/frontend/tests/playwright-report/
+          retention-days: 30
+
+      # Step 10: Upload test results (on failure)
+      - name: Upload Test Results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: web-app/frontend/tests/test-results/
+          retention-days: 30
+
+      # Step 11: Clean up - Stop and remove Docker containers
+      - name: Stop Docker Compose
+        if: always()
+        run: docker compose -f docker-compose-test.yml down -v

.github/workflows/frontend_tests.yml

@@ -0,0 +1,25 @@
+name: Frontend Tests
+on: [push, pull_request]
+
+jobs:
+  frontend-unit-tests:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: web-app/frontend/package-lock.json
+
+      - name: Install dependencies
+        working-directory: web-app/frontend
+        run: npm ci
+
+      - name: Run unit tests
+        working-directory: web-app/frontend
+        run: npm test

.github/workflows/python_format.yml

@@ -7,4 +7,4 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: psf/black@stable
+      - uses: psf/black@stable

.gitignore

@@ -111,3 +111,13 @@ venv
 web-app/frontend/dist/
 web-app/frontend/node_modules/
 web-app/frontend/assets/css/
+
+# Playwright test artifacts
+web-app/frontend/tests/.auth/
+web-app/frontend/tests/test-results/
+web-app/frontend/tests/playwright-report/
+
+# LLM
+.cursor/
+.claude/
+CLAUDE.md

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/psf/black
-    rev: 23.1a1
+    rev: 26.1.0
     hooks:
       - id: black
 
@@ -14,7 +14,9 @@ repos:
         require_serial: false
 
   - repo: https://github.com/djlint/djLint
-    rev: v1.34.1
+    rev: v1.36.4
     hooks:
       - id: djlint-reformat-django
+        args: [--configuration=.djlintrc]
       - id: djlint-django
+        args: [--configuration=.djlintrc]

.releaserc.json

@@ -0,0 +1,16 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["CHANGELOG.md"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    "@semantic-release/github"
+  ]
+}

Makefile

@@ -0,0 +1,6 @@
+# Frontend tests (Vitest)
+test-frontend:
+	docker compose exec app npm test --prefix /virtual-instrument-museum/frontend
+
+.PHONY: test-frontend
+