Alpha Client Onboarding Checklist

Alpha Client Onboarding Checklist

Version: 1.1 (Alpha Phase) Last Updated: March 10, 2026 Estimated Total Time: 25-35 minutes Success Rate Target: 95% completion without support

---

🎯 Your Mission

Welcome to Seed & Source Alpha! This checklist will guide you from installation to your first successful deployment. Each step has clear success indicators so you know when to move forward.

Alpha Expectations:

• ⚠️ You may encounter rough edges—that’s why we need your feedback!
• ⚠️ Breaking changes may occur between versions during alpha
• ✅ We’re here to help: support@seedsource.dev (response time: 4-8 hours)

Your Alpha portals:

• 🖥️ Account Dashboard: https://account.seedsource.dev — view your license, tier, API token, and available templates
• 📦 CLI: sscli on PyPI — generate and manage your project templates

Before You Start:

• You have a GitHub account (used for authentication via sscli auth login)
• You have 30 minutes of uninterrupted time
• You’re ready to provide feedback on any friction points

---

✅ Phase 1: Environment Setup (10 minutes)

Step 1.1: Verify Prerequisites (3 minutes)

Check your system has:

# Check Python version (need 3.11+)
python3 --version

# Check Docker is running
docker ps

# Check Git is installed
git --version

Success Indicators:

• ✅ Python shows version 3.11.0 or higher
• ✅ Docker command returns container list (even if empty)
• ✅ Git shows version 2.x or higher

Common Issues:

❌ “command not found: python3”

• macOS/Linux: Install from python.org or use brew install python@3.11
• Windows: Download from python.org, ensure “Add to PATH” is checked during install

❌ “Cannot connect to the Docker daemon”

• Solution: Start Docker Desktop (macOS/Windows) or sudo systemctl start docker (Linux)
• Verify: The Docker Desktop icon should show “running” status

Time checkpoint: If this step took more than 5 minutes, ask for help before proceeding.

---

Step 1.2: Install Stack CLI (2 minutes)

# Install from PyPI
pip3 install sscli

# Verify installation
sscli --version

Success Indicators:

• ✅ Installation completes without errors
• ✅ sscli --version returns something like: Stack CLI version 3.2.1
• (Upgrade existing install: pip install --upgrade sscli)

Common Issues:

❌ “command not found: sscli” after installation

• Cause: pip installed to a location not in your PATH

• Solution:

  # Try with python3 -m
  python3 -m pip install --user sscli
  
  # Or add pip's user bin to PATH (add to ~/.zshrc or ~/.bashrc)
  export PATH="$HOME/.local/bin:$PATH"
  source ~/.zshrc  # or source ~/.bashrc

❌ “ERROR: Could not find a version that satisfies the requirement sscli”

• Cause: pip is looking at the wrong index
• Solution:

  pip3 install --upgrade pip
  pip3 install sscli

⏱️ Estimated time so far: 5 minutes

---

Step 1.3: Authenticate with License Server (5 minutes)

# Start authentication flow
sscli auth login

What happens:

1. CLI initiates the GitHub OAuth device-code flow
2. A device code and URL are shown in the terminal
3. You open github.com/login/device in your browser and enter the code
4. After authorizing, the CLI receives the token and authenticates automatically

Success Indicators:

• ✅ CLI displays a device code and prompts you to visit github.com/login/device
• ✅ After entering the code in your browser, you see a GitHub authorization prompt
• ✅ CLI shows: ✓ Successfully authenticated as <your-email>
• ✅ CLI shows: License Tier: ALPHA

⚠️ NOTE: Authentication tokens are stored locally by the CLI. To re-authenticate on a new machine, simply run sscli auth login again with the same GitHub account.

Common Issues:

❌ “Authentication failed: device authorization expired”

• Solution: The device code expires in ~15 minutes. Run sscli auth login again and complete the browser step promptly
• Still failing?: Email support@seedsource.dev with subject “Alpha Auth Issue”

❌ Terminal stays waiting but browser doesn’t open automatically

• Solution: Copy the URL and device code shown in the terminal and visit github.com/login/device manually

❌ “License tier: FREE” instead of “ALPHA”

• Cause: Your GitHub account hasn’t been granted ALPHA access yet by our team
• Solution: Email support@seedsource.dev with your GitHub username
• Note: All templates (including python-saas, react-client, rails-api, static-landing, python-worker-service) require at least ALPHA tier

Validate your authentication:

# This should show your username and ALPHA tier
sscli whoami

⏱️ Estimated time so far: 10 minutes

