Skip to content

DEPLOYMENT.md

Latest commit

 

History

History
259 lines (187 loc) · 6.7 KB

DEPLOYMENT.md

File metadata and controls

259 lines (187 loc) · 6.7 KB

Deployment Guide

This guide provides step-by-step instructions for deploying the SophiaHackLab documentation site to GitHub Pages.

Prerequisites

  • Git repository pushed to GitHub: https://github.com/SophiaHackLab/docusaurus
  • GitHub account with write access to the repository
  • All files committed to the main branch

Deployment Steps

Step 1: Enable GitHub Pages

  1. Go to your repository on GitHub: https://github.com/SophiaHackLab/docusaurus
  2. Click on Settings tab
  3. In the left sidebar, click Pages
  4. Under Build and deployment:
    • Source: Select GitHub Actions
    • This enables the automated deployment workflow

Step 2: Push Changes to Main Branch

# Ensure you're on the main branch
git checkout main

# Add all files
git add .

# Commit with a descriptive message
git commit -m "Initial Docusaurus setup with CI/CD"

# Push to GitHub
git push origin main

Step 3: Monitor Deployment

  1. Go to the Actions tab in your repository

  2. You should see two workflows running:

    • Deploy to GitHub Pages - Builds and deploys the site
    • E2E Tests - Runs automated tests

  3. Click on each workflow to see the progress

  4. Wait for both to complete (usually 2-5 minutes)

Step 4: Verify Deployment

Once the deploy workflow completes successfully:

  1. Access the site: https://sophiahacklab.github.io/docusaurus/
  2. Verify:
    • Homepage loads correctly
    • Navigation works
    • Sidebar shows all projects
    • All project pages are accessible

GitHub Actions Workflows

Deploy Workflow (deploy.yml)

Triggers:

  • Automatic: Push to main branch
  • Manual: Workflow dispatch button in Actions tab

What it does:

  1. Checks out code
  2. Sets up Node.js 20
  3. Installs dependencies
  4. Builds Docusaurus (with GitHub Pages base URL)
  5. Uploads build artifact
  6. Deploys to GitHub Pages

Status Badge:

[![Deploy](https://github.com/SophiaHackLab/docusaurus/actions/workflows/deploy.yml/badge.svg)](https://github.com/SophiaHackLab/docusaurus/actions/workflows/deploy.yml)

Test Workflow (test.yml)

Triggers:

  • Push to main branch
  • Pull requests to main branch
  • Manual: Workflow dispatch button

What it does:

  1. Checks out code
  2. Sets up Node.js 20 and Playwright
  3. Installs dependencies
  4. Builds and serves Docusaurus locally
  5. Runs 69 tests across 3 browsers (207 total test executions)
  6. Generates JUnit XML and HTML reports
  7. Uploads test artifacts (available for 30 days)

Status Badge:

[![Tests](https://github.com/SophiaHackLab/docusaurus/actions/workflows/test.yml/badge.svg)](https://github.com/SophiaHackLab/docusaurus/actions/workflows/test.yml)

Local Testing Before Deployment

Always test locally before pushing:

# Run full test suite (build + serve + test + report)
npm run test:local

# Or run tests individually
npm run build          # Build site
npm run serve &        # Serve in background
npm run test:e2e       # Run tests
npm run test:report    # View HTML report

Troubleshooting

Deployment Fails

Problem: Deploy workflow shows errors

Solutions:

  1. Check workflow logs in Actions tab
  2. Verify all files are committed
  3. Ensure docusaurus.config.ts has correct settings
  4. Check Node.js version in workflow matches local

Tests Fail

Problem: Test workflow shows failures

Solutions:

  1. Download test artifacts from Actions tab
  2. Review HTML report for specific errors
  3. Run tests locally: npm run test:local
  4. Check screenshots in test-results folder
  5. Fix failing tests and push again

Site Not Loading

Problem: GitHub Pages URL shows 404

Solutions:

  1. Verify GitHub Pages is enabled in Settings → Pages
  2. Check deploy workflow completed successfully
  3. Wait 2-3 minutes for DNS propagation
  4. Clear browser cache
  5. Check repository visibility (should be public)

Wrong Base URL

Problem: Assets not loading, 404 on internal links

Solutions:

  1. Verify docusaurus.config.ts has correct baseUrl: '/docusaurus/'
  2. Verify environment detection: GITHUB_ACTIONS environment variable
  3. Rebuild and redeploy

Manual Deployment (Alternative)

If you need to deploy manually without GitHub Actions:

# Set your GitHub username
export GIT_USER=<your-github-username>

# Deploy (will build and push to gh-pages branch)
npm run deploy

Or with SSH:

USE_SSH=true npm run deploy

Post-Deployment Checklist

After successful deployment, verify:

  • Homepage loads at https://sophiahacklab.github.io/docusaurus/
  • All navigation links work
  • Sidebar shows all 4 projects
  • Project pages are accessible:
    • ROV
    • Triviak Real
    • Triviak Mini
    • Fête de la Science
  • CONTRIBUTING and TODO pages for each project
  • Contributing guide is accessible in sidebar
  • Test reports page is accessible
  • Blog section works (3 SHL articles)
  • Search functionality works (if enabled)
  • Dark/light mode toggle works
  • Mobile responsive design works

Updating the Site

To update the site after initial deployment:

# Make your changes to markdown files or code

# Test locally
npm run test:local

# Commit and push
git add .
git commit -m "Update: description of changes"
git push origin main

# GitHub Actions will automatically rebuild and deploy

Viewing Test Results

From GitHub Actions

  1. Go to Actions tab
  2. Click on a test workflow run
  3. Scroll to bottom to see artifacts
  4. Download:
    • test-results-junit - JUnit XML for CI integration
    • test-results-html - Interactive HTML report
    • test-screenshots - Screenshots (if tests failed)

Test Report Retention

  • Test artifacts are kept for 30 days
  • Download important reports before expiration
  • Historical test results are in workflow run history

Environment Variables

The site uses environment-based configuration:

Environment Detection Base URL Site URL
Local Default / http://localhost:3000
GitHub Pages GITHUB_ACTIONS=true /docusaurus/ https://sophiahacklab.github.io

No manual configuration needed - automatically detected!

Support

If you encounter issues:

  1. Check README.md for general documentation
  2. Review Test Reports for testing info
  3. Contact SophiaHackLab: crew@shl.contact

Resources