Codakey
Play
← Back to hug oio/hugo

How to Deploy & Use hug oio/hugo

# Hugo Deploy & Usage Guide

## 1. Prerequisites

### Required
- **Go 1.24.0 or later** (only required if building from source)
- **Git** (required for Hugo Modules and theme management)

### Edition-Specific Requirements
- **Standard Edition**: Go 1.24.0+
- **Extended Edition**: Go 1.24.0+ and **GCC** (required for LibSass transpilation)
- **Extended/Deploy Edition**: Go 1.24.0+ and **GCC** (required for cloud storage deployment)

### Verify Prerequisites
```bash
go version          # Should show go1.24.0 or later
gcc --version       # Required only for Extended/Extended+Deploy editions
git --version       # Required for modules

2. Installation

Option A: Prebuilt Binary (Recommended)

Download the latest binary for your platform from the releases page.

Quick install (macOS/Linux):

# macOS with Homebrew
brew install hugo

# Extended edition
brew install hugo --build-from-source --formula --HEAD

# Ubuntu/Debian
sudo apt install hugo

# Arch Linux
sudo pacman -S hugo

Option B: Build from Source

Standard Edition:

go install github.com/gohugoio/hugo@latest

Extended Edition:

CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest

Extended/Deploy Edition:

CGO_ENABLED=1 go install -tags extended,withdeploy github.com/gohugoio/hugo@latest

Verify Installation

hugo version
# Should show: hugo v0.x.x+extended (if using extended edition)

3. Configuration

Project Structure

Create a new site:

hugo new site mysite
cd mysite
git init   # Required for Hugo Modules

Configuration Files

Hugo supports hugo.toml, hugo.yaml, or hugo.json in the project root.

Minimal hugo.toml:

baseURL = 'https://example.com'
languageCode = 'en-us'
title = 'My Site'
theme = 'ananke'  # Or use [module] for Hugo Modules

[module]
  [[module.imports]]
    path = 'github.com/theNewDynamic/gohugo-theme-ananke'

Environment Variables

  • HUGO_ENV - Set to production, development, or staging (affects template logic)
  • HUGO_CACHEDIR - Cache directory path
  • HUGO_RESOURCEDIR - Resources directory path
  • HUGO_MODULE_PROXY - Go module proxy (default: https://proxy.golang.org)

Cloud Deployment Credentials (Extended/Deploy Edition)

For hugo deploy, configure credentials in hugo.toml:

[deployment]
  [[deployment.targets]]
    name = "aws"
    URL = "s3://mybucket?region=us-east-1"
    # Credentials via env vars: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY

4. Build & Run

Development Server

Start the development server with live reload:

hugo server

Common development flags:

hugo server --bind 0.0.0.0 --port 8080    # Custom bind/port
hugo server --disableFastRender           # Disable fast render for full rebuilds
hugo server --gc                          # Run garbage collection on build
hugo server --navigateToChanged           # Auto-navigate browser to changed files
hugo server -D                            # Include drafts
hugo server -E                            # Include expired content
hugo server -F                            # Include future-dated content

Production Build

Generate the static site (outputs to public/ by default):

hugo --gc --minify

Production flags:

hugo --minify           # Minify HTML, CSS, JS
hugo --gc               # Clean cache after build
hugo --templateMetrics  # Debug template execution times
hugo --cleanDestinationDir  # Remove files in target dir not in source

Build Targets

Set environment for production builds:

HUGO_ENV=production hugo --gc --minify

5. Deployment

Static Hosting (All Editions)

Deploy the public/ directory to any static host:

Netlify:

# netlify.toml
[build]
  publish = "public"
  command = "hugo --gc --minify"

[build.environment]
  HUGO_VERSION = "0.139.0"
  HUGO_ENV = "production"

Vercel: Set build command: hugo --gc --minify Output directory: public

GitHub Pages:

# .github/workflows/deploy.yml
- name: Build
  run: hugo --gc --minify
- name: Deploy
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public

Cloud Storage (Extended/Deploy Edition Only)

Deploy directly to cloud storage using the hugo deploy command:

Configure hugo.toml:

[deployment]
  [[deployment.targets]]
    name = "production"
    URL = "s3://mybucket?region=us-east-1"  # AWS S3
    # URL = "gs://mybucket"                   # Google Cloud Storage
    # URL = "azblob://mycontainer"            # Azure Blob Storage
    cloudFrontDistributionID = "E1234567890"  # Optional: invalidate CDN

  [[deployment.matchers]]
    pattern = "^.+\\.(js|css|svg|ttf)$"
    cacheControl = "max-age=31536000, no-transform, public"
    gzip = true

Deploy:

hugo deploy --target production --invalidateCDN

Environment variables for credentials:

  • AWS: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
  • GCS: GOOGLE_APPLICATION_CREDENTIALS (path to service account JSON)
  • Azure: AZURE_STORAGE_ACCOUNT, AZURE_STORAGE_KEY

6. Troubleshooting

Build Errors

"exec: "gcc": executable file not found in $PATH"

  • Cause: Attempting to build Extended edition without GCC
  • Solution: Install GCC or use Standard edition: go install github.com/gohugoio/hugo@latest

"module not found" errors

  • Cause: Git not initialized or module proxy unreachable
  • Solution: 
    git init
hugo mod get -u ./...

Sass/SCSS compilation fails

  • Cause: Standard edition installed but theme uses Sass
  • Solution: Install Extended edition or configure Dart Sass as external binary

Runtime Issues

Changes not reflecting in browser

  • Clear browser cache (Hugo server adds cache-busting hashes in development)
  • Check if --disableFastRender is needed for structural changes
  • Verify file watcher limits: ulimit -n 2048 (macOS/Linux)

"too many open files"

# macOS
ulimit -n 4096
# Or increase system limits in /etc/sysctl.conf

Memory issues on large sites

hugo --gc              # Clean cache
hugo --templateMetrics # Identify slow templates
# Increase Go runtime memory: export GOGC=100

Module Issues

Slow module resolution

hugo mod clean
hugo mod get -u ./...

Private repositories

export GOPRIVATE=github.com/myorg
git config --global url."git@github.com:".insteadOf "https://github.com/"

Deployment Failures

"Access Denied" on hugo deploy

  • Verify cloud credentials are exported as environment variables
  • Check IAM permissions (S3: s3:PutObject, GCS: Storage Object Admin)
  • For AWS, ensure bucket policy allows access from your IP

CSS/JS not loading on deployed site

  • Check baseURL in config matches your deployed domain
  • Verify asset links use relURL or absURL template functions
  • Check if --minify broke HTML (disable to test)
← Project overviewView alternatives to hug oio/hugo →