---

🚀 Phase 2: Generate Your First Project (10 minutes)

Step 2.1: Create Project Directory (1 minute)

# Create and navigate to your workspace
mkdir -p ~/projects/my-alpha-test
cd ~/projects/my-alpha-test

Success Indicator:

• ✅ You’re in an empty directory: ls -la shows minimal content

---

Step 2.2: Run Interactive Setup (7 minutes)

# Start the interactive wizard (requires a TTY/interactive terminal)
sscli explore

# Non-TTY alternative (e.g. in scripts or CI):
sscli explore --list          # print available templates as a list
sscli explore --json          # print available templates as JSON

What you’ll be asked:

1. “Select a template”

   • ALPHA tier templates: static-landing, python-saas, react-client, rails-api, python-worker-service
   • PRO tier only: rails-fullstack (upgrade required)
   • Recommendation for Alpha: Start with static-landing (simplest, fastest)
   • Alternative: Choose python-saas for full-stack (takes 15 min longer)

2. “Project name”

   • Use lowercase with hyphens: my-company-landing

3. “Target directory”

   • Press Enter to use current directory
   • Or specify: ./my-project

4. Template-specific questions

   • For static-landing: Company name, tagline, color scheme
   • For python-saas: Database type, feature flags

Success Indicators:

• ✅ CLI downloads template (you see download progress)
• ✅ CLI generates files (you see file creation messages)
• ✅ Final message: ✓ Project generated successfully at <path>
• ✅ You see new files: ls -la shows template structure

Common Issues:

❌ “Permission denied” when creating files

• Solution: Ensure you have write permissions in the target directory
• Or: Run from your home directory: cd ~ && mkdir alpha-test && cd alpha-test

❌ “Template download failed”

• Solution: Check internet connection and try again
• Persistent?: GitHub may be down—check https://www.githubstatus.com

❌ CLI hangs at “Downloading template…”

• Wait time: Initial download can take 30-60 seconds for large templates
• If >2 minutes: Press Ctrl+C, delete directory, try again with --verbose flag

Validation step:

# Check generated files
ls -la

# You should see:
# - Dockerfile
# - README.md
# - docker-compose.yml (for full-stack templates)
# - src/ or app/ directory

⏱️ Estimated time so far: 18 minutes

---

Step 2.3: Review Generated Structure (2 minutes)

# View the README for your specific template
cat README.md | head -30

What to look for:

• Project name matches what you entered
• Instructions are present for running locally
• Dockerfile exists

Quick orientation:

• Dockerfile — How to build your app as a container
• README.md — Template-specific documentation
• src/ or app/ — Your application code
• .env.example — Environment variables template

Success Indicator:

• ✅ You understand where the code lives and how to run it (even if you don’t run it yet)

⏱️ Estimated time so far: 20 minutes

---

🏗️ Phase 3: Local Deployment (10 minutes)

Step 3.1: Build Docker Container (5 minutes)

# Build the Docker image (this takes 2-4 minutes)
docker build -t my-alpha-test .

Success Indicators:

• ✅ You see build steps progressing (Step 1/10, Step 2/10, etc.)
• ✅ No red “ERROR” messages
• ✅ Final line: Successfully tagged my-alpha-test:latest

Common Issues:

❌ “Cannot connect to Docker daemon”

• Solution: Make sure Docker Desktop is running
• Verify: Docker icon in menu bar shows “running” (green)

❌ “ERROR: failed to solve with frontend dockerfile.v0”

• Cause: Syntax error in Dockerfile (report to us!)
• Workaround: Try different template: sscli interactive → choose static-landing

❌ Build takes forever (>10 minutes)

• Cause: Slow internet or large dependencies
• Action: Let it finish once (downloads are cached after first build)

Time check: First build is slow (3-8 min). Rebuilds are fast (30 sec).

---

Step 3.2: Run the Application (3 minutes)

For static-landing:

# Run container
docker run -d -p 8080:80 --name alpha-test my-alpha-test

# Check it's running
docker ps

For python-saas or full-stack:

# Use docker compose for multi-service stacks
docker compose up --build

# Check all services are running
docker compose ps

Success Indicators:

• ✅ docker ps shows container(s) with status “Up”
• ✅ PORT shows mapping like 0.0.0.0:8080->80/tcp

Access your application:

Open browser and visit:

• Static landing: http://localhost:8080
• Python SaaS API: http://localhost:8000
• React Client: http://localhost:5173
• Rails API: http://localhost:3000

Success Indicators:

