Skip to content

Latest commit

 

History

History
434 lines (342 loc) · 36.1 KB

smalruby-web-hosting.md

File metadata and controls

434 lines (342 loc) · 36.1 KB

smalruby-web-hosting (Web 配信基盀むンフラ)

🆕 Smalruby 独自 — Smalruby の Web フロント゚ンドを AWSS3 + CloudFrontから配信するための基盀。

抂芁

infra/smalruby-web-hosting/ は、Smalruby の GUI を AWS から配信するための CDK プロゞェクト。 最初の甚途はブランチプレビュヌpreview.smalruby.app/<slug>/。

stg ステヌゞに、preview.smalruby.app のホストゟヌンお名前.com から NS 委任枈みず、 プレビュヌの配信基盀S3 + CloudFront + ACM 蚌明曞 + CI 甹 IAM ロヌルを眮く。 プレビュヌを S3 に眮くのは CI䞋の「CI のプレビュヌ」。このプロゞェクトは眮き堎所ず配信の仕組みだけを䜜る。

ステヌゞごずのリ゜ヌス

Stage スタック名 リ゜ヌス
stg SmalrubyWebHostingStack-stg パブリックホストゟヌン preview.smalruby.app、S3 バケット、CloudFront、ACM 蚌明曞us-east-1、A / AAAAALIAS、CI 甹 IAM ロヌル
prod SmalrubyWebHostingStack 本番 smalruby.app の配信基盀S3 バケット、CloudFront、ACM 蚌明曞us-east-1、CI 甹 IAM ロヌルず、パブリックホストゟヌン smalruby.appお名前.com のレコヌドを写したもの。CloudFront には代替ドメむン smalruby.app が付いおおり、apex の A / AAAA は CloudFront の ALIAS䞋の「本番の配信基盀prod」「ホストゟヌン smalruby.appprod」
その他stg2 等 SmalrubyWebHostingStack-<stage> なし
  • プレビュヌは stg の API を芋るので、プレビュヌ甚の資源は stg ステヌゞに眮く。
  • Deploy Infra は develop ぞのマヌゞで prod にも出す。prod でプレビュヌ甚のリ゜ヌスができないよう、 プレビュヌ甚の資源は stg だけに䜜る同じ名前のゟヌンが耇数あるず、どれが委任先か分からなくなる。
  • prod には本番smalruby.appの配信基盀ず smalruby.app のゟヌンだけを䜜る。stg2 などほかのステヌゞでは䜕も䜜らない。

ホストゟヌン preview.smalruby.app

項目 倀
皮類 パブリックホストゟヌン
removalPolicy RETAIN — 䜜り盎すず NS が倉わり、お名前.com に登録した NS ず食い違う
Output PreviewHostedZoneNameServers NS 4 本カンマ区切り。お名前.com の委任に䜿う
Output PreviewHostedZoneId ホストゟヌン ID

smalruby.app 自䜓の DNS はお名前.com で管理しおいる。preview サブドメむンだけを お名前.com から Route 53 ぞ NS レコヌドで委任する。委任するたで誰もこのゟヌンを参照しない ので、本番の DNS には圱響しない。

NS は stg デプロむ埌に次で確認する:

aws cloudformation describe-stacks --stack-name SmalrubyWebHostingStack-stg \
  --query "Stacks[0].Outputs" --output table

ゟヌンを䜜り盎すずきRETAIN の埌始末

ゟヌンは RETAIN なので、スタックを消しおも、論理 ID やスタック名が倉わっお CloudFormation が 「削陀 + 新芏䜜成」ず刀断しおも、叀いゟヌンは AWS に残る。Route 53 は同じ名前のゟヌンを いく぀でも䜜れるため、そのたた出し盎すず NS の違う 2 ぀目の preview.smalruby.app が黙っおできる。 お名前.com の委任は叀いゟヌンの NS を向いたたたなので、新しいゟヌンに足したレコヌド蚌明曞の 怜蚌レコヌドや CloudFront の別名は倖から芋えない。

そもそも䜜り盎さないのが基本論理 ID・スタック名・ゟヌン名を倉えない。やむを埗ないずきは、 たず同名のゟヌンがいく぀あるかを確かめる:

aws route53 list-hosted-zones-by-name --dns-name preview.smalruby.app \
  --query "HostedZones[?Name=='preview.smalruby.app.'].[Id,Config.Comment]" --output table

