Skip to content

DEPLOYMENT.md

Latest commit

 

History

History
128 lines (97 loc) · 4.71 KB

DEPLOYMENT.md

File metadata and controls

128 lines (97 loc) · 4.71 KB

Deployment Guide

Overview

This site is automatically deployed to https://volttron.org via GitHub Pages when changes are pushed to the main branch.

Build Process

GitHub Actions Workflows

Production Deployment (.github/workflows/hugo.yaml)

The production deployment workflow:

  1. Installs Hugo Extended 0.126.0 and Dart Sass
  2. Checks out the repository with submodules (to get the theme)
  3. Configures GitHub Pages and gets the base URL from repository settings
  4. Builds the site using hugo --gc --minify --baseURL with the GitHub Pages configured URL
  5. Deploys to GitHub Pages with the custom domain

Important: The workflow uses ${{ steps.pages.outputs.base_url }} to dynamically get the custom domain configured in GitHub Pages repository settings. This ensures the site is built with the correct URLs.

Triggers: Pushes to main branch

PR Preview Build (.github/workflows/pr-preview.yaml)

The PR preview workflow:

  1. Builds the site for pull requests before merging
  2. Creates a downloadable artifact with the built site
  3. Posts a comment on the PR with preview instructions
  4. Allows reviewers to test changes before merging to production

Triggers: Pull requests targeting main branch

How to preview:

  1. Go to the PR's "Checks" tab
  2. Click on "PR Preview Build" workflow run
  3. Download the artifact named pr-preview-{PR-number}
  4. Extract and open index.html in a browser, or use a local web server

Local Development

Development Server (with live reload)

# Initialize theme submodule (first time only)
git submodule update --init --recursive

# Start development server
hugo serve

Visit http://localhost:1313 to preview changes.

⚠️ IMPORTANT: Never commit the public/ directory that's generated by hugo serve! It contains localhost URLs and development scripts.

Production Build (for testing)

# Build exactly as GitHub Actions does
hugo --gc --minify

# The output will be in the public/ directory
# Verify it looks correct, then delete it (it should not be committed)
rm -rf public/

Important Files

Configuration

  • hugo.toml - Main Hugo configuration with baseURL
  • config/_default/config.toml - Extended configuration including languages
  • Both must have baseURL = "https://volttron.org/"

Deployment Files

  • static/CNAME - Contains "volttron.org" for custom domain
  • static/.nojekyll - Tells GitHub Pages not to use Jekyll
  • Files in static/ are copied to the root of public/ during build

GitHub Pages Settings

The custom domain must be configured in GitHub Pages repository settings:

  1. Go to repository Settings → Pages
  2. Under "Custom domain", enter: volttron.org
  3. Wait for DNS check to complete (green checkmark)
  4. Enable "Enforce HTTPS" once DNS is validated

The workflow uses ${{ steps.pages.outputs.base_url }} to get this configured domain dynamically.

Ignored Directories

The following directories are build artifacts and should NEVER be committed:

  • public/ - Generated site output
  • resources/ - Hugo cache files
  • .hugo_build.lock - Hugo lock file

These are listed in .gitignore to prevent accidental commits.

Troubleshooting

Site shows localhost URLs

  • Cause: The public/ directory was built with hugo serve instead of hugo
  • Fix: Delete the public/ directory and let GitHub Actions rebuild it

Theme not found error

  • Cause: The theme submodule wasn't initialized
  • Fix: Run git submodule update --init --recursive

Wrong domain in deployed site

  • Cause: CNAME file missing or in wrong location
  • Fix: Ensure static/CNAME exists and contains "volttron.org"

Custom domain (volttron.org) not working

  • Cause: Custom domain not configured in GitHub Pages repository settings
  • Fix:
    1. Go to repository Settings → Pages
    2. Enter volttron.org in the "Custom domain" field
    3. Wait for DNS check to pass (shows green checkmark)
    4. The workflow will automatically use this domain via ${{ steps.pages.outputs.base_url }}
  • Note: The domain volttron.net redirects to volttron.org at the DNS level

Deployment Checklist

Before merging to main:

  • Verify hugo --gc --minify builds successfully
  • Check that public/ and resources/ are not being committed
  • Confirm baseURL in both config files is "https://volttron.org/"
  • Ensure static/CNAME exists with correct domain
  • Test that theme submodule is configured correctly
  • Review the PR preview build artifact to verify the site looks correct

Security Notes

  • The site uses HTTPS and is served via GitHub Pages
  • Custom domain is configured via CNAME
  • All builds are done in GitHub Actions with a clean environment
  • No sensitive data should be committed to the repository