• ✅ Page loads without errors
• ✅ You see the generated template content
• ✅ (For APIs) http://localhost:8000/health returns {"status": "healthy"} (python-saas) or http://localhost:3000/health (rails-api)

Common Issues:

❌ “This site can’t be reached” in browser

• Check: Is the container running? docker ps should show it
• Check: Wait 10 seconds and refresh (services need startup time)
• Check: Try curl http://localhost:8080 in terminal

❌ “port is already allocated”

• Cause: Something else is using port 8080 (or 3000, 5000, etc.)
• Solution: Stop other service, or change port:

  docker run -d -p 8081:80 --name alpha-test my-alpha-test
  # Then visit http://localhost:8081

❌ Container starts then immediately stops

• Diagnose: Check logs:

  docker logs my-alpha-test

• Common fix: Missing environment variables—check .env.example and create .env

⏱️ Estimated time so far: 28 minutes

---

Step 3.3: Make a Test Change (2 minutes)

For static-landing:

1. Open src/pages/index.astro (or similar entry file)
2. Change the headline text
3. Rebuild: docker build -t my-alpha-test .
4. Restart: docker stop alpha-test && docker rm alpha-test && docker run -d -p 8080:80 --name alpha-test my-alpha-test
5. Refresh browser

For python-saas:

1. Open src/routes/health.py
2. Change the response message
3. Rebuild: docker compose up --build
4. Visit http://localhost:8000/health

Success Indicator:

• ✅ You see your changes reflected in the running application

⏱️ Estimated time so far: 30 minutes

---

🎉 Phase 4: Success Validation & Next Steps (5 minutes)

✅ Onboarding Complete Checklist

Mark everything you’ve accomplished:

Setup:

• CLI installed and version verified
• Successfully authenticated with Alpha license
• License tier shows ALPHA

Generation:

• Generated at least one template (static-landing or python-saas)
• Reviewed generated file structure
• Read template’s README

Deployment:

• Docker build completed successfully
• Container running (verified with docker ps)
• Application accessible in browser
• Made a small change and saw it deploy

🏆 If all checked: CONGRATULATIONS! You’re officially onboarded!

---

📊 Success Metrics (Help us measure)

We’re tracking alpha success by these metrics:

• ✅ Installation time: Target <5 min (yours: _ min)
• ✅ Time to first deploy: Target <30 min (yours: _ min)
• ✅ Friction points: How many times did you need to search for help? (_)
• ✅ Steps requiring support: Which step was most confusing? (**__**)

Please share your numbers! Email to: alpha-feedback@seedsource.dev

---

🚀 What to Do Next

Immediate actions (today):

1. Customize your deployment: Change colors, text, branding
2. Try a different template: Run sscli interactive again in a new folder
3. Explore feature injection: Check template README for available features

This week:

1. Deploy to production:

   • Static sites: Deploy to Vercel/Netlify (2-5 min) — see Deployment Runbook
   • Full-stack: Deploy to Render/Railway (10-15 min) — see Deployment Runbook

2. Enable additional features:

   # ALPHA users: Add Stripe payment support to python-saas
   # Option A — inject at generation time:
   sscli new --template python-saas --name my-app --with-payment
   
   # Option B — inject into an existing generated project:
   sscli inject --path ./my-app --features payment --template python-saas
   
   # PRO users additionally have access to:
   # --with-auth  --with-commerce  --with-admin  --with-tunnel

3. Integrate with your codebase: Copy generated code into your existing repos

Before end of alpha (next 30 days):

1. Build a real feature: Implement your core business logic
2. Report bugs: https://github.com/seed-source/feedback/issues
3. Share your experience: Optional feedback call—schedule at calendly.com/seedsource/alpha-feedback

---

🆘 Troubleshooting Reference

Quick Diagnostic Commands

# Check CLI version
sscli --version

# Validate authentication
sscli auth validate

# Check Docker
docker ps
docker logs <container-name>

# Check ports
lsof -i :8080  # macOS/Linux
netstat -aon | findstr :8080  # Windows

Common Error Patterns

Error Message	Most Likely Cause	Quick Fix
”command not found: sscli”	Not in PATH	python3 -m pip install --user sscli then restart terminal
”Authentication failed”	Invalid license key	Re-copy key from email (check for spaces)
“Cannot connect to Docker”	Docker not running	Start Docker Desktop
”port is already allocated”	Port conflict	Change port: -p 8081:80 instead of -p 8080:80
”This site can’t be reached”	Container not running	docker ps to verify, docker logs <name> to debug
”Template download failed”	Network/GitHub issue	Retry after 5 minutes, check githubstatus.com

