From zero to your own Naute, in thirty minutes.

None of these are unusual. If you've shipped anything on AWS before, you already have most of them.

You don't need the API key to deploy. You can stand up the stack first, then add the key when you're ready to turn AI on.

Fork the repo first, then clone your fork. Cloning the upstream directly works for a local-only deploy, but step 9 (push-to-main CI/CD) needs you to own the remote — pushes have to land somewhere you control.

Naute is a monorepo with three workspaces — shared, backend, and frontend — plus an infra directory holding the SAM template. The shared package has to be built first because the other two import its types.

After this, npm run lint and sam validate --lint -t infra/template.yaml should both pass — a quick way to confirm your toolchain is wired up before you spend any AWS credits.

The deploy script reads exactly three variables. Everything else — bucket names, Lambda configuration, DynamoDB keys — is derived inside the SAM template.

• NAUTE_DOMAIN — the domain Naute will live on. Example: notes.example.com.
• NAUTE_HOSTED_ZONE_ID — the Route 53 hosted zone ID that owns that domain.
• NAUTE_COGNITO_PREFIX — a unique prefix for your Cognito hosted UI domain. Must be globally unique across AWS.

Put these in your shell profile, a direnv .envrc, or wherever you keep per-project env vars. The deploy script refuses to run if any of the three is missing.

./infra/deploy.sh builds shared types, builds the SAM application, deploys the stack, then builds and syncs the frontend. On this first run only the three NAUTE_* vars from step 3 need to be set — the frontend build inside will produce an incomplete bundle (Cognito values don't exist yet), and we'll replace it in step 5.

First runs take a little longer because ACM has to issue a certificate and CloudFront has to propagate. Don't open the app yet — the frontend won't be able to log you in until step 5.

Six VITE_* values get baked into the frontend bundle at build time. The deploy script reads one of them (VITE_GENERATE_URL, the Function URL of the streaming AI Lambda) straight from the stack outputs, so you never set it by hand. The other five are on you: two (VITE_COGNITO_CLIENT_ID, VITE_COGNITO_DOMAIN) come from the stack you just created; the remaining three are fixed once you've chosen a domain.

Now redeploy:

From here on every deploy is a single pass — SAM sees no infrastructure change and the script just re-syncs the (now correctly-built) frontend.

Prefer not to re-export those vars every time? Drop them into frontend/.env.production and Vite will pick them up automatically on every build. The five values stay constant for the life of the stack.

From the same stack outputs you can also grab the production API host, which step 8 needs to proxy requests from npm run dev:

Naute's Cognito pool is configured with AllowAdminCreateUserOnly: true, so there's no public sign-up. The first user — and every user after — is created via the AWS CLI.

Pull the User Pool ID from the stack outputs:

Then create yourself with a temporary password:

Visit https://your-domain and sign in with that email and temporary password. Cognito's hosted UI prompts you to set a permanent password and — if you enabled TOTP — register an authenticator app. After that, you're in.

Naute's AI features (generate, format) live behind a streaming Lambda that reads its Anthropic key from SSM Parameter Store. The path is hard-coded in the backend:

The Lambda caches it in memory, so a fresh value is picked up on the next cold start (or you can force a redeploy). Skip this step if you'd rather use Naute purely as a markdown editor — every other feature works without it.

Once the stack is up, you have everything you need to run the frontend locally against your real backend. Copy the example env file and fill in the values from the stack you just deployed:

The Cognito client is preconfigured to accept http://localhost:5173/callback as a callback URL, so OAuth works out of the box. For API calls, set API_PROXY_TARGET in .env.local to your deployed API host (the ApiUrl output from step 5, e.g. https://api.your-domain) — Vite uses it to proxy /api through to your real API Gateway. Without it, requests stay on localhost and 404.

To push your changes live, run ./infra/deploy.sh again — SAM will skip the no-op infrastructure change and just re-sync the frontend.

The repo ships a GitHub Actions workflow at .github/workflows/deploy.yml that runs ./infra/deploy.sh on every push to main. It authenticates to AWS via OIDC — no long-lived access keys. Everything below happens in your fork, not the upstream — that's what owning the remote bought you in step 2.

You'll need an IAM role in your AWS account that trusts token.actions.githubusercontent.com and is allowed to assume the same permissions the deploy script uses locally. GitHub publishes the exact trust-policy template for this — paste it in, scope it to your repo, attach a deploy policy, and copy the role ARN.

Then add the following secrets to the repository, under Settings → Secrets and variables → Actions:

The VITE_* values are baked into the frontend bundle at build time, so changing one means re-running the workflow (or ./infra/deploy.sh) to produce a fresh build.

Once the secrets are in place, push to main and the workflow takes over. Subsequent deploys are a git push.