v260414.01 2:55p
← Back to setup

AlpacApps Setup Guide

This page is designed for Claude to read and follow. It contains step-by-step instructions for guiding a user through the complete AlpacApps infrastructure setup.

Instructions for Claude Chat

One step at a time: Present ONE sub-step, wait for the user to confirm they've done it, then move to the next sub-step. Do NOT give multiple instructions in one message. For example, don't say "install Git, create a GitHub account, and install the GitHub CLI" — instead say "First, let's check if Git is installed. Open your terminal and run git --version. What do you see?" Then wait.

Checkpoint rule: Do not move to Step N+1 until every item in Step N is explicitly confirmed by the user. If the user says they've already completed something, still confirm it — ask them to verify (run a command, paste a screenshot, or state the result). "I already did that" requires a quick proof before proceeding.

Chat vs Code: Steps 1–3 happen here in Claude Chat. The user cannot switch to Claude Code until after Step 3, because Claude Code needs a local project folder to open — and that folder doesn't exist until they clone the repo. Do NOT mention Claude Code or tell the user to switch to it until the clone in Step 3 is confirmed.

Screenshot verification: At each step that requires the user to interact with a website or application (GitHub, Supabase, Google Cloud, Cloudflare, etc.), ask them to paste a screenshot so you can verify they're on the right page and guide them to the correct buttons and fields.

Adapting to the user: Adapt commands and instructions to their OS (Mac, Windows, Linux). If they've already completed a full step (e.g., "I already have a Supabase project"), confirm the key details you'll need (project ref, password, etc.) and move on — but still follow step order.

1 Understand what they're building

Before any setup, ask the user one question:

What kind of project? Two profiles are available:

Record their profile choice. You'll need it for the Claude Code setup wizard later. Service selection happens at the end — don't discuss it now.

2 Check prerequisites

Operating system

Ask what OS they're using. This affects install commands throughout.

Xcode Command Line Tools (Mac only)

On Mac, always install Xcode Command Line Tools first — this provides Git, compilers, and other developer essentials that Claude Code needs.

Ask the user to open Terminal and run:

xcode-select --install

If already installed, the terminal will say so and they can move on. If not installed:

  1. A system dialog will appear asking to install — click "Install"
  2. Then click "Agree" to the license agreement
The install dialog hides behind other windows! After running the command, the confirmation dialog almost always appears BEHIND the Terminal window and other open apps. Tell the user to check behind all their open windows or use Mission Control (swipe up with three fingers, or press F3) to find the dialog. If they don't see anything happening, it's hiding — not missing.

The download is ~1–2 GB and can take several minutes. Wait for it to complete before moving on.

Ask the user to confirm the install finished by running git --version. They should see a version number (e.g., git version 2.39.5).

Install all prerequisites (Mac — one command)

After Xcode CLI Tools are confirmed, run the prerequisite installer. This installs or upgrades: git, GitHub CLI, Node.js, Supabase CLI, Wrangler, psql, TypeScript.

