⛵

Kamal 2 を使い、インフラに詳しくない人でもNext.jsを269円のVPSにデプロイできるよう、説明してみる

2024/10/02に公開

AWS

9月26, 27日に開催され、めちゃくちゃ盛り上がったRails World 2024でKamal 2が発表されました。Kamal 2はRuby on Railsを作った37signals社が、自社の人気サービスをデプロイするのに使用しているツールです。
37signals社はAWS等のクラウドに年間で$3,201,564を使った(2022年: 日本円で4.5億円ほど)らしく、一方でAWSを使ってもインフラ系人員の削減もほとんどできなかったので、全然割に合わないからもうクラウドはやめて自分たちのサーバを使うと宣言しています。Kamal 2はそのために作られた、本格的なデプロイツールです。
（ちなみに自分たちのサーバを使うと言ってもオンプレミスでサーバを運用するというのではなく、さくらの専用サーバに近いイメージです）
Dockerベース
Docker化されたアプリなら何にでも対応 (Railsだけじゃない！)
Dockerさえインストール可能なら、どんなLinuxサーバにもデプロイ可能 (Dockerは自動インストールしてくれる)

ゼロダウンタイムデプロイなど、本格的なサービスに対応したデプロイ機能
データベース等の付随サービスもKamalが管理し、サーバのDocker上にデプロイされる
Ruby on RailsをKamal 2でデプロイする記事は別途書きましたので、今回はNext.jsをデプロイします。しかも月額たった269円(税込)のVPSサーバ(ConoHa VPS)を使います！

 本記事の目標商用・個人開発の如何に関わらず、月額定額・全部込みの明朗会計のサービスだけを使い、安心して複数のプロジェクトを公開できること（高額請求の心配がない）
インフラに詳しくないエンジニアやデザイナーが、自分でレンタルVPSをレンタル・セットアップし、Next.jsをデプロイできること
インフラを触って勉強するきっかけになること

 前提以下のものがローカルマシンにすでにインストールされていて、基本的な使っ方ができることが前提になります。Next.jsの開発をしているのならば、３つともインストール済みではないかと思います。
Node.jsおよびNPM
Git
Docker
もし使ったことがなくても非常に基本的な使い方しかしませんので、チュートリアルをやっていただければと思います。

 作るもの基本的なものですが、１時間あたり数千ユーザは捌ける構成です。