Getting Help

Self-service (fastest):

1. Check TROUBLESHOOTING.md for detailed guides
2. Search docs: https://docs.seedsource.dev
3. Review your template’s README for specific issues

Community (fast):

1. Discord: discord.gg/seedsource (invite in your welcome email)
2. GitHub Discussions: https://github.com/seed-source/discussions

Direct Support (alpha clients only):

1. Email: support@seedsource.dev
   • Subject: “Alpha Onboarding: [specific issue]”
   • Include: CLI version, OS, error message, steps taken
2. Expected response time: 4-8 hours (weekdays)

Emergency (deployment blocking):

1. Slack: Use #alpha-urgent channel (invite in welcome email)
2. Response time: 1-2 hours (during business hours)

---

📝 Feedback Form

We need your honest input to improve!

What worked well? (What steps were clear and easy?)

---

What was confusing? (Which steps made you pause or search for help?)

---

What’s missing? (What would have made this smoother?)

---

Time spent:

• Prerequisites: _ min
• Installation: _ min
• Authentication: _ min
• Generation: _ min
• Deployment: _ min
• Total: _ min

Would you recommend Seed & Source to a colleague?

• Yes, definitely
• Yes, with reservations: **___**
• No, because: **___**

Submit feedback: Send to alpha-feedback@seedsource.dev or fill form at https://seedsource.dev/alpha-feedback

---

🔒 Alpha Program Details

Your Responsibilities:

• Test thoroughly and report bugs (not assume they’re documented)
• Provide feedback within 7 days of each milestone
• Understand that APIs may change (we’ll notify via email)
• Don’t share alpha builds or documentation publicly

What You Get:

• Full access to all alpha templates
• Priority support (4-8 hour response time)
• Direct line to engineering team
• Influence on roadmap direction
• Grandfather pricing when we launch (details TBD)

Alpha Timeline:

• Phase 1 (Weeks 1-2): Core functionality validation (you’re here!)
• Phase 2 (Weeks 3-4): Advanced features and deployment options
• Phase 3 (Weeks 5-6): Production hardening and performance testing
• Beta Launch: Target Q2 2026

Communication Cadence:

• Weekly email updates (every Monday)
• Monthly feedback calls (optional, but appreciated)
• Immediate notifications for breaking changes

---

📚 Additional Resources

Essential Docs:

• Getting Started — Comprehensive guide (more detail than this checklist)
• Troubleshooting — Detailed error solutions
• CLI Reference — All commands and flags
• Feature Injection Guide — How to add capabilities

Template-Specific:

• Static Landing Guide
• Python SaaS Architecture
• React Client Setup
• Rails API Quickstart

Deployment:

• Deployment Runbook — All hosting platforms
• Environment Variables — Configuration
• Docker Best Practices — Container optimization (coming soon)

Community:

• GitHub: https://github.com/seed-source
• Discord: discord.gg/seedsource
• Twitter: @seedsource_dev

---

🎯 Quick Reference Card (Print This!)

┌─────────────────────────────────────────────────────┐
│        SEED & SOURCE ALPHA - QUICK COMMANDS         │
├─────────────────────────────────────────────────────┤
│ Install CLI:                                        │
│   pip3 install sscli                                │
│                                                     │
│ Authenticate:                                       │
│   sscli auth login                                  │
│   (paste license key when prompted)                 │
│                                                     │
│ Generate Project:                                   │
│   mkdir my-project && cd my-project                 │
│   sscli interactive                                 │
│                                                     │
│ Build & Run:                                        │
│   docker build -t my-app .                          │
│   docker run -d -p 8080:80 my-app                   │
│   Open: http://localhost:8080                       │
│                                                     │
│ Check Status:                                       │
│   docker ps                                         │
│   docker logs <container-name>                      │
│                                                     │
│ Get Help:                                           │
│   support@seedsource.dev                            │
│   Discord: discord.gg/seedsource                    │
└─────────────────────────────────────────────────────┘

---

Version History:

• v1.0 (Feb 28, 2026): Initial alpha release
• Next review: After first 10 alpha clients complete onboarding

Maintained by: Seed & Source Platform Team Last validated: February 28, 2026 Next validation: March 15, 2026 (after first alpha cohort)

---

✅ You made it! Welcome to the Seed & Source alpha community. We’re excited to build the future of stack templates with you.

First question? Drop it in Discord (#alpha-general) or email support@seedsource.dev.

Ready for more? Check out GETTING_STARTED.md for advanced workflows.