Deployment & Hosting

This section describes practical deployment strategies aligned to the repository.

Recommended split

• Docs (static): S3 (optionally fronted by CloudFront).
• Runtime: containerized deploy (ECS Fargate behind an ALB).

Operational requirements

• No secrets in repo.
• Health checks and fail-closed semantics.
• Object Lock + correct IAM permissions for archival.

Docs deployment (mdBook -> S3)

Prerequisites

• AWS CLI installed (aws --version).
• mdBook installed (mdbook --version).
  • If you don’t have it yet: cargo install mdbook.

AWS authentication (do not paste secrets into chat)

Configure a dedicated AWS profile and enter your access key/secret at the terminal prompt:

• aws configure --profile cb-docs

Then verify:

• aws sts get-caller-identity --profile cb-docs

Build the docs

From repo root:

• mdbook build docs

Output is written to:

• docs/book/

Option A (fast): Public S3 static website

This is the simplest path to get a URL up quickly.

1. Pick:

• BUCKET (globally unique), e.g. centralbinary-docs-<your-org>-<env>
• REGION, e.g. us-east-1 or us-west-2

2. Create the bucket:

• aws s3api create-bucket --bucket $BUCKET --region $REGION --profile cb-docs (for us-east-1)
• aws s3api create-bucket --bucket $BUCKET --region $REGION --create-bucket-configuration LocationConstraint=$REGION --profile cb-docs (for other regions)

3. Allow public website hosting (intentionally):

• aws s3api put-public-access-block --bucket $BUCKET --public-access-block-configuration BlockPublicAcls=false,IgnorePublicAcls=false,BlockPublicPolicy=false,RestrictPublicBuckets=false --profile cb-docs

4. Attach a read-only bucket policy (public GET objects):

• Create a local file bucket-policy.json with:

  • Resource: arn:aws:s3:::$BUCKET/*

• Then:

  • aws s3api put-bucket-policy --bucket $BUCKET --policy file://bucket-policy.json --profile cb-docs

5. Enable S3 website configuration:

• aws s3 website s3://$BUCKET --index-document index.html --error-document 404.html --profile cb-docs

6. Upload:

• aws s3 sync docs/book s3://$BUCKET --delete --profile cb-docs

Website endpoint:

• http://$BUCKET.s3-website-$REGION.amazonaws.com

Option B (recommended): CloudFront + private bucket

For an institutional public site, the recommended posture is:

• CloudFront distribution
• ACM TLS cert for your domain
• Origin Access Control (OAC)
• S3 bucket kept private (no public policy)

This is a longer setup, but it can be done with CLI only. You can run without a custom domain first (CloudFront default HTTPS domain), then add ACM + Route53 later.

B.1 Create a private bucket (us-east-1)

Set:

• REGION=us-east-1
• BUCKET=<globally-unique-bucket>

Commands:

• aws s3api create-bucket --bucket $BUCKET --region $REGION --profile cb-docs
• aws s3api put-bucket-versioning --bucket $BUCKET --versioning-configuration Status=Enabled --profile cb-docs
• aws s3api put-bucket-encryption --bucket $BUCKET --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"AES256"}}]}' --profile cb-docs
• aws s3api put-public-access-block --bucket $BUCKET --public-access-block-configuration BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true --profile cb-docs

B.2 Upload the built site

• mdbook build docs
• aws s3 sync docs/book s3://$BUCKET --delete --profile cb-docs

B.3 Create an Origin Access Control (OAC)

• aws cloudfront create-origin-access-control --origin-access-control-config '{"Name":"cb-docs-oac","Description":"OAC for CB docs","SigningProtocol":"sigv4","SigningBehavior":"always","OriginAccessControlOriginType":"s3"}' --profile cb-docs

Save the returned Id as OAC_ID.

B.4 Create the CloudFront distribution

Create cloudfront-distribution.json (example values; you must substitute $BUCKET and $OAC_ID):

• Origins[0].DomainName: $BUCKET.s3.$REGION.amazonaws.com
• DefaultRootObject: index.html
• DefaultCacheBehavior.ViewerProtocolPolicy: redirect-to-https

Then:

• aws cloudfront create-distribution --distribution-config file://cloudfront-distribution.json --profile cb-docs

Save:

• Distribution Id as DIST_ID
• Distribution ARN as DIST_ARN
• Distribution domain name (your HTTPS URL)

B.5 Attach a bucket policy allowing CloudFront (OAC)

Create a bucket policy that allows the CloudFront service principal to s3:GetObject with a AWS:SourceArn condition bound to your distribution ARN:

• aws s3api put-bucket-policy --bucket $BUCKET --policy file://bucket-policy-cloudfront.json --profile cb-docs

B.6 Invalidate CloudFront after updates

After any aws s3 sync update:

• aws cloudfront create-invalidation --distribution-id $DIST_ID --paths '/*' --profile cb-docs

B.7 Custom domain (optional)

If you want docs.<your-domain>:

• Request/validate an ACM cert in us-east-1.
• Update distribution aliases + viewer certificate.
• Create a Route53 alias record to the CloudFront distribution.