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:

   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:

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:

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

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

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:

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

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:

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:

   export GITEA_API_TOKEN="your-gitea-token"
   

4. Run Deployment Script

# 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 (subdomain.recruitai.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: acme.recruitai (or your subdomain)
• 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://acme.recruitai.startanaicompany.com
• Admin Panel: https://acme.recruitai.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:

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:

dig acme.recruitai.startanaicompany.com

Should point to your Coolify server or Cloudflare.

Site Not Loading

1. Check deployment status in Coolify
2. Verify containers are running:

   # 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:

   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