AI Recruitment Site Template

A fully customizable recruitment website template designed for easy deployment and AI agent modification. Built with Node.js, Express, and PostgreSQL with comprehensive environment-based configuration.

🎯 Use This Template

This repository is marked as a template. You can create your own recruitment site in minutes!

Quick Start (3 Steps)

1. Use this template - Click "Use this template" on Gitea
2. Customize - Edit .env file with your company information
3. Deploy - Run the automated deployment script

✨ Features

Public Features

• Job listings with search and filters
• Online application system with CV upload
• Contact form
• Fully responsive design
• Dynamic branding and content

Admin Features

• Dashboard with statistics
• Application management
• CV downloads and viewing
• Job posting management
• First-time admin account creation

Template Features

• Environment-based configuration - All customization via .env file
• Dynamic branding - Company name, colors, contact info all configurable
• AI agent friendly - Clear structure for automated modifications
• One-click deployment - Automated deployment to StartAnAiCompany infrastructure
• No hardcoded values - Everything is configurable

🚀 Quick Deployment

Prerequisites

• Gitea account at git.startanaicompany.com
• SAAC API key (get from apps.startanaicompany.com)
• Basic command line knowledge

📖 Detailed Guide: See DEPLOYMENT_GUIDE.md for complete instructions.

Step 1: Create Your Copy

Use Gitea's template feature to create your own copy:

# Or clone the template manually
git clone https://git.startanaicompany.com/StartanAICompany/ai-recruit-site-template.git my-recruit-site
cd my-recruit-site

Step 2: Customize Configuration

# Copy the example environment file
cp .env.example .env

# Edit .env with your company information
nano .env

Minimum required configuration in .env:

# Company Information
COMPANY_NAME="Your Recruitment Firm"
COMPANY_TAGLINE="Your Tagline Here"
COMPANY_DESCRIPTION="Your company description"

# Branding Colors
PRIMARY_COLOR=#2563EB
ACCENT_COLOR=#059669
DARK_COLOR=#1E293B

# Contact Information
CONTACT_EMAIL=info@yourcompany.com
CONTACT_PHONE=+1 (555) 123-4567
CONTACT_ADDRESS=123 Business St, City, State 12345

# Deployment Configuration
SUBDOMAIN=yourname
GITEA_USERNAME=your-gitea-username
GITEA_REPO_NAME=my-recruit-site

Step 3: Register for API Key

Register once to get your deployment API key:

curl -X POST https://apps.startanaicompany.com/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email":"your@email.com","gitea_username":"'${GITEA_USERNAME}'"}'

Save the returned API key:

export SAAC_API_KEY="cw_your_api_key_here"

Step 4: Deploy

# Copy and run the deployment script
cp deploy-to-apps.example.sh deploy-to-apps.sh
chmod +x deploy-to-apps.sh
./deploy-to-apps.sh

The script will:

• Create application on StartAnAiCompany infrastructure
• Configure domain (yournamerecruit.startanaicompany.com)
• Set up webhooks for automatic deployments
• Trigger initial deployment

Your site will be live in 2-3 minutes!

See DEPLOYMENT_GUIDE.md for detailed instructions and troubleshooting.

🎨 Customization Guide

Company Information

All company information is configured via environment variables in .env:

# Company Identity
COMPANY_NAME="Your Recruitment Firm"
COMPANY_TAGLINE="Finding the Perfect Match for Your Career"
COMPANY_DESCRIPTION="We specialize in connecting talented professionals..."

# Contact Details
CONTACT_EMAIL=info@yourcompany.com
CONTACT_PHONE=+1 (555) 123-4567
CONTACT_ADDRESS=123 Business St, Suite 100, City, State 12345
BUSINESS_HOURS=Monday - Friday: 9:00 AM - 6:00 PM

# Social Media (leave empty to hide)
SOCIAL_LINKEDIN=https://linkedin.com/company/yourcompany
SOCIAL_TWITTER=https://twitter.com/yourcompany
SOCIAL_FACEBOOK=

Branding Colors

Customize your brand colors:

PRIMARY_COLOR=#2563EB  # Main brand color (buttons, links)
ACCENT_COLOR=#059669   # Success/accent color
DARK_COLOR=#1E293B     # Dark elements (footer, headings)

Colors update automatically across the entire site!

About Page Content

ABOUT_MISSION=Our mission statement here
ABOUT_VISION=Our vision statement here
ABOUT_VALUES=Integrity, Excellence, Innovation, Partnership

Services Offered

SERVICES_LIST=Executive Search,Contract Staffing,Permanent Placement,Career Consulting

Feature Configuration

MAX_CV_SIZE_MB=5
ALLOWED_CV_TYPES=application/pdf,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document

🤖 AI Agent Modification

This template is designed to be easily modified by AI agents like Claude Code. The structure includes:

Clear File Organization

ai-recruit-site-template/
├── config.js              # Centralized configuration
├── server.js              # Main application
├── public/
│   ├── js/
│   │   └── init.js       # Dynamic config injection
│   ├── css/
│   │   └── styles.css    # CSS with variables
│   └── *.html            # HTML with data attributes
├── migrations/            # Database migrations
└── .env.example          # Configuration template

