ai-recruit-site-template/COOLIFY_SETUP.md

# Coolify Setup Guide

This guide explains how to set up Coolify for deploying AI recruitment sites from this template.

## Prerequisites

- Coolify instance (self-hosted or cloud)
- Coolify API token
- Gitea account and API token
- Cloudflare account for DNS (optional but recommended)

## One-Time Coolify Setup

These steps only need to be done once when setting up your Coolify instance for the first time.

### 1. Get Coolify API Token

1. Log in to your Coolify instance at `https://app.coolify.io` (or your self-hosted URL)
2. Go to **Settings** → **API Tokens**
3. Click **Create New Token**
4. Copy the token and save it securely
5. Export it as an environment variable:
   ```bash
   export COOLIFY_API_TOKEN="your-token-here"
   ```

### 2. Create Coolify Project (One Time)

If this is your first deployment, create a project for all recruitment sites:

```bash
COOLIFY_API="https://app.coolify.io/api/v1"

curl -X POST "${COOLIFY_API}/projects" \
  -H "Authorization: Bearer ${COOLIFY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "RecruitAI",
    "description": "AI Recruitment Sites from Template"
  }'
```

Save the returned `uuid` - you'll need it for deployments.

### 3. Get Server and Destination UUIDs

Find your server UUID:

```bash
curl -s "${COOLIFY_API}/servers" \
  -H "Authorization: Bearer ${COOLIFY_API_TOKEN}" | jq '.'
```

Find your destination UUID (usually "coolify" network):

```bash
curl -s "${COOLIFY_API}/servers/{SERVER_UUID}/destinations" \
  -H "Authorization: Bearer ${COOLIFY_API_TOKEN}" | jq '.'
```

### 4. Update Deployment Script

Edit `deploy-to-coolify.example.sh` with your UUIDs:

```bash
COOLIFY_PROJECT_UUID="your-project-uuid"
COOLIFY_SERVER_UUID="your-server-uuid"
COOLIFY_DESTINATION_UUID="your-destination-uuid"
```

## Per-Deployment Setup

These steps are done for each new recruitment site you deploy from the template.

### 1. Use the Template

On Gitea:
1. Go to https://git.startanaicompany.com/StartanAICompany/ai-recruit-site-template
2. Click **Use this template**
3. Name your repository (e.g., `acme-recruit-site`)
4. Create the repository

### 2. Clone and Configure

```bash
git clone https://git.startanaicompany.com/yourusername/acme-recruit-site.git
cd acme-recruit-site

# Copy and edit environment file
cp .env.example .env
nano .env
```

Configure at minimum:
```bash
COMPANY_NAME="ACME Recruitment"
SUBDOMAIN=acme
GITEA_USERNAME=yourusername
GITEA_REPO_NAME=acme-recruit-site
CONTACT_EMAIL=info@acmerecruitment.com
```

### 3. Get Gitea API Token

1. Log in to Gitea at https://git.startanaicompany.com
2. Go to **Settings** → **Applications** → **Generate New Token**
3. Name it (e.g., "Coolify Deployment")
4. Copy the token
5. Export it:
   ```bash
   export GITEA_API_TOKEN="your-gitea-token"
   ```

### 4. Run Deployment Script

```bash
# Copy the example script
cp deploy-to-coolify.example.sh deploy-to-coolify.sh

# Make it executable
chmod +x deploy-to-coolify.sh

# Run it
./deploy-to-coolify.sh
```

The script will:
- Create a Coolify application
- Configure the domain (subdomainrecruit.startanaicompany.com)
- Set up Traefik labels for HTTPS
- Configure webhook for automatic deployments
- Trigger initial deployment

### 5. Configure DNS

Add a CNAME record in Cloudflare (or your DNS provider):

- **Type**: CNAME
- **Name**: `acmerecruit` (or your subdomain + "recruit")
- **Target**: `app.coolify.io` (or your Coolify instance domain)
- **Proxy**: Enabled (for Cloudflare)

