Solanasis Docs

01-human-setup-guide

12 min read

Solanasis Website — Human Setup Guide

What this is: Only the steps that require a human — browser dashboards, account creation, OAuth login, and secure credential storage. Everything else (installing tools, scaffolding the project, building the site) Claude Code handles for you.

Time estimate: 30-45 minutes

Security model: This guide follows the three-tier security architecture defined in solanasis-credentials-security-playbook.md. Credentials are stored in a local .env file (Tier 1), never pasted into chat prompts or committed to git.

What we’re building: A brand new Astro static site for solanasis.com, deployed to Cloudflare Pages. The project will live in a new directory on your machine — Claude Code will scaffold it from a theme.

Phase 1: Create Accounts (10 min)

Claude Code cannot create accounts on your behalf — these require browser signup and payment info.

1.1 — GitHub Account

  • Go to github.com → Sign up (or confirm you’re logged in)
  • Note your GitHub username: _______________

1.2 — Cloudflare Account

Phase 2: Domain & DNS (15-20 min)

You already own solanasis.com on Namecheap. This phase points it to Cloudflare so Cloudflare manages DNS (required for free hosting, SSL, and Turnstile).

2.1 — Add Your Domain to Cloudflare

  • Go to Cloudflare dashboard → Websites → Add a site
  • Enter solanasis.com → Select Free plan → Click Continue
  • Cloudflare will scan your existing DNS records and import them — review these carefully:
    • Make sure any existing records you need (like email MX records) are imported
    • If you currently have a live site, Cloudflare will import those A/CNAME records too (they’ll be replaced later when we deploy)
  • Cloudflare shows you two nameservers — write them down:
    • Nameserver 1: _______________ (e.g., ada.ns.cloudflare.com)
    • Nameserver 2: _______________ (e.g., bob.ns.cloudflare.com)

2.2 — Update Nameservers in Namecheap

What’s happening: You’re telling Namecheap “stop managing DNS for solanasis.com — Cloudflare handles it now.” Your domain registration stays on Namecheap; only DNS resolution moves.

  • Log in to namecheap.com → Domain List → click Manage next to solanasis.com
  • Scroll to the Nameservers section
  • Change the dropdown from Namecheap BasicDNS (or whatever it currently says) to Custom DNS
  • Enter the two Cloudflare nameservers from Step 2.1:
    • Nameserver 1: (paste the first one from Cloudflare)
    • Nameserver 2: (paste the second one from Cloudflare)
  • Click the green checkmark to save

Pro Tip: Don’t touch anything in cPanel for this — nameserver changes happen at the registrar level (the Namecheap Domain List page), not in cPanel. cPanel manages hosting on Namecheap’s servers, which we’re replacing entirely with Cloudflare. Once nameservers point to Cloudflare, cPanel DNS settings are ignored.

2.3 — Verify Domain is Active on Cloudflare

  • Go back to Cloudflare dashboard → click solanasis.com
  • Status should show Active (green checkmark)
    • If it says “Pending” → nameservers haven’t propagated yet. This usually takes 15 min to 1 hour, but can take up to 24 hours.
    • You can check propagation at dnschecker.org — search for solanasis.com NS records
  • Domain active on Cloudflare: ✓

⚠️ Important: Once nameservers point to Cloudflare, your old Namecheap hosting (if any) stops resolving. If you have a live site on Namecheap hosting, it will go down until Cloudflare is configured. Since we’re building a brand new site, this is fine — but be aware if you have email or other services tied to the old DNS.

Phase 3: Brevo Email Setup (15-20 min)

All of these steps happen in Brevo and Cloudflare dashboards. You already have a Brevo account.

3.1 — Verify Your Domain with Brevo

  • Go to app.brevo.com → log in
  • Navigate to Senders, Domains & Dedicated IPs → Domains tab
  • Click Add a domain → enter solanasis.com
  • Brevo will show you DNS records to add. Open a second browser tab to your Cloudflare DNS settings:
    • Cloudflare dashboard → solanasis.com → DNS → Records

Add these DNS records in Cloudflare (Brevo tells you the exact values):

  • DKIM Record:

    • Type: TXT
    • Name: (Brevo specifies — usually something like mail._domainkey)
    • Content: (copy the value Brevo provides)
    • TTL: Auto

  • Brevo Verification Code:

    • Type: TXT
    • Name: @
    • Content: (copy the value Brevo provides — starts with brevo-code:)
    • TTL: Auto

  • SPF Record:

    • Type: TXT
    • Name: @
    • Content: v=spf1 include:sendinblue.com ~all
    • TTL: Auto
    • ⚠️ Important: If you already have an SPF record (a TXT record starting with v=spf1), DON’T create a second one. Instead, EDIT the existing one and add include:sendinblue.com before the ~all part.

  • DMARC Record (strongly recommended):

    • Type: TXT
    • Name: _dmarc
    • Content: v=DMARC1; p=quarantine; rua=mailto:dmarc@solanasis.com
    • TTL: Auto

  • Go back to Brevo → click Verify

    • Green checkmarks should appear as DNS propagates (usually 5-30 min with Cloudflare)
    • If they don’t appear immediately, wait 15 min and click Verify again

