ai-recruit-site-template/QUICK_START.md

Quick Start Guide - AI Recruitment Site Deployment

Prerequisites

1. Install jq (JSON processor)

   # Ubuntu/Debian
   sudo apt install jq
   
   # macOS
   brew install jq
   
   # Alpine Linux
   apk add jq
   

2. Get Gitea API Token (only needed for first deployment)

   • Go to https://git.startanaicompany.com
   • Profile → Settings → Applications
   • Generate New Token (grant 'repo' permissions)
   • Save the token

3. Configure your .env file

   cp .env.example .env
   nano .env  # Edit with your company information
   

---

First-Time Deployment

Step 1: Copy the Script

cp deploy-to-apps.example.sh deploy-to-apps.sh

Step 2: Set Gitea Token

export GITEA_API_TOKEN='your_gitea_token_here'

Step 3: Run the Script

./deploy-to-apps.sh

Step 4: Follow the Prompts

The script will:

1. Prompt for your email

   Enter your email address: you@example.com
   

2. Register your account

   • Creates user account
   • Generates API key
   • Saves to .saac.json

3. Request verification code

   Check your email at MailHog:
   https://mailhog.goryan.io
   
   Enter the verification code from the email:
   

4. Create deployment

   • Sets up application
   • Configures webhook
   • Deploys your site

Step 5: Wait for Deployment

Your site will be live in 2-3 minutes at:

https://<subdomain>recruit.startanaicompany.com

---

Updating Your Site

Step 1: Edit .env

nano .env
# Change COMPANY_NAME, colors, contact info, etc.

Step 2: Deploy Updates

./deploy-to-apps.sh
# or
./deploy-to-apps.sh --update

The script will:

• Load configuration from .saac.json
• Update environment variables
• Trigger redeployment

Your changes will be live in 2-3 minutes.

---

Checking Deployment Status

./deploy-to-apps.sh --status

Output:

Application UUID: 123e4567-e89b-12d3-a456-426614174000
Name: mycompany-recruit
Domain: https://mycompany.recruit.startanaicompany.com
Status: running
Repository: git@git.startanaicompany.com:myuser/myrepo.git
Branch: master
Created: 2026-01-24T12:00:00Z

---

Understanding .saac.json

This file stores your credentials and deployment configuration:

{
  "user": {
    "email": "you@example.com",
    "user_id": "...",
    "api_key": "...",
    "verified": true
  },
  "deployment": {
    "application_uuid": "...",
    "domain": "..."
  }
}

Important:

• ⚠️ Never commit this file to git (it's in .gitignore)
• ✅ Keep it secure (permissions set to 600)
• 📋 Backup this file to restore access

---

Common Scenarios

Scenario 1: Interrupted Registration

If you exit during registration/verification:

./deploy-to-apps.sh

The script will:

• Detect existing .saac.json
• Check verification status
• Resume where you left off

Scenario 2: New Deployment on Existing Account

If you want to deploy a different site:

./deploy-to-apps.sh --setup

This will:

• Use existing credentials
• Create new application
• Update .saac.json with new deployment

Scenario 3: Lost .saac.json

If you lose your .saac.json file:

Option 1: Re-register with same email

• Run ./deploy-to-apps.sh
• Enter same email
• New API key will be generated
• Old deployments will still work with old API key

Option 2: Restore from backup

• Copy backed-up .saac.json
• Run ./deploy-to-apps.sh --status to verify

---

Troubleshooting

Error: "jq: command not found"

Solution: Install jq

sudo apt install jq  # Ubuntu/Debian
brew install jq      # macOS

Error: "Email verification failed"

Causes:

• Wrong verification code
• Code expired (valid for 24 hours)

Solution:

1. Check MailHog: https://mailhog.goryan.io
2. Copy code exactly as shown
3. Try again (re-run script if needed)

Error: "Application not found"

Causes:

• Application was deleted
• Wrong API key
• Corrupt .saac.json

Solution:

# Create new deployment
./deploy-to-apps.sh --setup

Error: "GITEA_API_TOKEN not set"

Cause: Token not exported (only needed for setup mode)

Solution:

export GITEA_API_TOKEN='your_token_here'
./deploy-to-apps.sh --setup

---

Script Modes

Auto-detect (Default)

./deploy-to-apps.sh

Automatically determines:

• No .saac.json → Registration + Setup
• .saac.json exists, unverified → Verification
• .saac.json exists, verified, no deployment → Setup
• .saac.json exists, verified, has deployment → Update

Force Setup

./deploy-to-apps.sh --setup

Creates new deployment (warns if one already exists)

Force Update

./deploy-to-apps.sh --update

Updates existing deployment (fails if none exists)

Check Status

./deploy-to-apps.sh --status

Shows deployment information

---

Security Best Practices

1. Never commit .saac.json

   • Contains API key (like a password)
   • Already in .gitignore

2. Backup your .saac.json

   • Store in secure location
   • Don't upload to public services

3. Rotate API keys if compromised

   • Delete .saac.json
   • Re-register with new email
   • Create new deployment

4. Use environment variables for Gitea token

   # Add to ~/.bashrc or ~/.zshrc
   export GITEA_API_TOKEN='your_token_here'
   

---

Next Steps

After deployment:

1. Configure DNS (if using custom domain)

   • Add CNAME record
   • Point to: apps.startanaicompany.com

2. Customize your site

   • Edit .env file
   • Run ./deploy-to-apps.sh to update

3. Monitor deployment

   • Use --status mode
   • Check application logs

4. Set up monitoring

   • Check site regularly
   • Monitor uptime
   • Test features

---

Support

• MailHog: https://mailhog.goryan.io
• Gitea: https://git.startanaicompany.com
• SAAC API: https://apps.startanaicompany.com/api/v1

---

Last Updated: 2026-01-24