Wait 2-3 minutes for DNS propagation and deployment to complete.

### 6. Access Your Site

Your site will be available at:
- **Public Site**: `https://acmerecruit.startanaicompany.com`
- **Admin Panel**: `https://acmerecruit.startanaicompany.com/admin/login`

On first visit to admin, create your admin account.

## Automatic Deployments

After setup, any push to your repository's `master` branch will automatically:
1. Trigger a webhook to Coolify
2. Pull the latest code
3. Rebuild the Docker containers
4. Deploy the updated site

No manual intervention needed!

## Troubleshooting

### Deployment Failed

Check Coolify logs:
1. Go to https://app.coolify.io
2. Navigate to your application
3. Click **Logs** tab
4. Look for errors

Common issues:
- **Database connection failed**: Check DB_PASSWORD in environment variables
- **Build failed**: Check Dockerfile syntax
- **Port conflict**: Ensure port 3000 is exposed

### Webhook Not Working

Verify webhook is configured:

```bash
curl -s "https://git.startanaicompany.com/api/v1/repos/yourusername/yourrepo/hooks" \
  -H "Authorization: token ${GITEA_API_TOKEN}" | jq '.'
```

Should show a webhook with URL: `https://app.coolify.io/api/v1/deploy?uuid=...`

### DNS Not Resolving

Check DNS configuration:
```bash
dig acmerecruit.startanaicompany.com
```

Should point to your Coolify server or Cloudflare.

### Site Not Loading

1. Check deployment status in Coolify
2. Verify containers are running:
   ```bash
   # From Coolify server
   docker ps | grep acme
   ```
3. Check application logs in Coolify dashboard

## Environment Variables in Coolify

You can also set environment variables directly in Coolify UI:

1. Go to your application in Coolify
2. Click **Environment Variables** tab
3. Add variables (they override .env file)

Useful for:
- Secrets (DB_PASSWORD, SESSION_SECRET)
- Production-specific values
- API keys

## Security Best Practices

1. **Never commit .env files** - They're in .gitignore
2. **Use strong passwords** - Generate with `openssl rand -hex 32`
3. **Rotate tokens** - Regenerate API tokens periodically
4. **Limit access** - Only grant necessary permissions
5. **Enable HTTPS** - Always use https:// for production
6. **Monitor logs** - Check for suspicious activity

## Resource Requirements

Per deployment:
- **CPU**: 1 core minimum
- **RAM**: 512MB minimum (1GB recommended)
- **Storage**: 1GB for app + database

For multiple sites on one Coolify instance, scale accordingly.

## Scaling Multiple Sites

To deploy multiple recruitment sites:

1. Each site gets its own:
   - Repository (from template)
   - Coolify application
   - Subdomain
   - Database

2. All sites share:
   - Coolify project
   - Server resources
   - DNS domain

3. Resource isolation:
   - Each site runs in separate Docker containers
   - Separate PostgreSQL instances
   - Independent environment variables

## Advanced Configuration

### Custom Domain

To use a custom domain instead of subdomain:

1. In `.env`, set:
   ```bash
   CUSTOM_DOMAIN=recruiting.yourcompany.com
   ```

2. Update deployment script to use CUSTOM_DOMAIN

3. Add DNS record pointing to Coolify

### SSL Certificates

Coolify uses Let's Encrypt automatically for HTTPS.

For custom certificates:
1. Go to Coolify → Your Application → Settings
2. Upload custom SSL certificate
3. Configure certificate details

### Database Backups

Enable automatic backups in Coolify:
1. Go to your PostgreSQL service
2. Click **Backups** tab
3. Configure backup schedule
4. Set retention policy

## Support

For issues:
- **Template Issues**: https://git.startanaicompany.com/StartanAICompany/ai-recruit-site-template/issues
- **Coolify Issues**: https://coolify.io/docs or GitHub issues
- **General Help**: Check README.md in the template repository