Skip to content

Deployment Guide for Java Learning Platform

Overview

This guide outlines the complete process for deploying the Java Learning Platform to a production environment. The platform is deployed as a static documentation site using GitHub Pages with custom domain configuration and CDN integration.

Prerequisites

Before proceeding with deployment, ensure you have:

  1. GitHub Account: With permissions to access the repository
  2. Git: Installed locally for repository management
  3. Python Environment: For local testing (Python 3.8+ with pip)
  4. Domain: If using a custom domain name
  5. Cloudflare Account: For CDN setup (optional but recommended)

Deployment Architecture

The deployment architecture consists of:

                                     ┌────────────────┐
                                     │   Cloudflare   │
                                     │   CDN/Cache    │
                                     └───────┬────────┘
                                             │
                                             ▼
┌────────────────┐             ┌────────────────────────┐
│  GitHub        │──Build──────▶  GitHub Pages Hosting  │
│  Repository    │  Actions    │                        │
└───────┬────────┘             └────────────┬───────────┘
        │                                   │
        │                                   │
        │                                   ▼
┌───────▼────────┐             ┌────────────────────────┐
│  Local         │             │   Custom Domain        │
│  Development   │             │   (Optional)           │
└────────────────┘             └────────────────────────┘

GitHub Pages Deployment Process

Step 1: Configure Repository Settings

  1. Navigate to your repository on GitHub
  2. Go to Settings > Pages
  3. Configure source:
  4. Select "GitHub Actions" as the deployment method
  5. Set the branch to main or your preferred deployment branch

Step 2: Create GitHub Actions Workflow

Create a file at .github/workflows/deploy.yml:

name: Deploy Documentation

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Build documentation
        run: mkdocs build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site
          cname: your-custom-domain.com  # Remove if not using custom domain

Step 3: Set Up Custom Domain (Optional)

  1. Purchase a domain from a domain registrar
  2. In your repository, go to Settings > Pages
  3. Under "Custom domain", enter your domain name
  4. Save the configuration
  5. Update DNS settings at your domain registrar:
  6. Add a CNAME record pointing to mshemeel.github.io
  7. Or, for apex domains, add A records pointing to GitHub's IP addresses: 
    185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Step 4: Configure HTTPS

  1. In GitHub Pages settings, check "Enforce HTTPS"
  2. This will generate a free SSL certificate through Let's Encrypt
  3. Wait for the certificate to be issued (may take up to 24 hours)

Cloudflare CDN Integration (Optional)

Step 1: Set Up Cloudflare Account

  1. Create an account on Cloudflare
  2. Add your website to Cloudflare
  3. Update your domain's nameservers to those provided by Cloudflare

Step 2: Configure Cloudflare Settings

  1. SSL/TLS Settings:
  2. Set to "Full" mode

  3. Enable "Always Use HTTPS"

  4. Caching Configuration:

  5. Set caching level to "Standard"

  6. Create a page rule to cache everything:

    • URL pattern: yoursite.com/*
    • Setting: Cache Level: "Cache Everything"

  7. Performance Settings:

  8. Enable Auto Minify for HTML, CSS, and JavaScript
  9. Enable Brotli compression
  10. Enable HTTP/2 and HTTP/3

Local Build and Testing

Before deploying, test your documentation locally:

# Clone the repository (if you haven't already)
git clone https://github.com/mshemeel/java-learning.git
cd java-learning

# Install dependencies
pip install -r requirements.txt

# Run the local development server
mkdocs serve

# Build the documentation locally
mkdocs build

The local site will be available at http://127.0.0.1:8000/.

Continuous Deployment Workflow

The typical workflow for updating the documentation:

  1. Make changes to documentation content in a feature branch
  2. Test locally using mkdocs serve
  3. Push changes to GitHub and create a pull request
  4. Review changes in the PR preview (if configured)
  5. Merge the PR to the main branch
  6. GitHub Actions will automatically build and deploy the changes

Deployment Verification

After deployment, verify:

  1. Content: Ensure all content is correctly displayed
  2. Links: Check that all internal and external links work
  3. Search: Test the search functionality
  4. HTTPS: Verify the site loads securely with HTTPS
  5. Mobile: Test the site on mobile devices
  6. Performance: Use tools like Google PageSpeed Insights to check performance

Maintenance and Updates

Regular Maintenance Tasks

  1. Content Updates:
  2. Commit and push content changes

  3. GitHub Actions will automatically redeploy

  4. Dependency Updates:

  5. Periodically update Python dependencies in requirements.txt

  6. Update MkDocs theme and plugins as needed

  7. SSL Certificate:

  8. If using GitHub Pages with a custom domain, certificates auto-renew
  9. If using Cloudflare, certificates are managed automatically

Monitoring

  1. GitHub Actions: Monitor deployment workflows for any failures
  2. Cloudflare Analytics: Review traffic patterns and cache performance
  3. Error Tracking: Set up external monitoring for any site outages

Troubleshooting

Common Issues and Solutions

  1. Deployment Failures:
  2. Check GitHub Actions logs for detailed error messages
  3. Verify Python dependencies are correctly specified

  4. Ensure the MkDocs configuration is valid

  5. Custom Domain Issues:

  6. Verify DNS records are correctly configured
  7. Check the CNAME file in the repository

  8. Allow up to 24 hours for DNS propagation

  9. SSL Certificate Problems:

  10. Ensure "Enforce HTTPS" is enabled
  11. Check for mixed content warnings

  12. Verify the certificate is issued for the correct domain

  13. Performance Issues:

  14. Check image sizes and formats
  15. Verify Cloudflare caching settings
  16. Review JavaScript and CSS minification

Rollback Procedure

If a deployment causes issues:

  1. Identify the last known good commit
  2. Revert to that commit: 
    git revert <commit-hash>
git push origin main
  3. Alternatively, manually roll back through GitHub interface:
  4. Go to repository Actions
  5. Find the last successful deployment
  6. Use the "Re-run jobs" option

Security Considerations

  1. Access Control:
  2. Limit write access to the repository
  3. Use branch protection rules for the main branch

  4. Require pull request reviews before merging

  5. Sensitive Information:

  6. Do not store API keys or secrets in the repository
  7. Use GitHub Secrets for sensitive information

  8. Regularly audit repository content

  9. External Dependencies:

  10. Regularly update dependencies to patch security vulnerabilities
  11. Consider using Dependabot for automated updates

Additional Resources

Conclusion

Following this deployment guide will result in a fully functional, secure, and performant documentation platform accessible to all users. The automated deployment pipeline ensures that content updates are quickly and reliably published, while the CDN integration provides optimal performance for users worldwide.