そのうえで次のどちらかを遞ぶどちらも人間が手元で行う。

  • 残ったゟヌンを取り蟌むNS が倉わらない。こちらを優先: スタックが無い状態で npx cdk import --context stage=stg を実行し、PreviewHostedZone に残ったゟヌンの ID を枡す。 お名前.com の NS はそのたたでよい。取り蟌んだあずは通垞どおり Deploy Infra で出す。
  • 残ったゟヌンを消しお䜜り盎すNS が倉わる: 残ったゟヌンの NS / SOA 以倖のレコヌドを消しおから ゟヌンを消し、Deploy Infra で出し盎す。新しい NS 4 本Output PreviewHostedZoneNameServersを お名前.com の委任に登録し盎す。登録し盎すたで preview.smalruby.app は匕けない。

蚌明曞を埌から足した理由

ACM の DNS 怜蚌は、公開 DNS から怜蚌レコヌドCNAMEが匕けるたで蚌明曞を発行しない。 委任前にゟヌンず蚌明曞を同じデプロむで䜜るず、CloudFormation が蚌明曞の発行を埅ち続けお タむムアりトし、デプロむが倱敗する。そこで「ゟヌン → 委任 → 蚌明曞ず配信基盀」の順に分けた。

プレビュヌの配信基盀

ブラりザ ── https://preview.smalruby.app/<slug>/ ──▶ CloudFront ──(OAC)──▶ S3 (private)
                                                    │  viewer-request: /<slug>/ → /<slug>/index.html、/<slug>/gui.js → .br / .gz
                                                    │  viewer-response: 圧瞮版に Vary: Accept-Encoding
                                                    └─ 蚌明曞: ACM (us-east-1)

S3 バケット

項目 倀
公開蚭定 Block Public Access 党郚 ON。読めるのは CloudFrontOACだけ。enforceSSL
キヌ <slug>/...プレビュヌず、ルヌトの auth-redirect.html / auth-redirect.js
ラむフサむクル 最埌に眮いおから 365 日経ったオブゞェクトを消す消し忘れの保険。䞻な片付けはブランチ削陀時の CI ゞョブ。未完了のマルチパヌトアップロヌドは 7 日で砎棄
removalPolicy DESTROYCI から䜜り盎せるため。autoDeleteObjects は付けないので、オブゞェクトが残っおいる間はバケットの削陀が倱敗しお止たる

ラむフサむクルはオブゞェクト単䜍そのオブゞェクトを最埌に put した日から数える。CI が aws s3 sync で差分だけ䞊げるず、倉わっおいないファむルは叀い日付のたた残るので、1 幎以䞊 続くブランチでは䞀郚のファむルだけが消えうる。長く続くブランチがあるずきは、党ファむルを 眮き盎すaws s3 cp --recursive。

CloudFront

項目 倀
代替ドメむン preview.smalruby.app蚌明曞は us-east-1 の ACM。DnsValidatedCertificate でこのゟヌンを䜿っお DNS 怜蚌する
オリゞン S3 + OACOrigin Access Control
viewer-requestCloudFront Functions /<slug>/ や /<slug>/x/ → .../index.html。/<slug> のように末尟 / も拡匵子も無いものは /<slug>/ ぞ 301ク゚リ文字列は保぀。gui の JS/<slug>/gui.js・/<slug>/gui.<hash>.jsは Accept-Encoding に応じお事前圧瞮版の .br優先/ .gz ぞ曞きかえるヘッダが無い・どちらも受け取らないずきはそのたた。それ以倖はそのたたinfra/smalruby-web-hosting/lib/functions/preview-viewer-request.js。芏則は docs/hosting/README.md の「URI の曞きかえず Vary」
viewer-responseCloudFront Functions Content-Encoding のある応答事前圧瞮版に Vary: Accept-Encoding を付けるlib/functions/preview-viewer-response.js。HSTS などほかのヘッダは付けない
キャッシュ Cache-Control の無いオブゞェクトぱッゞで 60 秒、Cache-Control があればそれに埓う最長 1 幎。キャッシュキヌにク゚リ文字列・ヘッダ・Cookie を含めない
その他 HTTPS ぞリダむレクト、TLS 1.2 以䞊、HTTP/2 ず HTTP/3、Price Class 200日本を含む

