ローカル環境を汚さない静的サイト構築 - Hugo Docker Compose環境構築記録

Sun, 21 Dec 2025 23:00:00 +0900

背景

日課でできる範囲の活動として、軽い記事から、疑問を生成AIに出してもらって、それに答えてもらって、深堀や補足、添削をしてもらった内容までを記事にするという習慣を続けていたが、公開するのはどうなのかなと思った。

しかし、後ほど止めるのはもったいないということで妥協案として、ローカルで動くブログには投稿することにした。

なので、ローカルブログを立ち上げることにした。

最初はGitHub Pagesでよく使われているJekyllを試した。しかし、ローカル環境とDocker環境でRubyのバージョン不一致が発生し、プロジェクト初期化の段階で躓いた。

ローカルのRuby 3.4に対してDockerの最新イメージがRuby 3.1で、この差分が原因でSCSS変換周りでエラーが頻発。Jekyllはプロジェクト作成をローカルで行う必要があるため、「Docker使えば環境差を吸収できる」という謳い文句が実質的に機能しなかった。

もっとうまくやればよかっただろうが、そのときは血が登っていて、Hugoにしてしまった。

要件整理

改めて自分の要件を整理した：

Markdownファイルのマウントだけで完結
ローカル環境に一切依存しない
プロジェクト初期化もDocker内で実行可能
検索機能とファイル一覧が欲しい

これを満たすツールを探した結果、Hugoに行き着いた。

なぜHugoなのか

Hugoを選んだ理由は明確：

1. バイナリ単体で動作

Go言語で書かれたHugoは単一バイナリで動作する。RubyやNode.js、Pythonのようなランタイム環境が不要。これにより依存関係地獄から解放される。

2. プロジェクト初期化もDocker内で完結

当初は生成AIの言うとおりに以下のコマンドでプロジェクトを作成した。

docker run --rm -v $(pwd)/posts:/src klakegg/hugo:alpine new site .

この1コマンドでプロジェクト作成が完了する。ローカルに何もインストールする必要がない。

のだが、後ほどこれがトラブルを産んだ。

3. 高速なビルド

Goの並列処理能力により、数千ページ規模のサイトでも秒単位でビルドが完了する。開発時のホットリロードも快適。

構築手順

1. docker-compose.yml作成

services:
  hugo:
    image: hugomods/hugo:base
    container_name: hugo-blog
    ports:
      - "7000:7000"
    volumes:
      - ./posts:/src
    command: server --bind 0.0.0.0 --port 7000 --buildDrafts --buildFuture
    restart: unless-stopped

ポイント：

hugomods/hugo:base を使用
ポートは7000にマッピング（後述のブラウザ制限回避）
--buildDrafts --buildFuture で下書きと未来日付の記事も表示

2. プロジェクト初期化

docker run --rm -v $(pwd)/posts:/src klakegg/hugo:alpine new site .

これで posts/ ディレクトリに必要なファイル群が生成される。

静的サイトジェネレータ on 怠惰技術ブログ