Skip to content

Fix: Set S3 bucket's 404 page on docs release #373

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
straight-shoota merged 1 commit into from
Oct 16, 2025
Merged

Fix: Set S3 bucket's 404 page on docs release #373

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions docs/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,14 +50,22 @@ dist-docs_versions: $(OUTPUT_DIR)/versions-$(CRYSTAL_VERSION).json ## Update `/v

$(OUTPUT_DIR)/versions-$(CRYSTAL_VERSION).json: $(OUTPUT_DIR)/$(OUTPUT_DOCS_BASE_NAME).tar.gz

.PHONY: dist-redirect_latest
dist-redirect_latest: MATCH_CURRENT_ETAG = --name crystal-api-docs-redirects --if-match "$$($(AWS_CLI) cloudfront describe-function --name crystal-api-docs-redirects --output text --query 'ETag')"
dist-redirect_latest: $(OUTPUT_DIR)/aws-cloudfront-redirect.js ## Apply redirect from `api/latest` to `api/$(CRYSTAL_VERSION)` in CloudFront (needs to be manually applied)
.PHONY: release_latest_docs
release_latest_docs: MATCH_CURRENT_ETAG = --name crystal-api-docs-redirects --if-match "$$($(AWS_CLI) cloudfront describe-function --name crystal-api-docs-redirects --output text --query 'ETag')"
release_latest_docs: $(OUTPUT_DIR)/aws-cloudfront-redirect.js $(OUTPUT_DIR)/aws-config.json ## Redirect `api/latest` in CloudFront, and set the 404 page (needs to be manually applied)
$(AWS_CLI) cloudfront update-function $(MATCH_CURRENT_ETAG) --function-config '{"Runtime":"cloudfront-js-2.0","Comment":"Redirects for Crystal API docs $(CRYSTAL_VERSION)"}' --function-code "$(shell base64 -i $(OUTPUT_DIR)/aws-cloudfront-redirect.js)"
$(AWS_CLI) cloudfront publish-function $(MATCH_CURRENT_ETAG)
$(AWS_CLI) s3api put-bucket-website --bucket "$(AWS_BUCKET)" --website-configuration "file://$<"

.PHONY: $(OUTPUT_DIR)/aws-cloudfront-redirect.js
$(OUTPUT_DIR)/aws-cloudfront-redirect.js: aws-cloudfront-redirect.js $(OUTPUT_DIR)

.PHONY: get-website-configuration
get-website-configuration: ## Pull website configuration from S3 bucket (run as `make pull-website-configuration -s > aws-config.json`)
$(AWS_CLI) s3api get-bucket-website --bucket "$(AWS_BUCKET)"

.PHONY: $(OUTPUT_DIR)/aws-config.json
$(OUTPUT_DIR)/aws-config.json: aws-config.json $(OUTPUT_DIR)
sed 's/$${CRYSTAL_VERSION}/$(CRYSTAL_VERSION)/g' "$<" > $@

.PHONY: help
Expand Down
10 changes: 10 additions & 0 deletions docs/aws-config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"IndexDocument": {
"Suffix": "index.html"
},
"ErrorDocument": {
"Key": "api/${CRYSTAL_VERSION}/404.html"
},
"RoutingRules": [
]
}
2 changes: 1 addition & 1 deletion processes/crystal-release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ Add an issue `Crystal release X.Y.Z` in https://github.com/crystal-lang/distribu
1. [ ] Publish API docs
1. Have `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` env variables defined
* Keys can be generated at https://console.aws.amazon.com/iam/home#/security_credentials (contact a Manas admin if you don't have access).
2. Run `make -C docs publish_docs dist-redirect_latest CRYSTAL_VERSION=${VERSION}` to publish docs to `api/${VERSION}` and apply redirect from `api/latest` to `api/${VERSION}`
2. Run `make -C docs publish_docs release_latest_docs CRYSTAL_VERSION=${VERSION}` to publish docs to `api/${VERSION}`, apply redirect from `api/latest` to `api/${VERSION}` and set the 404 error page
3. Update API docs' 404 page to add `<base href="/api/${VERSION}/" />` in the `<head>`
2. [ ] (minor) Publish Crystal book
1. (minor) Create `release/${VERSION%.*}` branch and push it to `crystal-lang/crystal-book` (deployment happens automatically in GHA)
Expand Down