Add comprehensive Coolify setup documentation
Created COOLIFY_SETUP.md with complete instructions for: - One-time Coolify instance setup (API tokens, projects, UUIDs) - Per-deployment setup for each recruitment site - DNS configuration with Cloudflare - Webhook configuration for automatic deployments - Troubleshooting common issues - Security best practices - Scaling multiple sites - Advanced configuration options Updated README.md to reference the new setup guide. This provides all the information users need to set up their own Coolify instance and deploy multiple recruitment sites from the template. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Mikael Westöö
296
COOLIFY_SETUP.md
Normal file
296
COOLIFY_SETUP.md
Normal file
@@ -0,0 +1,296 @@
|
||||
# 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 (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:
|
||||
|
||||
```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 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:
|
||||
```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
|
||||
@@ -41,9 +41,11 @@ This repository is marked as a template. You can create your own recruitment sit
|
||||
|
||||
- Gitea account at git.startanaicompany.com
|
||||
- Gitea API token
|
||||
- Coolify API token (for deployment)
|
||||
- Coolify instance with API token
|
||||
- Basic command line knowledge
|
||||
|
||||
**New to Coolify?** See [COOLIFY_SETUP.md](COOLIFY_SETUP.md) for detailed setup instructions.
|
||||
|
||||
### Step 1: Create Your Copy
|
||||
|
||||
Use Gitea's template feature to create your own copy:
|
||||
|
||||
Reference in New Issue
Block a user