This guide covers how to deploy your Hugo site on various hosting platforms, from static site hosts to cloud providers.

Prerequisites

• Hugo site ready for deployment
• Git repository (GitHub, GitLab, etc.)
• Basic command line knowledge

Quick Comparison

Netlify (Recommended)

Best for: Beginners, continuous deployment, form handling

Method 1: Git Integration (Recommended)

1. Push your Hugo site to GitHub/GitLab

   git add .
   git commit -m "Initial commit"
   git push origin main
   

2. Connect to Netlify

   • Visit netlify.com
   • Click “New site from Git”
   • Choose your Git provider and repository

3. Configure Build Settings

   Build command: hugo --minify
   Publish directory: public
   Environment variables:
     HUGO_VERSION: 0.120.0  # Use your Hugo version
   

4. Deploy

   • Click “Deploy site”
   • Your site will be available at https://random-name.netlify.app

Method 2: Manual Upload

1. Build your site locally

   hugo --minify
   

2. Deploy to Netlify

   • Go to netlify.com/drop
   • Drag and drop your public folder

Netlify Configuration File

Create netlify.toml in your site root:

[build]
  command = "hugo --minify"
  publish = "public"

[build.environment]
  HUGO_VERSION = "0.120.0"

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-XSS-Protection = "1; mode=block"
    Content-Security-Policy = "frame-ancestors https://www.facebook.com"

# Redirect rules
[[redirects]]
  from = "/old-path"
  to = "/new-path"
  status = 301

Useful Links:

• Netlify Hugo Documentation
• Custom Domain Setup

GitHub Pages

Best for: Free hosting, GitHub integration, simple setup

Method 1: GitHub Actions (Recommended)

1. Create workflow file .github/workflows/hugo.yml:

name: Deploy Hugo site to Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

defaults:
  run:
    shell: bash

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v3

      - name: Build with Hugo
        env:
          HUGO_ENVIRONMENT: production
          HUGO_ENV: production
        run: |
          hugo \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"          

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: ./public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

2. Enable GitHub Pages
   • Go to repository Settings → Pages
   • Source: “GitHub Actions”
   • Push to trigger deployment

Method 2: Manual Build

1. Configure Hugo for GitHub Pages

   # config.yaml
   baseURL: 'https://username.github.io/repository-name'
   

2. Build and push to gh-pages branch

   hugo --minify
   git add public
   git commit -m "Deploy site"
   git subtree push --prefix public origin gh-pages
   

Useful Links:

• GitHub Pages Documentation
• Hugo on GitHub Pages

Vercel

Best for: Fast builds, edge functions, developer experience

Setup

1. Install Vercel CLI

   npm i -g vercel
   

2. Deploy

   vercel
   

3. Or connect via dashboard

   • Visit vercel.com
   • Import your Git repository
   • Vercel auto-detects Hugo configuration

Configuration File

Create vercel.json:

{
  "build": {
    "env": {
      "HUGO_VERSION": "0.120.0"
    }
  },
  "redirects": [
    {
      "source": "/old-path",
      "destination": "/new-path",
      "permanent": true
    }
  ]
}

Useful Links:

• Vercel Hugo Documentation

GitLab Pages

Best for: GitLab users, CI/CD integration

Setup

Create .gitlab-ci.yml:

image: klakegg/hugo:ext-alpine

variables:
  GIT_SUBMODULE_STRATEGY: recursive

pages:
  script:
    - hugo --minify
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Useful Links:

• GitLab Pages Documentation

Firebase Hosting

Best for: Google ecosystem, dynamic features

Setup

1. Install Firebase CLI

   npm install -g firebase-tools
   

2. Initialize Firebase

   firebase login
   firebase init hosting
   

3. Configure firebase.json:

   {
     "hosting": {
       "public": "public",
       "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
       "rewrites": [
         {
           "source": "**",
           "destination": "/404.html"
         }
       ]
     }
   }
   

4. Build and deploy

   hugo --minify
   firebase deploy
   

Useful Links:

• Firebase Hosting Documentation

Amazon S3 + CloudFront

Best for: AWS ecosystem, high traffic sites

Setup

1. Build your site

   hugo --minify
   

2. Create S3 bucket

   • Enable static website hosting
   • Upload public folder contents

3. Configure CloudFront

   • Create distribution pointing to S3 bucket
   • Set up custom domain and SSL certificate

4. Automated deployment with GitHub Actions

   - name: Deploy to S3
     run: |
       aws s3 sync ./public s3://your-bucket-name --delete
       aws cloudfront create-invalidation --distribution-id ${{ secrets.CLOUDFRONT_ID }} --paths "/*"    
   

Useful Links:

• AWS S3 Static Website Hosting

Custom Domain Setup

General Steps

1. Configure your DNS

   • Add CNAME record pointing to hosting provider
   • Or A record for apex domain

2. Common DNS Records

   # Netlify
   CNAME www your-site.netlify.app
   
   # GitHub Pages
   CNAME www username.github.io
   
   # Vercel
   CNAME www your-site.vercel.app
   

3. SSL Certificate

   • Most platforms provide automatic SSL
   • May take up to 24 hours to provision

Performance Optimization

Hugo Configuration

# config.yaml
minify:
  disableCSS: false
  disableHTML: false
  disableJS: false
  disableJSON: false
  disableSVG: false
  disableXML: false

imaging:
  resampleFilter: "CatmullRom"
  quality: 75
  anchor: "smart"

caches:
  assets:
    dir: ":resourceDir/_gen"
    maxAge: "1h"
  getcsv:
    maxAge: "10s"
  getjson:
    maxAge: "10s"

Build Optimization

# Production build
hugo --minify --gc --enableGitInfo

# With specific environment
HUGO_ENV=production hugo --minify

Troubleshooting

Common Issues

1. Build fails with theme submodule

   git submodule update --init --recursive
   

2. Assets not loading

   • Check baseURL in config
   • Ensure relative URLs are used

3. 404 errors

   • Verify publishDir setting
   • Check routing configuration

4. Slow build times

   • Use --gc flag
   • Consider build caching
   • Optimize images before processing

Debug Commands

# Verbose build output
hugo -v

# Check configuration
hugo config

# Test locally
hugo server -D --disableFastRender

Continuous Integration Tips

Environment Variables

# Common Hugo environment variables
HUGO_VERSION=0.120.0
HUGO_ENV=production
HUGO_ENABLEGITINFO=true
NODE_ENV=production

Build Scripts

Create package.json for Node.js tools:

{
  "scripts": {
    "build": "hugo --minify --gc",
    "dev": "hugo server -D",
    "clean": "rm -rf public resources"
  },
  "devDependencies": {
    "postcss": "^8.0.0",
    "autoprefixer": "^10.0.0"
  }
}

Security Considerations

Content Security Policy

<!-- In your head.html partial -->
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';">

Headers Configuration

Most platforms support custom headers:

# Netlify
[[headers]]
  for = "/*"
  [headers.values]
    Strict-Transport-Security = "max-age=31536000; includeSubDomains; preload"
    X-Content-Type-Options = "nosniff"
    X-Frame-Options = "DENY"
    Referrer-Policy = "strict-origin-when-cross-origin"

Monitoring and Analytics

Popular Analytics Solutions

• Google Analytics 4: Most comprehensive
• Plausible: Privacy-focused alternative
• Fathom: Simple, privacy-focused
• Netlify Analytics: Server-side analytics

Performance Monitoring

• Google PageSpeed Insights
• GTmetrix
• WebPageTest
• Lighthouse CI for automated testing

This guide covers the most popular hosting options for Hugo sites. Choose based on your specific needs, technical expertise, and budget requirements.