Hugoで構築したサイトをAWS Amplifyへデプロイする際にいくつかハマったポイントがあるのでメモを残しておきます。
テーマのSubmoduleはSSHではなくHTTPSで追加する
デプロイをしようとしたところフロントエンドのビルドで失敗しており、よく読むとどうやらsubmoduleで追加しているテーマのディレクトリが読み込めていないようでした。
直前のリポジトリのクローンのログには以下のようなメッセージが出ていました。
[INFO]: # Updating Git submodules...
[WARNING]: # Unable to update submodules: Error: Command failed: git submodule update
Cloning into '/codebuild/output/(略)/themes/stack'...
Host key verification failed.
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
fatal: clone of 'git@github.com:CaiJimmy/hugo-theme-stack.git' into submodule path '/codebuild/output/(略)/themes/stack' failed
Failed to clone 'themes/stack'. Retry scheduled
なんと、テーマのsubmoduleをcloneすることができていないようです。
調べてみるとAmplifyではsubmoduleは使えないというような記載も見かけましたが、そんなはずはない!と試行錯誤した結果、submoduleをaddするときにSSHではなくHTTPSにすれば上手く行きました。
つまり
git submodule add git@github.com:OWNER/REPO.git themes/XXX
ではなく
git submodule add https://github.com/OWNER/REPO.git themes/XXX
という形ですね。
すでにSSHで追加してしまっているという場合は一度きれいに削除してから再追加すれば大丈夫です。
# 一旦削除
git rm themes/XXX
git config --remove-section submodule.themes/XXX
rm -rf .git/modules/themes/XXX
# 再追加
git submodule add https://github.com/OWNER/REPO.git themes/XXX
参考:git submodule 追加・削除のやり方【2022 年版】
Hugoのバージョンを指定する
AmplifyはデフォルトではビルドイメージはAmazon Linux:2となっています(2024年1月現在)。このビルドイメージで使われるHugoのバージョンは0.75.1です。
私は現在0.121.2を使っており、そうすると以下のようなエラーが出てしまいます。
[WARNING]: Error: Unable to locate config file or config directory. Perhaps you need to create a new site.
Hugoの設定ファイルが変わった影響ですね。
Hugoなどの依存ライブラリのバージョンはライブパッケージアップデートという仕組みで指定することができます。
私の場合はここで 0.121.2
と入力することで、手元と同じバージョンを指定することができるようになりました。
最新のビルドイメージを利用する
Hugoのバージョンまで指定しましたが、それでもビルドが失敗しました。
[INFO]: WARN Module "stack" is not compatible with this Hugo version; run "hugo mod graph" for more information.
[INFO]: Start building sites …
[INFO]: hugo v0.121.2-6d5b44305eaa9d0a157946492a6f319da38de154 linux/amd64 BuildDate=2024-01-05T12:21:15Z VendorInfo=gohugoio
[INFO]: ERROR render of "page" failed: "/codebuild/output/(略)/themes/stack/layouts/_default/baseof.html:19:19": execute of template failed: template: _default/single.html:19:19: executing "left-sidebar" at <partial "sidebar/left.html" .>: error calling partial: "/codebuild/output/(略)/layouts/partials/sidebar/left.html:19:52": execute of template failed: template: partials/sidebar/left.html:19:52: executing "partials/sidebar/left.html" at <$avatar.Resize>: error calling Resize: image "/codebuild/output/(略)/assets/avatar.webp": this feature is not available in your current Hugo version, see https://goo.gl/YMrWcn for more information
[INFO]: ERROR TOCSS: failed to transform "scss/style.scss" (text/x-scss). Check your Hugo installation; you need the extended version to build SCSS/SASS with transpiler set to 'libsass'.: this feature is not available in your current Hugo version, see https://goo.gl/YMrWcn for more information
Total in 758 ms
Error: error building site: render: failed to render pages: render of "page" failed: "/codebuild/output/(略)/themes/stack/layouts/_default/baseof.html:19:19": execute of template failed: template: _default/single.html:19:19: executing "left-sidebar" at <partial "sidebar/left.html" .>: error calling partial: "/codebuild/output/(略)/layouts/partials/sidebar/left.html:19:52": execute of template failed: template: partials/sidebar/left.html:19:52: executing "partials/sidebar/left.html" at <$avatar.Resize>: error calling Resize: image "/codebuild/output/(略)/assets/avatar.webp": this feature is not available in your current Hugo version, see https://goo.gl/YMrWcn for more information
[ERROR]: !!! Build failed
[ERROR]: !!! Non-Zero Exit Code detected
ログを読んでみると、私が利用しているstackというテーマがこのバージョンに対応していないとのことです。
バージョンは合わせたはず…と思ったのですが、どうやらビルド環境にインストールされているのはHugoのstandardエディションであり、extendedエディションが必要な場合はビルドができないようです。
これはライブパッケージアップデートの仕組みでも解決できません。
Extendedをインストールするスクリプトを書けばいいという書き込みもありましたがそれは面倒くさい、と思っていたところ以下のイシューの最後に解決策がありました。
The new amplify:2023 build image has Hugo Extended installed by default. You can choose this image in your Amplify app’s build settings.
ビルドイメージでAmazon Linux:2023を選べばよいとのことです。
コンソールでビルド環境の設定から以下のようにAmazon Linux:2023を選ぶことで、Hugo extendedエディションによるビルドが可能となります。
ちなみにこちらのイメージではデフォルトでextendedのv0.120.4が使われていました。
今のところ十分新しいバージョンかもしれませんが、手元の環境とのバージョンの違いで思わぬ影響が出ることを防ぐために、ライブパッケージアップデートによるバージョン指定は引き続きしておくことをおすすめします。
まとめ
Hugoで構築したサイトをAWS Amplifyへデプロイする場合は以下の3点に気をつける必要があります。
- テーマのSubmoduleはSSHではなくHTTPSで追加する
- Hugoのバージョンを指定する
- 最新のビルドイメージを利用する
HugoもAmplifyも開発が進んでいろいろと状況も変わる可能性もありますので、現状で変わっていることがあればコメントいただけると幸いです。