ryananderssonrecruit/QUICK_START.md

# Quick Start Guide - AI Recruitment Site Deployment

## Prerequisites

1. **Install jq** (JSON processor)
   ```bash
   # 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**
   ```bash
   cp .env.example .env
   nano .env  # Edit with your company information
   ```

---

## First-Time Deployment

### Step 1: Copy the Script

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

### Step 2: Set Gitea Token

```bash
export GITEA_API_TOKEN='your_gitea_token_here'
```

### Step 3: Run the Script

```bash
./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

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

### Step 2: Deploy Updates

```bash
./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

```bash
./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:

```json
{
  "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:

```bash
./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:

```bash
./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
```bash
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:**
```bash
# Create new deployment
./deploy-to-apps.sh --setup
```

### Error: "GITEA_API_TOKEN not set"

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

**Solution:**
```bash
export GITEA_API_TOKEN='your_token_here'
./deploy-to-apps.sh --setup
```

---

## Script Modes

### Auto-detect (Default)

```bash
./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

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

Creates new deployment (warns if one already exists)

### Force Update

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

Updates existing deployment (fails if none exists)

### Check Status

```bash
./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**
   ```bash
   # 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