左から順番に解説します
インターネットに接続したブラウザからリクエストが来ると、まず最初にVPSプロバイダ（今回はConoha VPS）が用意したファイヤーウォール（Conohaではセキュリティグループと呼びます）に届きます
ここでport 22(SSH), 80(HTTP), 443(HTTPS)向けのトラフィックのみを通します
つまり、外部からアクセスできるのはSSH (外部からターミナル接続できる機能), HTTP (暗号化なしの"http://..."）接続機能, HTTPS (暗号化ありの"https://..."）接続機能だけに制限します。これはセキュリティ上必須です

ファイヤーウォールを通過したリクエストはKamal Proxyに届きます

Kamal-Proxyに来たリクエストは、URLのホスト部分（"app1.example.com"のところ）で振り分けられ、対応するNext.jsアプリのContainerに送られます
Next.jsアプリが複数ある場合は、URLのホスト部分に応じて振り分けられます

Kamal-Proxyのもう１つ大事な機能は、TLS証明書の自動取得・更新です。これがないとHTTPS接続ができず、セキュリティ上の問題になります。一般には有料でかつ複雑なセットアップが必要ですが、Kamalは無料で全自動でやってくれます


Kamal-Proxyによって振り分けられたリクエストは、適切なNext.jsアプリのContainerに届きます
Next.jsアプリのContainerは、皆さんがローカルのマシンでnpm run build, npm run startをやるのとほぼ同じ箇所です。つまりアプリの本体です
コードを書き換えてデプロイするときは、ここだけがスムーズに新旧交代します


 デプロイ時の流れデプロイは複雑なので完全に理解する必要はありません。以後の設定ファイル編集等に登場する３人の役者、つまりローカルマシン、DockerHub、そしてサーバ(VPS)が存在することだけでも把握していただければと思います。
「Docker Imageをbuildする」の箇所は、Docker開発をしている人なら馴染んでいるdocker compose buildもしくはdocker build .コマンドに相当します。
Docker Imageは、Next.jsを起動するために必要なOS(Linux)、Node.js、NPM、Next.jsフレームワーク、自分自身が書いたコードをすべてまとめたものです。パソコンのドライブに相当するものです
コードを変更するたびにDocker Imageを作り替えます。それが「Docker Imageをbuildする」ステップです

「DockerHubにアップロードする」の箇所は、Docker Imageをサーバに配信する準備段階です
本格運用をすると、サーバは何十、何百台になったりします。Docker Imageはそのすべてのサーバに届ける必要があります。さすがにローカルマシンから直接配信するのは心配です
DockerHubはDocker Imageを保管するRepositoryです。何十、何百のサーバはそれぞれDockerHubにアクセスし、Docker Imageを要求すれば良いのです。そのために「DockerHubにアップロードする」ステップがあります

Kamalは各サーバにDeployの指示を出します
指示を受けた各サーバはDockerHubに対して、適切なDocker Imageを要求します
指示されたDocker Imageはサーバにダウンロードされます
各サーバではDocker Imageを実行します。これはDocker開発をするのであれば、docker compose runもしくはdocker runコマンドに相当します。Docker開発をしていないのであれば、npm run startに相当します。Docker Imageが実行された状態、つまり稼働中のサーバはContainerと呼ばれます
Kamalのデプロイはゼロダウンタイムデプロイと呼ばれるものです。デプロイ時にサービスは一瞬も停止しません
(6)で新しいContainerを立ち上げている間、古いContainerはまだ残しています。そしてインターネットから来たリクエストには、古いContainerが対応します
新しいContainerが立ち上がったことが確認できたら(healthcheck)、次のリクエストからは新しいContainerに振り分けられます。そして古いContainerは停止されます


 VPSのセットアップConoha VPSを使った場合のセットアップ手順については、ビデオで紹介していますので、ご覧ください
https://youtu.be/z2bKG4Ddwzw?si=rJ5hGDXJWNWBVE5W
ここでやっていることをまとめると
VPSを契約する
VPSにUbuntuをインストールする
VPSがSSHとWeb(HTTPとHTTPS)のサービスを提供するようにする
ローカルマシンからSSHでログインできるようにする

 以降のセットアップのビデオVPSのセットアップから実際のデプロイまでの様子（つまり以下全部）をビデオでも紹介しています。ご覧ください
https://youtu.be/x2fOZ0iHbVM?si=RJyrwNCp1Z533m12

 ローカルマシンの準備
 Node, Git, Dockerのインストール上述したように、ローカルマシンには下記のものがインストールされている必要があります
Node.js, NPM
Git
Docker
Next.js開発をしてもDockerは使っていない可能性がありますので、必要に応じてインストールしてください。Dockerのウェブサイトからインストールしてください

 Kamalの準備今回はKamalをインストールしないで使います。下記のコマンドだけ、ターミナルから実行してセットアップをしてください[1]。
alias kamal='docker run -it --rm -v "${PWD}:/workdir" -v "/run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock" -e SSH_AUTH_SOCK="/run/host-services/ssh-auth.sock" -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/basecamp/kamal:latest'
!2024/10/2 15:00 時点で設定ミスにより、上記のコマンドはうまくいきません（Kamal v.1.9.1をダウンロードしてしまいます）。代わりに下のものを使用してください。
alias kamal='docker run -it --rm -v "${PWD}:/workdir" -v "/run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock" -e SSH_AUTH_SOCK="/run/host-services/ssh-auth.sock" -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/basecamp/kamal:v2.0.0'
動作確認のために次のコマンドを実行してください。バージョン番号 (2024年9月30日時点では"2.0.0"）が表示されたら成功です。
 kamal version
!この方法の欠点として、SSHのpublic-keyを使ったアクセスができなくなってしまうようです。その都度パスワードを入れる必要があります。

 Create Next AppでNext.jsの新しいアプリを作成公式ドキュメントの通りに操作します。色々なオプションがありますが、どれでも問題ありません。

 Next.jsアプリをDocker化上記の項目で作成されたNext.jsアプリをDocker化します。公式ドキュメントのSelf-Hostingの項目の"A Node.js server"と"A Docker Container"のところを実施します。
私がやったもののコードがGitHubにありますので、こちらもご覧ください。
package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}
Dockerfile
見本アプリのDockerfileをそのままコピーします
見本アプリのIn existing projectsに書かれている通りに、next.config.jsを変更します。ESモジュールを使っている場合は下記のようにしてください。
next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "standalone",
};

export default nextConfig;
publicフォルダ
上記のDockerfileは/publicフォルダの存在を前提としています（無いとbuildが落ちます）。このように/publicフォルダを作り、その中に.keepという空のファイルを作ってください。空のフォルダはGitに無視されるため、.keepのファイルは重要です（何か一つでもファイルがあれば良いので、それがあれば.keepじゃなくても良いです）。
動作確認を実施します。下記のコマンドを実行し、http://localhost:3000でNext.jsのページが表示されることを確認してください
docker build . -t kamal_next
docker run --rm -p 3000:3000 kamal_next
動作確認コマンドの解説）

docker build . -t kamal_nextは上記のDockerfileの中身に沿って、Docker Imageを作成するコマンドです。NodeとかNext.jsをインストールし、さらにnpm run buildをしてNext.jsをbuildします。Docker Imageの名前を"kamal_next"にしています（名前は任意）。

docker run -p 3000:3000 kamal_nextはDocker Imageを実行し、Docker Containerを実行します。node server.jsを実行して、Next.jsのサーバを立ち上げます。通常の開発時にnpm run startとするのと同じです。
これが成功すれば、Dockerfileまではうまく作れた証明になります！

 Next.jsにhealthcheckを導入ヘルスチェックは、サーバが作業を正常に実行できるかどうかを確認する方法です。KamalではこれからデプロイしようとするDocker Containerが正常に立ち上がったかどうかを確認するのに使用します。
ヘルスチェックを実装するためには、Next.jsアプリに/upのエンドポイントを作成し、これがStatus 200を返すようにします。下記のファイルを作成して実装します。
app/up/route.ts
export async function GET() {
  return new Response("I'm Healthy", {status: 200})
}

 KamalのセットアップいよいよKamalのセットアップです。
下記を実行するとデフォルトの設定ファイルが生成されます。
kamal init

 DockerHubアクセス用のPersonal Access Tokenの取得Kamalは先ほどセットアップしたDockerHubのアカウントに接続して、Docker Imageをアップロードしたり、あるいはダウンロードしたりする必要があります。その時のパスワードがわりにpersonal access tokenを作ります（大元のパスワードは漏洩したくないので、必ずpersonal access tokenを使ってください）。
"Account Settings" > "Personal Access Tokens" > "Generate New Token" で新しいpersonal access tokenを作成してください。

"Access Permissions"は"Read & Write"としてください。Docker Imageをアップロードもダウンロードもするためです。
Personal Access Tokenはあとで使いますので、記録しておいてください。

 .kamal/secrets-commonの作成
/.kamalフォルダにsecrets-commonというファイルを作成してください。
これは機密情報を含みますので、gitには絶対にコミットしないでください。.gitignoreに/.kamal/secrets-common を登録してください
これは機密情報を含みますので、gitには絶対にコミットしないでください！。.gitignoreに/.kamal/secrets-common を登録してください
これは機密情報を含みますので、gitには絶対にコミットしないでください！！。.gitignoreに/.kamal/secrets-common を登録してください

secrets-commonに、先ほどのPersonal Access Tokenを登録します。書き方は下記の通りになります

.kamal/secretsの方は、KAMAL_REGISTRY_PASSWORDのところをコメントアウトしてください
.kamal/secrets-common
KAMAL_REGISTRY_PASSWORD=[先ほどのDockerHubのPersonal access token]
.kamal/secrets
# Option 1: Read secrets from the environment
# KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD

 config/deploy.ymlの編集これがKamalのメインの設定ファイルです。下記のところを変更してください
# Name of your application. Used to uniquely configure containers.
service: [アプリの名前（任意の名前で良いです）：例えば"hotwire-and-next"]

# Name of the container image.
image: [コンテナイメージの名前：<DockerHubのアカウント名>/<イメージ名(任意のもので良いです)：例えば"naofumik/hotwire-and-next"]

# Deploy to these servers.
servers:
  web:
    - [VPSのIPアドレス：例えば "123.456.789.99"]xxx.xxx.xxx.xxx
  # job:
  #   hosts:
  #     - 192.168.0.1
  #   cmd: bin/jobs

# Enable SSL auto certification via Let's Encrypt (and allow for multiple apps on one server).
# Set ssl: false if using something like Cloudflare to terminate SSL (but keep host!).
proxy:
  ssl: true
  host: [VPSのホスト名：例えば "hotwire-n-next.castle104.com"]
  app_port: [Next.jsが動くポート番号："3000"]

# Credentials for your image host.
registry:
  # Specify the registry server, if you're not using Docker Hub
  # server: registry.digitalocean.com / ghcr.io / ...
  username: [DockerHubのアカウント名：例えば"naofumik"]
host:のところは、VPSを登録したときのホスト名でも良いですが、自分でドメイン名を持っていれば、DNSを設定してこのVPSのIPアドレスに向けても良いです。DNSの設定方法については、ここでは紹介しませんが、一般的な内容ですので必要であれば各自でお調べください。

 kamal setupコマンドの実行いよいよデプロイです！
現在のコードをGitにコミットします（GitHub等にpushする必要はありません。ローカルだけで十分です）
コマンドラインからkamal setupを実行します
そうするとKamalは以下の処理を実行します
各サーバにDockerがインストールします

デプロイ時の流れに沿ってデプロイを実行します
最後にブラウザからVPSに接続して、Next.jsのページが正しく表示されることを確認します
!最初にアクセスした時に下記のような画面が表示されます。これはKamalがTLS証明書を作成している途中である時に起きます（説明は割愛します）。しばらくしてリロードすると消えると思います。なお、これは初回セットアップの時だけ起きる可能性があり、以降は問題になりません

 kamal deployコマンドの実行２回目以降はkamal deployを実行すれば十分です（setupを実行しても不具合は起こりませんが）
現在のコードをGitにコミットします（GitHub等にpushする必要はありません。ローカルだけで十分です）
コマンドラインからkamal deployを実行します
そうするとKamalはサーバへのDockerのインストールを省略して、再度、デプロイ時の流れに沿ってデプロイを実行します。

 振り返り流石にVercelにデプロイするときほどは簡単ではありませんが、上記でやったことをまとめました。ぜひお試しいただければと思います。もし引っかかるところやわからないところがありましたら、私もまだ勉強をしたいので、XのDMなどで気軽にご連絡ださい！
VPSをセットアップしました
DockerHubにアカウントを作りました
Next.jsをDocker化しました
Next.jsにhealthcheckのエンドポイントを作成しました
Kamalの設定ファイルを編集しました (7行程度)

kamal setupに実行
Kamalを使って、気軽にたくさんのプロジェクトを作り、たくさん公開しましょう！

脚注
RubyをインストールせずにKamalを実行するためにDockerを使っています。RubyとKamalをインストール済みのDocker Imageをタウンロードして、その中のKamalを実行する仕組みです。Dockerさえインストールされていれば、Rubyをインストールする手間が省けるわけです ↩︎

Kamal 2 を使い、インフラに詳しくない人でもNext.jsを269円のVPSにデプロイできるよう、説明してみる

本記事の目標

前提

作るもの

デプロイ時の流れ

VPSのセットアップ

以降のセットアップのビデオ

ローカルマシンの準備

Node, Git, Dockerのインストール

Kamalの準備

Create Next AppでNext.jsの新しいアプリを作成

Next.jsアプリをDocker化

Next.jsにhealthcheckを導入

Kamalのセットアップ

DockerHubアクセス用のPersonal Access Tokenの取得

`.kamal/secrets-common`の作成

`config/deploy.yml`の編集

`kamal setup`コマンドの実行

`kamal deploy`コマンドの実行

振り返り

Discussion