Data Attributes

HTML elements use data attributes for dynamic content:

<div data-company-name>Your Company</div>
<h1 data-company-tagline>Your Tagline</h1>
<a data-contact-email>email@example.com</a>

Configuration API

Frontend can access configuration via API:

// GET /api/config returns:
{
  company: { name, tagline, description },
  branding: { primaryColor, accentColor, darkColor },
  contact: { email, phone, address, businessHours },
  social: { linkedin, twitter, facebook },
  about: { mission, vision, values },
  services: { list: [...] }
}

💻 Local Development

With Docker (Recommended)

cp .env.example .env
# Edit .env with your settings

docker-compose up -d

Access at: http://localhost:3000

Without Docker

# Install dependencies
npm install

# Start PostgreSQL (must be running)
# Create database 'recruitment'

# Copy environment file
cp .env.example .env

# Start application
npm start

📊 Technology Stack

• Backend: Node.js 18 + Express
• Database: PostgreSQL 15 with BYTEA for CV storage
• Authentication: Session-based with bcrypt
• File Upload: Multer (PDF, DOC, DOCX)
• Deployment: Docker Compose + StartAnAiCompany platform
• DNS: Cloudflare

🔐 Security Features

• Password hashing with bcrypt (10 rounds)
• Secure HTTP-only session cookies
• SQL injection protection (parameterized queries)
• File upload validation (type and size)
• Environment-based secrets
• Automatic HTTPS in production

📚 API Documentation

Public APIs

• GET /api/config - Get site configuration
• GET /api/jobs - List active jobs
• GET /api/jobs/:id - Get job details
• POST /api/apply - Submit application (multipart/form-data)
• POST /api/contact - Submit contact form

Admin APIs (Authentication Required)

• POST /api/admin/login - Login / Create first admin
• GET /api/admin/check - Check auth status
• POST /api/admin/logout - Logout
• GET /api/admin/stats - Dashboard statistics
• GET /api/admin/applications - List applications (with filters)
• GET /api/admin/applications/:id - Get application details
• GET /api/admin/applications/:id/cv - Download CV
• PATCH /api/admin/applications/:id - Update application status
• GET /api/admin/jobs - List all jobs
• POST /api/admin/jobs - Create job
• PATCH /api/admin/jobs/:id - Update job (activate/deactivate)

🆘 Troubleshooting

Deployment Issues

# Check deployment logs via SAAC API
curl -H "X-API-Key: $SAAC_API_KEY" \
  "https://apps.startanaicompany.com/api/v1/applications/YOUR_APP_UUID/logs?tail=100"

# Re-trigger deployment
curl -X POST -H "X-API-Key: $SAAC_API_KEY" \
  https://apps.startanaicompany.com/api/v1/applications/YOUR_APP_UUID/deploy

Database Issues

# Check database connection
docker-compose logs postgres

# Access database
docker-compose exec postgres psql -U postgres -d recruitment

# List tables
\dt

Configuration Not Updating

Make sure you:

1. Updated .env file
2. Committed and pushed changes (triggers webhook)
3. Waited 2-3 minutes for redeployment

🎓 First Time Setup

1. Visit your deployment URL
2. Go to /admin/login
3. System detects no admin exists
4. Fill in email, password, and full name
5. Click "Create Admin Account"
6. You're logged in!

📝 Environment Variables Reference

Variable	Description	Default	Required
COMPANY_NAME	Your company name	Your Recruitment Firm	Yes
COMPANY_TAGLINE	Main tagline	Finding the Perfect Match...	Yes
COMPANY_DESCRIPTION	Company description	We specialize in...	Yes
PRIMARY_COLOR	Primary brand color	#2563EB	No
ACCENT_COLOR	Accent color	#059669	No
DARK_COLOR	Dark color	#1E293B	No
CONTACT_EMAIL	Contact email	info@yourcompany.com	Yes
CONTACT_PHONE	Contact phone	+1 (555) 123-4567	Yes
CONTACT_ADDRESS	Physical address	123 Business St...	Yes
BUSINESS_HOURS	Business hours	Monday - Friday...	No
SOCIAL_LINKEDIN	LinkedIn URL	(empty)	No
SOCIAL_TWITTER	Twitter URL	(empty)	No
SOCIAL_FACEBOOK	Facebook URL	(empty)	No
SUBDOMAIN	Your subdomain	yourname	Yes (deploy)
GITEA_USERNAME	Your Gitea username	-	Yes (deploy)
GITEA_REPO_NAME	Your repo name	-	Yes (deploy)
DB_PASSWORD	Database password	(auto-generated)	No
SESSION_SECRET	Session secret	(auto-generated)	No
MAX_CV_SIZE_MB	Max CV file size	5	No
ALLOWED_CV_TYPES	Allowed CV MIME types	pdf,doc,docx	No

🤝 Contributing

This is a template repository. Feel free to:

• Fork it for your own recruitment site
• Customize it to your needs
• Submit improvements via pull request

📄 License

MIT License - feel free to use for commercial projects

🆘 Support

For issues or questions:

• Check the How to set up a template repo guide
• Contact: info@startanaicompany.com