Quickstart

Prerequisites

Tool	Minimum version	Purpose
Node.js	20.x	CDK CLI and Docusaurus
AWS CLI	2.x	CDK deploy and S3 operations
AWS CDK CLI	2.x	Deploy CDK stacks

You will also need an AWS account with permissions to create S3 buckets, IAM roles, and CloudFormation stacks.

1 — Bootstrap the CDK environment

If this is the first time using CDK in your AWS account and region:

cdk bootstrap aws://ACCOUNT_ID/eu-west-1

2 — Deploy the infrastructure

git clone https://github.com/neulabscom/neulabs-docubuilder.git
cd neulabs-docubuilder/infra
npm install
cdk deploy --all \
  --context account=YOUR_ACCOUNT_ID \
  --context region=eu-west-1

This creates:

• S3 bucket neulabs-docs-swamp with public read on bootstrap/*
• GitHub OIDC IAM roles for CI/CD (no long-lived credentials needed)

3 — Configure GitHub Actions variables

In the neulabs-docubuilder repository settings → Variables, add:

Variable	Value
AWS_DOCS_ROLE_TO_ASSUME	ARN of github-oidc-workflow-role (from CDK output)
AWS_DEPLOY_ROLE_ASSUME	ARN of github-oidc-deploy-role (from CDK output)
AWS_REGION	eu-west-1

CDK prints these ARNs as stack outputs at the end of cdk deploy.

4 — Publish the bootstrap assets

Trigger the upload workflow from GitHub Actions → Upload bootstrap template to S3 → Run workflow, or push any change under bootstrap/.

After it completes, these public URLs become active:

https://neulabs-docs-swamp.s3.eu-west-1.amazonaws.com/bootstrap/doc_template.zip
https://neulabs-docs-swamp.s3.eu-west-1.amazonaws.com/bootstrap/docubuilder.sh

5 — Add docs to any project

From the root of any Neulabs repository:

curl -fsSL https://neulabs-docs-swamp.s3.eu-west-1.amazonaws.com/bootstrap/docubuilder.sh | bash

The script is interactive. Here is the full terminal session for a repository that does not yet have a docs/ folder:

  docubuilder  Neulabs documentation bootstrap
  ────────────────────────────────────────

  What will happen:
  1. Download the Docusaurus template from S3
  2. Create a new docs/ directory from the template

  Download doc_template.zip from https://neulabs-docs-swamp.s3.eu-west-1.amazonaws.com/bootstrap? [y/N] y

  › Downloading doc_template.zip...
  ✓ Downloaded.

  › Extracting template...
  ✓ Extracted.

  Create new docs/ directory from template? [y/N] y
  ✓ Created docs/ directory.

  ────────────────────────────────────────
  All done!

  What happened:
  ✓ Downloaded the Docusaurus template from S3
  ✓ Created docs/ from the template

  Next steps:
  1. cd docs
  2. npm install          — install Docusaurus dependencies
  3. npm run start        — preview the site locally
  4. Edit docs/intro.md   — start writing your documentation
  5. npm run build        — build for production

If a docs/ folder already exists the second confirmation prompt changes to ask whether to merge the template in, and existing files are left untouched (cp -rn).