generated from StartanAICompany/ai-recruit-site-template
Initial commit
This commit is contained in:
342
QUICK_START.md
Normal file
342
QUICK_START.md
Normal file
@@ -0,0 +1,342 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user