CI がアップロヌドするずきの玄束キャッシュを効かせるため:

  • index.html などハッシュの付かないファむルauth-redirect.html / auth-redirect.js / sw.js などは Cache-Control: max-age=0, s-maxage=60 を付ける。゚ッゞには 60 秒だけ残り、 ブラりザは毎回確かめ盎す。Cache-Control を付けないず゚ッゞは既定の 60 秒になるが、ブラりザが Last-Modified から勝手に鮮床を芋積もっお叀い index.html を䜿い続けるこずがある。 no-cache だけを付けるず゚ッゞにも残らないMinTTL が 0 のため。
  • ファむル名にハッシュが付いたもの*.<hash>.js、static/assets/*.<hash>.*。 /\.[0-9a-f]{8,}\./は Cache-Control: public, max-age=31536000, immutable を付ける。
  • 眮き盎したら /<slug>/* を invalidation するすぐに反映させたいずき。
  • gui の JSプレビュヌは gui.js、本番は gui.<hash>.jsは、事前に圧瞮した .brbrotli q11ず .gzgzip -9も隣に眮く。CloudFront は 10,000,000 バむトを超えるファむルを圧瞮しないため。 Content-Type: text/javascript・Content-Encoding: br / gzip・元ず同じ Cache-Control を aws s3 cp で明瀺し、index.html より前に眮く。䜜り方ず理由は docs/hosting/README.md の 「事前圧瞮した gui の JS」。viewer-request 関数が gui の JS をこの .br / .gz ぞ曞きかえるので、 圧瞮版が無いず br / gzip を受け取るブラりザには 404 になるscripts/precompress-assets.mjs を通さずに眮かない。

Microsoft ログむンの戻り先 /auth-redirect.html

Microsoft ログむンは window.location.origin + '/auth-redirect.html' に戻る packages/scratch-gui/src/lib/microsoft-auth.js。プレビュヌでは origin が https://preview.smalruby.app なので、バケットのルヌトに auth-redirect.html ず、それが読む auth-redirect.js を眮けば配信されるCloudFront Function は拡匵子付きのパスを玠通しする。 眮くのは CI の圹目。

DNS

preview.smalruby.appゟヌンの頂点に A / AAAA の ALIAS レコヌド→ CloudFrontを眮く。 ワむルドカヌドは䜜らないdocs/security/github-pages-subdomain-takeover.md。

CI 甹 IAM ロヌルGitHub OIDC

項目 倀
ä¿¡é Œ アカりントに䜜成枈みの OIDC プロバむダ token.actions.githubusercontent.comDeploy Infra ず共甚。アカりントに 1 ぀しか䜜れないので参照するだけ。aud = sts.amazonaws.com か぀ sub が repo:smalruby/smalruby3-editor:*
暩限 このバケットの s3:ListBucket / s3:PutObject / s3:DeleteObject、このディストリビュヌションの cloudfront:CreateInvalidation / cloudfront:GetInvalidation だけ
セッション 最長 1 時間

Output

Output 甹途
PreviewDeployRoleArn CI が AssumeRole するロヌルEnvironment stg の Variables に登録する
PreviewBucketName プレビュヌを眮くバケット
PreviewDistributionId invalidation の察象
PreviewDistributionDomainName CloudFront のドメむンALIAS の向き先。確認甚
aws cloudformation describe-stacks --stack-name SmalrubyWebHostingStack-stg \
  --query "Stacks[0].Outputs" --output table

動䜜確認手で眮いお芋る

BUCKET=<PreviewBucketName>
echo '<h1>preview test</h1>' > /tmp/index.html
aws s3 cp /tmp/index.html "s3://$BUCKET/test/index.html" --content-type text/html
curl -sI https://preview.smalruby.app/test/   # 200
curl -sI https://preview.smalruby.app/test    # 301 → /test/
aws s3 rm "s3://$BUCKET/test/index.html"

本番の配信基盀prod

本番 https://smalruby.app/ を GitHub Pages から移すための眮き堎所。蚈画・切り替えの手順・戻し方・費甚は docs/hosting/README.md。CloudFront には smalruby.app の蚌明曞ず代替ドメむンを 付け、apex の A / AAAA を CloudFront の ALIAS にしおある段 9。この倉曎が prod に出た時点で、利甚者の リク゚ストは GitHub Pages ではなく CloudFront に来る。戻し方は docs/hosting/README.md の「戻し方」。

リ゜ヌス 内容
S3 バケット SiteBucket Block Public Access 党郚 ON・enforceSSL・バヌゞョニングあり。䞊曞き・削陀された叀い版は 30 日で消し、残った削陀マヌカヌも片付ける。いたの版は期限で消さないプレビュヌずの違い。removalPolicy は RETAIN䞋の「本番のバケットを RETAIN にする理由」
CloudFront SiteDistribution 代替ドメむンは smalruby.app だけwww.smalruby.app は今は無いので付けない。蚌明曞は SiteCertificate、TLS 1.2 以䞊TLSv1.2_2021・SNI。オリゞンは S3 + OAC。viewer-request はプレビュヌず同じコヌドlib/functions/preview-viewer-request.jsの別の関数 SiteViewerRequest定額プランの配信には、ほかの配信に付いおいる関数を付けられない。/ → /index.html、拡匵子の無い URL/admin などは /<path>/ ぞ 301芏則は docs/hosting/README.md の「拡匵子の無い URL」。gui の JS/gui.<hash>.jsは Accept-Encoding に応じお事前圧瞮版の .br / .gz ぞ曞きかえる「URI の曞きかえず Vary」。存圚しないファむルS3 が返す 403 ず 404は、カスタム゚ラヌ応答で /404.html を応答コヌド 404 で返す゚ラヌのキャッシュは 60 秒。SITE_NOT_FOUND_PAGE_PATH / SITE_ERROR_CACHING_MIN_TTL_SECONDS。ペヌゞはビルドの packages/scratch-gui/pages/404.html。CloudFront の定額プランProに入れるため、カスタムのキャッシュポリシヌず応答ヘッダポリシヌは䜿わない定額プランでは䜿えない。キャッシュポリシヌは AWS 管理の CachingOptimizedキヌはプレビュヌず同じくク゚リ文字列・ヘッダ・Cookie なし・gzip / br。TTL は CI が付ける Cache-Control に埓う。Cache-Control が無いず既定の 1 日になる点がプレビュヌず違う。HSTS1 幎・includeSubDomains なしず X-Content-Type-Options: nosniff は viewer-response 関数lib/functions/site-viewer-response.jsで付ける。同じ関数が、Content-Encoding のある応答事前圧瞮版に Vary: Accept-Encoding も付ける関数はオリゞンの゚ラヌ4xx / 5xxず viewer-request 関数が返す 301 では動かないので、それらには付かない。HTTP/2 ず HTTP/3、Price Class は All定額プランは料金クラスを持たない。配信は定額プラン Pro に入っおいる。WAF の Web ACLSITE_WEB_ACL_ARN・CreatedByCloudFront-...はプランが䜜っお配信に付けたもので、CDK は䜜らず webAclId で ARN を参照するだけ消さない・䞭身を倉えない。倖すずプランの条件から倖れる。倉えるずきはコン゜ヌルでプランず付いおいる Web ACL を確かめおから定数を曞き換える。暙準ログ埓来の S3 配信・Cookie なしを SiteLogBucket の cloudfront/smalruby.app/ に出す
ACM 蚌明曞 SiteCertificate smalruby.appSAN なし。CloudFront 甚なので us-east-1 に、DnsValidatedCertificate で䜜り、SiteHostedZone で DNS 怜蚌する怜蚌の CNAME はこのゟヌンに曞かれる。スタックは分けない。ネヌムサヌバヌを Route 53 に倉えおから足した倉える前だず怜蚌が終わらず、デプロむが蚌明曞を埅ち続けお倱敗する。プレビュヌの「蚌明曞を埌から足した理由」ず同じ
S3 バケット SiteLogBucket アクセスログ専甚。Block Public Access 党郚 ON・SSE-S3・enforceSSL。暙準ログは ACL で曞き蟌たれるので Object Ownership は BucketOwnerPreferredACL を無効にしない。SITE_ACCESS_LOG_RETENTION_DAYS30 日を過ぎたログは消す。バヌゞョニングなし・removalPolicy は DESTROYログが無くおも配信は止たらない。䞭身が残っおいる間は削陀が倱敗しお止たる。方匏を遞んだ理由ず個人情報の扱いは docs/hosting/README.md の「アクセスログ段 5」
CI 甚ロヌル SiteDeployRole 既存の GitHub OIDC プロバむダを参照。信頌は repo:smalruby/smalruby3-editor:ref:refs/heads/develop ず ...:environment:prod だけプレビュヌより狭い。暩限はこのバケットの ListBucket / PutObject / DeleteObject ず、このディストリビュヌションの invalidation だけ

本番のバケットを RETAIN にする理由

デヌタ保持の決たり.claude/rules/infra/development.mdでは、ビルドから䜜り盎せるバケットは DESTROY に する。本番の配信バケットはその䟋倖で RETAIN にする。䞭身は䜜り盎せるが、切り替え埌に消えるず smalruby.app がその堎で止たるため、スタックの削陀や論理 ID の倉曎CloudFormation から芋るず削陀 + 新芏䜜成 で消えないようにする。

  • 残ったバケットを䜿い盎すずきは、スタックが無い状態で npx cdk import --context stage=prod を実行し、 SiteBucket に残ったバケットの名前を枡す人間が手元で行う。
  • 芁らなくなっお消すずきは、䞭身叀い版ず削陀マヌカヌを含むを空にしおから、人間がコン゜ヌルか CLI で消す。
  • 叀い版を残す日数いたは 30 日は人間が決める倀。案: 切り替えから 1 か月は 30 日のたた、萜ち着いたら 7〜14 日に瞮めお保存の費甚を抑える。

代替ドメむンず蚌明曞は、既存のディストリビュヌションぞの蚭定の远加で、眮き換えreplacementにはならない 論理 ID SiteDistribution を倉えない。代替ドメむンを付けおも、DNS が CloudFront を向くたで利甚者のリク゚ストは 来ない。apex を CloudFront の ALIAS に倉えるのは段 9 の別の倉曎。

Output 甹途
SiteDeployRoleArn CI が AssumeRole するロヌルrepo の Variables SITE_DEPLOY_ROLE_ARN に登録する
SiteBucketName ビルドを眮くバケットSITE_BUCKET_NAME
SiteDistributionId invalidation の察象SITE_DISTRIBUTION_ID
SiteDistributionDomainName CloudFront のドメむン切り替え前の確認甚
SiteCertificateArn smalruby.app の蚌明曞us-east-1。発行状態の確認に aws acm describe-certificate --region us-east-1 --certificate-arn <倀>
SiteLogBucketName アクセスログのバケット調べるずきに aws s3 ls s3://<倀>/cloudfront/smalruby.app/
aws cloudformation describe-stacks --stack-name SmalrubyWebHostingStack \
  --query "Stacks[0].Outputs" --output table

手で眮いお確かめるprod のバケットなので、確かめたら消す:

BUCKET=<SiteBucketName>
DOMAIN=<SiteDistributionDomainName>
echo '<h1>site test</h1>' > /tmp/index.html
aws s3 cp /tmp/index.html "s3://$BUCKET/index.html" --content-type text/html \
  --cache-control 'max-age=0, s-maxage=60'
curl -sI "https://$DOMAIN/"   # 200・strict-transport-security が付く
aws s3 rm "s3://$BUCKET/index.html"

CI からの配眮GitHub Pages ず䞊べお眮く

.github/workflows/ci-cd.yml の build-and-deploy は、develop ぞの push のたびに、GitHub Pages ぞ出したのず 同じビルドをこのバケットにも眮く。切り替えるたでの本番は GitHub Pages のたたで、こちらは CloudFront の ドメむンでしか芋えない。

  • repo の Variables SITE_DEPLOY_ROLE_ARN / SITE_BUCKET_NAME / SITE_DISTRIBUTION_ID のどれかが無いずきは、 warning を出しお飛ばすGitHub Pages ぞの配眮は続ける。
  • ゞョブに id-token: write を足すため、ゞョブの permissions で workflow の暩限contents / issues / pull-requests の writeも曞き盎しおいるゞョブに曞くず workflow の分は匕き継がれない。
  • 眮き方はプレビュヌず同じ「CI がアップロヌドするずきの玄束」: ハッシュ付きのファむルは public, max-age=31536000, immutable、それ以倖は max-age=0, s-maxage=60。.wasm / .mjs / .hex は Content-Type を明瀺する。gui の JS の .br / .gz も眮く䞊の玄束の最埌の項目。最埌に --delete --size-only で叀いファむルを消す。
  • 本䜓packages/scratch-gui/distはバケットの盎䞋、管理 SPApackages/admin/buildは admin/ に眮く。 本䜓の --delete は admin/* を陀き、管理 SPA の --delete は admin/ の䞭だけに効く。 .well-known/ などドットで始たるものも眮く。GitHub Pages 甚の .nojekyll ず CNAME は眮かない。
  • 眮いたあずに /* を invalidation する。

ホストゟヌン smalruby.appprod

本番のドメむン smalruby.app の DNS を、お名前.com から Route 53 ぞ移すためのゟヌンdocs/hosting/README.md の段 2。 お名前.com のネヌムサヌバヌを、このゟヌンの NS 4 本に倉えるたで人間が倜間に行う、誰もこのゟヌンを匕かない。 だから䜜っただけでは、いたの本番には䜕も起きない。

項目 倀
皮類 パブリックホストゟヌン論理 ID SiteHostedZone
removalPolicy RETAIN — 䜜り盎すず NS が倉わり、お名前.com に登録したネヌムサヌバヌず食い違う
Output SiteHostedZoneNameServers NS 4 本カンマ区切り。お名前.com のネヌムサヌバヌの蚭定に䜿う
Output SiteHostedZoneId ホストゟヌン ID

写したレコヌド倀は infra/smalruby-web-hosting/lib/site-zone-records.ts。お名前.com の゚クスポヌトず同じ倀:

名前 型 数 TTL 内容
smalruby.app A ALIAS — CloudFront SiteDistribution段 9。論理 ID は GitHub Pages の IP185.199.108〜111.153・TTL 300を曞いおいたずきず同じ SiteApexA のたた眮き換えではなく曎新にするため。倉えない
smalruby.app AAAA ALIAS — CloudFront SiteDistribution段 9 で足した。論理 ID SiteApexAAAA
smalruby.app TXT 1 300 google-site-verification=...Search Console の所有確認
_github-pages-challenge-smalruby.smalruby.app TXT 1 3600 GitHub の組織のドメむン怜蚌。消さないdocs/security/github-pages-subdomain-takeover.md
smalruby.app CAA 6 3600 issue amazon.com / amazonaws.com / amazontrust.com / awstrust.com / letsencrypt.org、issuewild ";"
api.smalruby.app NS 4 900 API 矀のゟヌンぞの委任いたの NS のたた
preview.smalruby.app NS 4 900 stg の PreviewHostedZone ぞの委任いたの NS のたた

写さないもの: apex の NS / SOARoute 53 のものになる、everdiary.smalruby.app A䜿っおいないこずを人間が確かめ、お名前.com からも消した。ワむルドカヌドは䜜らない。

  • お名前.com 偎のレコヌドを倉えたら、ここも同じ倀にするネヌムサヌバヌを倉えるたでは䞡方に曞いおおく決たり。 照合は scripts/hosting/dns-compare.mjsdocs/hosting/verify-scripts.mdで、お名前.com の゚クスポヌトず cdk synth の結果、たたは䞡方のネヌムサヌバヌぞの問い合わせを比べる。
  • NS の倀は末尟に . を付けお曞くゟヌン名を足した盞察名ず読たれないように。
  • apex の A / AAAA は CloudFront の ALIAS段 9。本番の向き先が倉わる倉曎なので、PR は人間が倜間にマヌゞした。 お名前.com のゟヌンには ALIAS が曞けないので、ここから先はお名前.com の゚クスポヌトず apex の A が䞀臎しない照合では apex の A / AAAA を陀いお芋る。

NS はデプロむ埌に次で確認する:

aws cloudformation describe-stacks --stack-name SmalrubyWebHostingStack \
  --query "Stacks[0].Outputs[?starts_with(OutputKey, 'SiteHostedZone')]" --output table

smalruby.app のゟヌンを䜜り盎すずきRETAIN の埌始末

考え方は䞊の「ゟヌンを䜜り盎すずき」preview.smalruby.appず同じ。䜜り盎さないのが基本 論理 ID SiteHostedZone・スタック名 SmalrubyWebHostingStack・ゟヌン名を倉えない。やむを埗ないずきは、 たず同名のゟヌンがいく぀あるかを確かめる:

aws route53 list-hosted-zones-by-name --dns-name smalruby.app \
  --query "HostedZones[?Name=='smalruby.app.'].[Id,Config.Comment]" --output table

泚意: RETAIN なのはゟヌンだけで、レコヌドは DESTROY。NS を切り替えたあずにスタックを消すず、apex の A ず api. / preview. の委任が消えお smalruby.app が止たる。䜜り盎すずきは、ゟヌンを cdk import で取り蟌んでから deploy する。

そのうえで次のどちらかを遞ぶどちらも人間が手元で行う。

  • 残ったゟヌンを取り蟌むNS が倉わらない。こちらを優先: スタックが無い状態で npx cdk import --context stage=prod を実行し、SiteHostedZone に残ったゟヌンの ID を枡す。 お名前.com のネヌムサヌバヌはそのたたでよい。
  • 残ったゟヌンを消しお䜜り盎すNS が倉わる: お名前.com のネヌムサヌバヌをただ倉えおいないずきだけ遞ぶ。 倉えたあずに消すず、smalruby.app も api. / preview. も匕けなくなる。残ったゟヌンの NS / SOA 以倖の レコヌドを消しおからゟヌンを消し、Deploy Infra で出し盎す。新しい NS 4 本Output SiteHostedZoneNameServersを 䜿う。

CI のプレビュヌ

䜕を どこで
ビルドしお眮く .github/workflows/ci-cd.yml の preview-deployPR ず develop ぞの push
片付ける .github/workflows/preview-cleanup.ymlPR を閉じたずき・週 1 回・手動
slug scripts/preview-slug.mjsテストは scripts/preview-slug.test.mjs。ゞョブの䞭でも走らせる

preview-deploy の流れ:

  1. ゚ンドポむントが stg を向いおいるか確かめる。Environment stg に倀が無いず repo の倀prodで 黙っおビルドされ、プレビュヌが本番のデヌタを読み曞きしおしたう。MESH_GRAPHQL_ENDPOINT / RUBYTEE_RELAY_ENDPOINT / CLASSROOM_API_ENDPOINT / BUG_REPORT_API_ENDPOINT / SCRATCH_API_PROXY_ENDPOINT のホストが 1 ぀でも stg. で始たらなければ、ビルドせずにゞョブを倱敗させる 倀は secret なので出さず、名前だけを出す。
  2. ブランチ名から slug を䜜るdevelop は develop。正芏化で名前が倉わるブランチには元の名前の ハッシュ 8 桁が付く。芏則は .claude/rules/infra/development.md の「ブランチプレビュヌで確かめる」。
  3. stg の倀で npm run build する。ゞョブは environment: stg で動くので、Environment stg に眮いた Secrets / Variables゚ンドポむント・メッシュの API キヌ・SCRATCH_API_PROXY_ENDPOINTが repo の 同名の倀より優先される。prod ず同じ倀Google / Microsoft のクラむアント ID・メッセヌゞ長・メッシュの 間隔は repo の倀をそのたた䜿う。倀の䞀芧は docs/infra/stg-prod-differences.md の「GUI のビルド倀」。
  4. PUBLIC_PATH=/<slug>/ で postbuild.mjs を走らせ、fetch-worker のパスを絶察パスにする ビルド自䜓は盞察パスなので、眮き堎所を遞ばない。
  5. GitHub OIDC で PreviewDeployRoleArn を AssumeRole し、s3://<bucket>/<slug>/ に眮く。䞊の 「CI がアップロヌドするずきの玄束」どおり、ハッシュ付きのファむルずそれ以倖で Cache-Control を 分けお 2 回 sync しその間に gui.js.br / gui.js.gz を aws s3 cp で眮く、最埌に --delete --size-only で新しいビルドに無いものを消す。その前に postbuild.mjs のあずで scripts/precompress-assets.mjs packages/scratch-gui/build が .br / .gz を䜜る。
  6. develop のずきだけ、バケットのルヌトに auth-redirect.html / auth-redirect.js を眮く 党プレビュヌが共有するので、ブランチからは䞊曞きしない。
  7. /<slug>/* を invalidation し、PR なら 1 回だけ URL をコメントする。

GitHub Pages ぞのプレビュヌsmalruby.jp/smalruby3-editor/<branch>/・prod の APIず develop 版 smalruby.jp/smalruby3-editor/の出力はやめた。gh-pages ブランチに残っおいる内容は消さずに眮いおあり、 もう曎新されない。本番smalruby.appは埓来どおり build-and-deploy が smalruby/smalruby.app ぞ出す。

  • ブランチ単䜍の concurrency はワヌクフロヌ党䜓のたたプレフィックスが分かれおいるので、 ブランチ間で競合しない。
  • fork からの PR・dependabot/ / renovate/・hotfix/ / main / master では出さない。
  • Environment stg の Variables PREVIEW_DEPLOY_ROLE_ARN / PREVIEW_BUCKET_NAME / PREVIEW_DISTRIBUTION_ID䞊の Output の倀が未蚭定なら、譊告を出しおプレビュヌを飛ばす PR は倱敗させない。登録は bin/gh-admin variable set <NAME> --env stg --body <value>。

片付けpreview-cleanup.yml:

  • PR を閉じたら、その head ブランチの <slug>/ を消しお invalidation する。
  • 週 1 回月曜 03:00 JST、git ls-remote --heads に無いブランチのプレフィックスを消す。 develop ずルヌトのファむルauth-redirect.*は消さない。消し挏れの保険は䞊のラむフサむクル365 日。

デプロむ

stg / prod ずも GitHub Actions の Deploy Infra.github/workflows/deploy-infra-stg.ymlから出す .claude/rules/infra/development.md。この workflow は repo Secrets の .env を䜿うので、 次の 2 ぀を登録しおおく:

Secret 眮き堎所 内容
INFRA_STG_DOTENV_SMALRUBY_WEB_HOSTING repo Secrets infra/smalruby-web-hosting/.env.stg
INFRA_PROD_DOTENV_SMALRUBY_WEB_HOSTING Environment prod の Secrets infra/smalruby-web-hosting/.env.prod
bin/gh-admin secret set INFRA_STG_DOTENV_SMALRUBY_WEB_HOSTING < infra/smalruby-web-hosting/.env.stg
bin/gh-admin secret set INFRA_PROD_DOTENV_SMALRUBY_WEB_HOSTING --env prod < infra/smalruby-web-hosting/.env.prod

.env の䞭身は STAGE だけでよいinfra/smalruby-web-hosting/.env.example。

Secrets が無いたたマヌゞするず、Deploy Infra のこのプロゞェクトのゞョブだけが「䜕を登録すべきか」を 瀺しお倱敗するほかのプロゞェクトは進む。

prod のデプロむ

prod には本番の配信基盀䞊の「本番の配信基盀prod」ず smalruby.app のゟヌンがある。远加だけの差分なので、develop ぞの マヌゞで Deploy Infra が自動で出す。削陀・眮き換えを含む差分は自動では出ず、人間が確かめお手元から出す。 prod にプレビュヌ甚のリ゜ヌスはできない。

テスト

cd infra/smalruby-web-hosting
npm install
npm test                                  # aws-cdk-lib/assertions によるスタックのテスト
npx cdk synth --context stage=stg
npx cdk synth --context stage=prod

テストは「stg にゟヌンがあり RETAIN・論理 ID が倉わらない」「NS ず ID を Output」 「バケットが非公開・SSL 必須・ラむフサむクルあり」「蚌明曞が us-east-1」「CloudFront が OAC・ 代替ドメむン・viewer-request 関数぀き」「ALIAS にワむルドカヌドが無い」「CI 甚ロヌルの信頌ず暩限が 最小」「prod にはプレビュヌ甚の資源が無く、本番の配信基盀非公開・バヌゞョニングあり・いたの版を消さない・ 独自ドメむンも蚌明曞も無い・develop だけを信頌するロヌルず、アクセスログのバケット非公開・暗号化・ 保持期間で消える・CI 甚ロヌルから觊れないがある」「stg2 には䜕も䜜らない」を確かめる。test/site-zone.test.ts は「prod に smalruby.app のゟヌンが 1 ぀あり RETAIN・論理 ID が倉わらない」「写した レコヌドがお名前.com の倀ず同じapex の A だけ TTL 300」「apex の NS / SOA・everdiary・ワむルドカヌドが無い」 「stg / stg2 にはこのゟヌンが無い」を確かめる。test/preview-viewer-request.test.ts は CloudFront Function の実コヌド本番ずプレビュヌで共甚を評䟡しお URI の曞き換えgui の JS の .br / .gz を含むを確かめる。 test/site-viewer-response.test.ts / test/preview-viewer-response.test.ts は viewer-response 関数のヘッダHSTS / nosniff・Varyを確かめる。

CI.github/workflows/ci-infra.yml の [web-hosting] Unit Tests / CDK Build & Synth / Security Auditが、infra/** を倉える PR ず push で同じテストず、stg / prod 䞡方の cdk synth を行う。

䞻芁ファむル

ファむル 圹割
infra/smalruby-web-hosting/bin/smalruby-web-hosting.ts ゚ントリポむント。stage ずスタック名を決める
infra/smalruby-web-hosting/lib/web-hosting-stack.ts スタック本䜓stg: ホストゟヌン・プレビュヌの配信基盀・CI 甚ロヌル / prod: 本番の配信基盀 createSiteDelivery()・ゟヌン createSiteZone()
infra/smalruby-web-hosting/lib/site-zone-records.ts smalruby.app のゟヌンに写すレコヌドの倀お名前.com ず同じ
infra/smalruby-web-hosting/lib/functions/preview-viewer-request.js viewer-request の CloudFront Function のコヌドディレクトリの URL → index.html、拡匵子の無い URL → /<path>/ ぞ 301、gui の JS → .br / .gz。本番ずプレビュヌで共甚関数のリ゜ヌスは別
infra/smalruby-web-hosting/lib/functions/site-viewer-response.js 本番の viewer-response の CloudFront Function のコヌドHSTS / nosniff・圧瞮版に Vary
infra/smalruby-web-hosting/lib/functions/preview-viewer-response.js プレビュヌの viewer-response の CloudFront Function のコヌド圧瞮版に Vary だけ
infra/smalruby-web-hosting/test/web-hosting.test.ts スタックのテスト
infra/smalruby-web-hosting/test/site-zone.test.ts smalruby.app のゟヌンのテスト写したレコヌドの䞀芧・RETAIN・prod だけに䜜る
infra/smalruby-web-hosting/test/preview-viewer-request.test.ts viewer-request の CloudFront Function のテスト本番ずプレビュヌで共甚
infra/smalruby-web-hosting/test/site-viewer-response.test.ts / preview-viewer-response.test.ts viewer-response の CloudFront Function のテスト
.github/workflows/ci-cd.ymlpreview-deploy プレビュヌを stg の倀でビルドしお眮く
.github/workflows/preview-cleanup.yml プレビュヌの片付け
scripts/preview-slug.mjs ブランチ名 → slug