3.2 — Add a Verified Sender

  • In Brevo → Senders, Domains & Dedicated IPs → Senders tab
  • Click Add a sender
  • From name: Solanasis
  • From email: info@solanasis.com (must be on your verified domain)
  • Click Save
  • Brevo sends a verification email → check your inbox → click the confirmation link

3.3 — Generate a Brevo API Key

  • In Brevo → click your name/avatar → SMTP & API
  • Click the API Keys tab
  • Click Generate a new API key
  • Name: solanasis-website
  • Click Generate
  • Copy the key immediately (starts with xkeysib-)
  • Save it in your password manager — you’ll paste it into the .env file in Phase 6
    • ⚠️ You cannot view this key again after leaving this page
  • Brevo API key saved: ✓

3.4 — Create a Newsletter Contact List

  • In Brevo → Contacts → Lists
  • Click Create a list
  • Name: Solanasis Newsletter
  • Click into the list after creation
  • Note the List ID — it’s the number in the URL (e.g., https://app.brevo.com/contacts/lists/3 → List ID is 3)
  • List ID: _______________

Phase 4: Cloudflare Turnstile (5 min)

Turnstile is Cloudflare’s free spam protection. Widget creation is dashboard-only.

4.1 — Create a Turnstile Widget

  • Go to Cloudflare dashboard → Turnstile (in the left sidebar)
  • Click Add Widget
  • Name: solanasis-forms
  • Domains: add BOTH of these:
    • solanasis.com (your production domain)
    • localhost (for local development testing)
  • Widget Mode: Managed (recommended)
  • Pre-clearance: No
  • Click Create

4.2 — Save the Keys

  • Site Key (starts with 0x4...): _______________
    • This one is public — it gets embedded in your HTML form (that’s by design)
  • Secret Key (starts with 0x4...): _______________
    • This one is private — it stays server-side. Save it in your password manager.

Phase 5: Authenticate CLI Tools (10 min)

Why you do this (not Claude Code): Both gh auth login and wrangler login open a browser window where you click “Authorize” on GitHub’s/Cloudflare’s consent screen. Claude Code cannot interact with your browser — it only runs terminal commands. These two steps are the only CLI commands in the entire process that require human interaction.

Alternative for Cloudflare: If you’d rather skip wrangler login, you can create a Cloudflare API Token in the dashboard instead (see 5.2 Option B below). Claude Code can then use the token from your .env file without needing interactive login.

5.1 — Authenticate GitHub CLI

  • Open a terminal and run: gh auth login
    • If it says gh: command not found, run brew install gh (macOS) or winget install GitHub.cli (Windows) first, or let Claude Code install it when you hand off
  • Follow the prompts:
    1. Select: GitHub.com
    2. Select: HTTPS
    3. Select: Login with a web browser
    4. Copy the one-time code shown in the terminal
    5. Browser opens → paste the code → click Authorize
  • Verify: run gh auth status → should show “Logged in to github.com as YOUR_USERNAME”

Why not a token? gh auth login stores an OAuth token securely on your machine and auto-refreshes it. This is more secure than a Personal Access Token (PAT) because you never handle the token directly and it can’t be accidentally committed.

5.2 — Authenticate Cloudflare (Pick ONE option)

Option A: Interactive Login (Simpler — recommended for personal machines)

  • Run: wrangler login
    • If it says wrangler: command not found, run npm install -g wrangler first (or let Claude Code install it when you hand off)
  • Browser opens → click Allow to authorize Wrangler
  • Run npx wrangler whoami → note your Account ID: _______________

Option B: API Token (No browser needed — better for CI/CD and contractor machines)

  • Go to Cloudflare dashboard → My Profile (top right) → API Tokens
  • Click Create Token
  • Use the Edit Cloudflare Workers template (or create a custom token with Workers + Pages permissions)
  • Zone Resources: select your domain or “All zones”
  • Click Continue to summary → Create Token
  • Copy the token immediately — you can only see it once
  • Save it in your password manager
  • Add it to your .env file as CLOUDFLARE_API_TOKEN (there’s no line for this in the default sample.env — add it under the CLOUDFLARE_ACCOUNT_ID line)
  • Get your Account ID from the Cloudflare dashboard URL or any page → note it: _______________

Pro Tip: Option B is what you’ll use for contractors anyway (see the security playbook’s Contractor Access Model). Each contractor gets their own scoped API token with limited permissions — they never use wrangler login on their machines. So if you set up Option B now, you’re already practicing the pattern you’ll use at scale.

Phase 6: Create Your .env File (5 min)

Why you do this instead of Claude Code: Following the security playbook (Tier 1), credentials should never appear in chat prompts, logs, or terminal history. You create the .env file manually so your keys only exist in two places: your password manager and this file on disk.

6.1 — Create the Project Directory

  • Open a terminal and create the directory where the site will live:
mkdir -p ~/projects/solanasis-site

What this is: A brand new empty directory. Claude Code will scaffold the full Astro project inside it (clone theme, install dependencies, create all files). You’re just creating the container folder and the .env file.

6.2 — Create the .env File

A pre-built template is included in this config folder: sample.env. It has all the variable names, inline instructions for where to get each value, and the security warnings from the playbook.

  • Copy it into your project directory and rename it to .env:
cp [path-to-this-folder]/website-config/sample.env ~/projects/solanasis-site/.env
  • Open ~/projects/solanasis-site/.env in a text editor
  • Fill in the Project Configuration section (top of file):
    • GITHUB_USERNAME — your GitHub username from Phase 1.1
    • GITHUB_REPO_NAME — defaults to solanasis-site (change if you want a different repo name)
    • SITE_URL — defaults to https://solanasis.com (update if using a different domain)
    • SITE_DOMAIN — defaults to solanasis.com
    • SITE_NAME — defaults to Solanasis
    • CLOUDFLARE_PAGES_PROJECT — defaults to solanasis-site
  • Fill in the Credentials section:
    • CLOUDFLARE_ACCOUNT_ID — from Phase 5.2
    • CLOUDFLARE_API_TOKEN — ONLY if you chose Option B in Phase 5.2 (uncomment the line first)
    • BREVO_API_KEY — from Phase 3.3
    • BREVO_LIST_ID — from Phase 3.4
    • BREVO_SENDER_EMAIL — defaults to info@solanasis.com
    • BREVO_SENDER_NAME — defaults to Solanasis
    • TURNSTILE_SITE_KEY — from Phase 4.2
    • TURNSTILE_SECRET_KEY — from Phase 4.2
  • .env file created and populated: ✓

What Claude Code does with this file: During Phase 0 of the build plan, Claude Code reads every variable from .env, validates the format, tests the API keys against live services, and reports a preflight summary before building anything. If any value is missing or invalid, it stops and tells you exactly what to fix. The .env file is the single source of truth — Claude Code never hardcodes project names, domains, or credentials.

⚠️ Security note: Claude Code will add .env to .gitignore when scaffolding the project, but always double-check. A single accidental commit of your .env file means you need to rotate every key in it immediately — even if you force-push to remove it, the old commit is still in git history and can be recovered. See the security playbook for the full incident response procedure.

Phase 7: Hand Off to Claude Code

You’re done! Open Claude Code in your terminal inside the project directory and give it the build plan:

cd ~/projects/solanasis-site

Then tell Claude Code:

Follow the build plan in [path-to]/02-claude-build-plan.md to build the Solanasis website.
The .env file is in the project root with all configuration and credentials.

That’s it. Everything Claude Code needs — your GitHub username, repo name, domain, project names, API keys — is in the .env file. You don’t need to pass anything else in the chat.

Notice: You’re not sharing any credentials in the chat prompt. All sensitive API keys AND project configuration live in the .env file which Claude Code reads from disk. This follows the Tier 1 security model from the credentials playbook.

Claude Code will then:

  1. Install any missing tools (Node.js, gh, wrangler)
  2. Read ALL configuration and credentials from the .env file
  3. Run a comprehensive preflight check (validate every variable, test API keys, check DNS, send a test email)
  4. Print a preflight summary and wait for your confirmation
  5. Create the GitHub repo under your account (if it doesn’t already exist)
  6. Start building the site following 02-claude-build-plan.md

Quick Reference — What You Need to Collect

.env VariableWhere to get itSecret?Phase
GITHUB_USERNAMEgithub.com profileNo1.1
GITHUB_REPO_NAMEYou choose (default: solanasis-site)No—
SITE_URLYour domain with https://No—
SITE_DOMAINYour domain without protocolNo2.1
CLOUDFLARE_PAGES_PROJECTYou choose (default: solanasis-site)No—
CLOUDFLARE_ACCOUNT_IDwrangler login or dashboard URLNo5.2
CLOUDFLARE_API_TOKENDashboard → API Tokens (Option B only)YES5.2
BREVO_API_KEYBrevo → SMTP & API → API KeysYES3.3
BREVO_LIST_IDBrevo → Contacts → Lists → number in URLLow3.4
BREVO_SENDER_EMAILMust match verified senderNo3.2
BREVO_SENDER_NAMEYour brand nameNo—
TURNSTILE_SITE_KEYCloudflare → Turnstile → your widgetNo (public)4.2
TURNSTILE_SECRET_KEYCloudflare → Turnstile → your widgetYES4.2

Pro Tip: Keep these values in your password manager. You’ll reuse this same pattern for every client site you build — the only things that change are the domain, Brevo sender email, Turnstile widget, and GitHub repo name. Over time, this becomes a 15-minute setup since you already know the workflow.

About the GitHub repo: Claude Code creates the repo for you under $GITHUB_USERNAME/$GITHUB_REPO_NAME during Phase 7 of the build plan. If the repo already exists (e.g., you re-run the build), Claude Code detects it and pushes to the existing repo instead of creating a duplicate. You don’t need to create the repo yourself.

Once all checkboxes are checked, proceed to 02-claude-build-plan.md.

Graph View

Backlinks