tacocat-gallery-sam

Back end for Tacocat's photo and video gallery. Implemented using the Amazon AWS Serverless Application Model (SAM).

Key services

Service	Purpose
AWS DynamoDB	The database. Contains info about albums, images, and videos
AWS S3	Stores media files, both originals and derived: resizes, thumbnails, transcoded videos
AWS Lambda	API fulfillment, EXIF extraction, image resizing
AWS MediaConvert	Video transcoding
AWS API Gateway	REST API for the front end website
AWS CloudFront	CDN delivery of media (image and video files)
Redis Labs	Search - not an AWS service!

For more info, see docs/Architecture.md.

Getting Started

Prerequisites

• Node.js 24 or higher
• The AWS Serverless Application Model Command Line Interface (SAM CLI)
• esbuild installed globally (npm install --global esbuild)
• I'm using the Visual Studio Code IDE with a lot of extensions, the AWS Toolkit is a key one

Install

• Clone this project from github
• Install dependencies: cd into the project directory, cd app and then install dependencies with npm install or pnpm install or yarn.

Note the app subdirectory! Due to the way SAM handles Typescript, package.json and all the Node.js stuff lives under app.

Build

Build the SAM app with the sam build command:

sam build

This installs dependencies defined in app/package.json, compiles TypeScript with esbuild, creates a deployment package, and saves it in the .aws-sam/build folder.

It does NOT deploy to AWS; that comes later.

Tests

Unit tests

You have to cd app, that's where the Node project is.

cd app && npm test

Integration tests

Integration tests run against the test environment. Deploy first, then run tests:

sam build
sam deploy --config-env test     # Deploy to test environment
cd app && npm run test:integration

Don't run the code locally

SAM provides tools to simulate the AWS cloud locally, but they're more hassle than they're worth. Instead, test your changes by deploying to the dev/staging environment on AWS as described below.

Environments

The project can create three environments. Each environment is a separate AWS infrastructure stack.

Environment	Stack Name	Web App	Purpose
dev	tacocat-gallery-sam-dev	staging-pix.tacocat.com	Staging for manual testing
test	tacocat-gallery-sam-test	test-pix.tacocat.com	Integration tests (CI)
prod	tacocat-gallery-sam-prod	pix.tacocat.com	Production

All developers use the dev/staging stack right now. Yes, this setup is geared towards a single developer.

The web app is not in this project; it's built and hosted in https://github.com/deanmoses/tacocat-gallery-sveltekit.

Deploy while developing

To deploy your local changes during development:

sam sync --watch   # --watch redeploys on file changes

This deploys to the tacocat-gallery-sam-dev AWS stack. The web app at https://staging-pix.tacocat.com is connected to this stack.

Automatic deployment when merging to main

When a PR is merged into main, the CI/CD system (GitHub Actions) automatically runs tests and deploys to staging. This overwrites anything you deployed to it with sam sync.

Deploy to prod

1. You need access to the repo
2. On GitHub, go to Actions > Deploy to Production
3. Click "Run workflow" and select the main branch
4. The workflow:
   1. Runs tests
   2. Deploys to prod (the tacocat-gallery-sam-prod AWS stack)
      1. The live web app https://pix.tacocat.com/ is attached to the prod stack
   3. Creates a GitHub release (like 2027v2) with auto-generated release notes

Working with remote logs

The sam logs command fetches logs generated by your deployed Lambda functions.

Tail ALL Lambda functions in your AWS account:

sam logs --include-traces --tail

Tail a specific function:

sam logs --include-traces --tail -n HelloWorldFunction

Common Commands

npm commands run from the app/ directory, sam commands run from project root:

# Testing and linting
npm test              # unit tests with silent console output
npm run test:verbose  # unit tests with console output. Use for debugging only, this gets pretty noisy
npm run test:integration  # integration tests (requires AWS credentials)
npm run test:all      # all tests (unit + integration)
npm run lint          # ESLint with auto-fix

# Building and deploying
sam build             # Build SAM application
sam deploy --no-execute-changeset  # Validate template without deploying
sam deploy            # Deploy to dev/staging
sam sync --watch      # Deploy to dev/staging and watch mode for rapid dev iteration

# Logs
sam logs --include-traces --tail         # All function logs
sam logs -n FunctionName --tail          # Specific function logs

# Documentation
npm run agent-docs    # Regenerate CLAUDE.md and AGENTS.md from docs/AGENTS.src.md