bash <(curl -fsSL https://alpacaplayhouse.com/scripts/install-prereqs.sh)

If the user already has Homebrew and prefers granular control, they can also use brew bundle from the project's Brewfile after cloning.

Ask the user to confirm the script completed successfully. It prints a summary of all installed tools and versions at the end.

Prerequisites (Windows / Linux)

If the user is NOT on Mac, they need to install these manually:

Ask the user to confirm they can run git --version && node --version successfully.

GitHub account & CLI auth

Ask if they already have a GitHub account. If not, direct them to github.com/signup.

Then authenticate the GitHub CLI:

gh auth login

The CLI will ask a series of questions. Tell the user to:

  1. "What account do you want to log into?" — Press Enter to pick the default (GitHub.com)
  2. "What is your preferred protocol?" — Press Enter to pick the default (HTTPS)
  3. "Authenticate Git with your GitHub credentials?" — Type Y and press Enter
  4. "How would you like to authenticate?" — Press Enter to pick Login with a web browser
  5. A one-time code will appear — press Enter, paste the code in the browser, and authorize
Ask the user to confirm they have a GitHub account and gh auth status shows "Logged in".

Claude Desktop

Claude Desktop is the AI app that includes Claude Code — the AI developer that handles all terminal work, database setup, and code generation.

  1. If you don't have a Claude account, sign up at claude.ai (Pro $20/mo recommended — free week here)
  2. Download Claude Desktop from claude.ai/download
  3. Install and open the app, then sign in with your Claude account

3 Create the GitHub repository

Use the template

Direct the user to the template repository:

github.com/rsonnad/alpacapps-infra

  1. Click the green "Use this template" button at the top right
  2. Click "Create a new repository"
  3. Enter a repository name (lowercase with hyphens, e.g., my-salon-app)
  4. Make sure "Public" is selected (required for free GitHub Pages)
  5. Click "Create repository"
Ask the user to paste a screenshot of their new repository page. Verify it shows their repo name and has files from the template (index.html, shared/, supabase/, etc.).

Enable GitHub Pages

In their new repository:

  1. Go to Settings (gear icon near the top of the repo page)
  2. Click "Pages" in the left sidebar
  3. Under "Build and deployment" → Source: select "Deploy from a branch"
  4. Branch: select "main" and folder "/ (root)"
  5. Click "Save"

The site will be live at https://USERNAME.github.io/REPO-NAME/ within 1–2 minutes.

Ask for a screenshot of the Pages settings page showing "main" branch selected. After 1–2 minutes, ask them to visit their site URL to confirm it loads.

Clone the repository locally

Back in their terminal:

git clone https://github.com/USERNAME/REPO-NAME.git
cd REPO-NAME

Replace USERNAME and REPO-NAME with their actual values. If they set up gh, they can also use gh repo clone USERNAME/REPO-NAME.

Ask them to confirm they see the project files by running ls (Mac/Linux) or dir (Windows) in the project folder.

Switch to Claude Code

Now that the repo is cloned locally, switch to Claude Code for the rest of the setup:

  1. Open Claude Desktop
  2. Click the Code tab (or start a new Claude Code session)
  3. Open your project folder — navigate to the directory you just cloned
  4. Switch to Opus 4.6 — Claude Code defaults to Sonnet, but you want the most capable model. Click the model selector (bottom of the chat) and choose Claude Opus 4.6 (or the latest available model)
  5. Enable "Bypass permissions" — This lets Claude Code run terminal commands without asking you to approve each one. Open Claude Code settings (click the gear icon or press Cmd + , on Mac / Ctrl + , on Windows), find "Bypass permissions" (or "Yolo mode"), and turn it on.
Why bypass permissions? The setup wizard runs dozens of terminal commands (installing CLIs, running database migrations, deploying functions). Without bypass, Claude Code will pause and ask you to approve every single command — which makes the process painfully slow. You can always turn it off later.
Model matters! Claude Code defaults to Sonnet, which is fast but less capable. For infrastructure setup and complex tasks, switch to Opus 4.6 (or the latest version) — it handles multi-step setup wizards, database migrations, and edge function deployment much more reliably.

From this point on, Claude Code handles everything: terminal commands, database setup, edge functions, and code generation. You can paste the remaining instructions directly into Claude Code.

Ask the user to confirm they have Claude Code open in their project folder with bypass permissions enabled and Opus 4.6 selected. They should see the project files and be ready to run commands.

4 Set up Supabase

Create a Supabase account and project

  1. Go to supabase.com/dashboard
  2. Sign up or log in (GitHub login is easiest)
  3. Click "New Project"
  4. Choose your organization (or create one)
  5. Enter a project name (e.g., same as your repo name)
  6. Set a strong database password — save this somewhere safe, you'll need it next
  7. Select a region close to your users
  8. Click "Create new project"
Important: Save your database password! Supabase only shows the password during project creation. If you lose it, you'll need to reset it in Settings → Database → Database Password.
Ask for a screenshot of their Supabase project dashboard. It should show the project name and a "Getting Started" or home page.

Find your project ref

The project ref is the random string in the Supabase URL. It looks like this:

https://supabase.com/dashboard/project/abcdefghijklm

The bolded part is the project ref. Alternatively:

  1. Go to Settings (gear icon in the sidebar)
  2. Click "General"
  3. The "Reference ID" is your project ref
Ask the user to share their project ref (the random string) and confirm they have their database password saved. You'll need both for the next step.

What you'll need for the setup wizard

Record these two values — you'll paste them into Claude Code in Step 6:

5 Set up Cloudflare

Cloudflare manages your domain’s DNS and provides a D1 database for session logging. You only need to provide two things — Claude handles the rest.

Get your Cloudflare Global API Key

  1. Sign up or log in at dash.cloudflare.com
  2. Go to Profile → API Tokens
  3. Find "Global API Key" and click "View"
  4. Copy the key — this is all Claude needs to manage DNS, D1, R2, and Workers for you
Why the Global API Key? It already exists on every Cloudflare account — no token creation wizard needed. Claude will use it once to create a scoped project token with only the permissions your project needs, then use that scoped token for all ongoing operations.
Ask the user to confirm they have their Cloudflare email and Global API Key. You'll need both for the setup wizard.

What you'll need for the next step

Record these values — you'll paste them into Claude Code in the next step:

6 Run the setup wizard in Claude Code

Open Claude Code in your project folder and let it handle all the technical setup.

Open Claude Code

  1. Open the Claude desktop app (or terminal)
  2. Navigate to your project folder from Step 3
  3. If on the Max plan ($100/mo), type: /setup-alpacapps-infra

If on the Pro plan ($20/mo) or lower, paste this prompt instead:

Set up my AlpacApps project. I chose the [PROFILE] profile and want these services: [LIST].
My Supabase project ref is: [REF]
My database password is: [PASSWORD]
My Cloudflare email is: [EMAIL]
My Cloudflare Global API Key is: [CF_KEY]

Follow the setup wizard in .claude/skills/setup-alpacapps-infra/SKILL.md to configure everything.
Handle all terminal work — CLI installs, database setup, edge functions, git pushes.
Ask me when you need credentials for optional services (API keys, etc.).

Replace the bracketed values with:

What the wizard does

Claude Code will automatically:

  1. Install and configure the Supabase CLI
  2. Link your Supabase project and fetch API keys
  3. Create database tables with Row Level Security
  4. Set up storage buckets
  5. Deploy edge functions
  6. Validate your Cloudflare key and create a scoped project token
  7. Set up DNS and D1 session logging database
  8. Configure each optional service you selected (asking you for API keys as needed)
  9. Generate your CLAUDE.md and documentation files
  10. Commit and push everything to GitHub

Going forward

After setup, Claude Code is how you build everything. Just describe what you want:

Claude Code handles the code, commits, and deploys.

Core setup complete! Your site is live on GitHub Pages with a fully configured Supabase backend and Cloudflare managing your domain. Next: install gstack (quick, 30 seconds), then optionally add more services.

7 Install gstack

gstack adds powerful skills to Claude Code: headless browser for QA testing, code review, ship workflow, engineering retrospectives, and more. Sub-second commands with zero token overhead.

In your Claude Code session, run:

curl -fsSL https://raw.githubusercontent.com/garrytan/gstack/main/install.sh | bash

Verify it installed:

ls ~/.claude/skills/gstack/SKILL.md

If the file exists, gstack is installed and Claude Code will automatically detect the skills.

Available skills

Update later: Run /gstack-upgrade inside Claude Code, or re-run the install script.

Source: github.com/garrytan/gstack (MIT license)

Ask the user to confirm gstack installed by checking if the SKILL.md file exists.

8 Add optional services

Your core stack is running. Now walk through these optional services and ask which ones they want to add. Claude Code will configure each one — just provide the API keys when asked.

Which services do they need?

For each service the user selects, walk them through the vendor signup below, then have Claude Code configure it.

You're done! Start building by telling Claude Code what you want — it handles the code, commits, and deploys.
Advanced: Conductor (parallel agents)

Want to run multiple Claude Code agents in parallel? Download Conductor — it lets you create separate workspaces that each run their own agent on their own git branch. Great for tackling multiple tasks simultaneously.

? Optional services reference

When the agent asks for credentials for optional services, direct the user to these vendor pages. For each service, the user needs to create an account and get an API key.

Google Sign-In (OAuth)

Resend (Email)

Telnyx (SMS)

Square (Payments)

Stripe (Payments)

SignWell (E-Signatures)

Google Gemini (AI)

Cloudflare R2 (Storage)

Uses the Cloudflare Global API Key you provided in Step 5 — no additional credentials needed.

Cloudflare D1 (DevControl)

The setup wizard creates two D1 databases using the Global API Key from Step 5:

Both are free tier (5M reads/day, 100K writes/day, 5 GB storage).

Other ways to get started:

Setup hub (overview) Quick start (for humans) Full manual guide Sync new features