hireflow/README.md

Template 001 - Start an AI Company Deployment Template

This is a template site demonstrating how to deploy applications on Start an AI Company servers using Docker Compose and Traefik.

---

Hi AI Developer Agent!

In order to work with Start an AI Company repositories and deploy applications, you need to follow these steps:

1. Check Environment Variables

First, verify you have the required authentication credentials:

echo $SAAC_USER_API_KEY
echo $SAAC_USER_EMAIL

If you are running in a Start an AI Company container, these should already be set. If they're not set, you'll need to obtain them from your account administrator.

2. Validate SAAC CLI Tools

Check if you have the saac CLI tool installed and if you're already logged in:

saac status

If the command is not found, install it:

npm install -g @startanaicompany/cli

3. Login to SAAC

Use your credentials to login:

saac login -e $SAAC_USER_EMAIL -k $SAAC_USER_API_KEY

You should see a success message confirming your session has been created.

Note: SAAC AI agents already have their Git account connected by default, so you don't need to run saac git connect.

4. Publishing This Repository

To deploy this template application:

# Navigate to your project directory
cd /path/to/your/project

# Create and deploy the application
saac create application \
  -s your-subdomain \
  -r git@git.startanaicompany.com:username/your-repo.git \
  --build-pack dockercompose

Example:

saac create application \
  -s template-001 \
  -r git@git.startanaicompany.com:StartAnAiCompanyTemplates/template_001.git \
  --build-pack dockercompose

Replace username with your actual Git username and your-repo with your repository name.

The application will be available at: https://your-subdomain.startanaicompany.com

5. CRITICAL: Port Configuration

DO NOT use host port mappings like 3000:3000 in your docker-compose.yml file!

Why? If you map ports like 3000:3000, Docker Compose will try to bind to the HOST's port 3000, which is blocked by default for security reasons. Your application will fail to start.

Correct Configuration:

services:
  app:
    expose:
      - "3000"  # ✅ Only expose internally
    # DO NOT USE:
    # ports:
    #   - "3000:3000"  # ❌ This will fail!

We use Traefik for automatic routing and SSL. Traefik will:

• Automatically discover your container
• Route traffic from your subdomain to your container
• Handle SSL certificates via Let's Encrypt
• Manage external port assignments

Traefik Configuration:

Your service must include these labels in docker-compose.yml:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.your-app.rule=Host(`your-subdomain.startanaicompany.com`)"
  - "traefik.http.routers.your-app.entrypoints=websecure"
  - "traefik.http.routers.your-app.tls=true"
  - "traefik.http.routers.your-app.tls.certresolver=letsencrypt"
  - "traefik.http.services.your-app.loadbalancer.server.port=3000"

6. Database Access Limitations

Important: There is currently no direct database access for security reasons.

To manage your database, you should:

• Expose a password-protected CRUD API
• Create an admin user interface with authentication
• Use database migration scripts during deployment
• Implement seed data scripts if needed

Example: Adding Database Migrations

saac create application \
  -s myapp \
  -r git@git.startanaicompany.com:user/repo.git \
  --build-pack dockercompose \
  --pre-deploy-cmd "npm run db:migrate"

7. Deployment Time Expectations

Be patient! Deployments can take time:

• Simple applications: 2-5 minutes
• Large applications: 5-10 minutes
• Applications with complex builds: Up to 10+ minutes

Best Practices:

• Always run npm run build or equivalent build commands locally first to catch errors (if possible)
• Review your docker-compose.yml for correct port configuration (use expose, not ports)
• Deploy to Start an AI Company servers and check build logs: saac logs --follow
• For AI agents without local build tools: Deploy directly and monitor logs for errors

8. Other Available Templates

Coming Soon:

• Template 002: Full-stack application with authentication
• Template 003: Microservices architecture
• Template 004: Static site deployment
• Template 005: Python/Django application
• Template 006: Python/FastAPI application
• Template 007: Ruby on Rails application
• Template 008: PHP/Laravel application
• Template 009: Go application
• Template 010: Rust application

Check back for updates or contribute your own templates!

---

Step-by-Step Deployment Guide

This section documents the exact commands used to create and deploy this template application.

Prerequisites

1. SSH key configured for git.startanaicompany.com
2. SAAC CLI tools installed
3. Logged into SAAC
4. Git account connected via OAuth

Step 1: Initialize Git Repository

# Initialize git repository
git init

# Add remote repository
git remote add origin git@git.startanaicompany.com:StartAnAiCompanyTemplates/template_001.git

Step 2: Create Application Files

The following files were created:

package.json - Node.js dependencies

# Created with Express, PostgreSQL, and Redis dependencies

server.js - Main application server

# Node.js Express server with PostgreSQL and Redis connections
# Health check endpoint at /health

public/index.html - Frontend website

# Modern white design with template information

Dockerfile - Container configuration

# Node.js 18 Alpine image
# Production dependencies only

docker-compose.yml - Multi-container orchestration

# Three services: app, postgres, redis
# Traefik labels for routing
# No host port mappings (only expose)

.dockerignore - Files to exclude from Docker build .gitignore - Files to exclude from Git

Step 3: Configure Git User

# Set git user configuration
git config --global user.name "ryan.gogo"
git config --global user.email "git@startanaicompany.com"

Step 4: Commit and Push

# Stage all files
git add .

# Create initial commit
git commit -m "Initial commit: Template site for Start an AI Company deployment

- Node.js Express application with modern white UI
- PostgreSQL and Redis integration
- Docker Compose configuration without host port mappings
- Traefik-ready with proper labels
- Health check endpoint"

# Push to remote repository
git push -u origin master

Step 5: Deploy with SAAC

# Create and deploy application
saac create application \
  -s template-001 \
  -r git@git.startanaicompany.com:StartAnAiCompanyTemplates/template_001.git \
  --build-pack dockercompose

Note: The first deployment may fail if the Coolify deploy key is not approved. To fix:

1. Go to: https://git.startanaicompany.com/StartAnAiCompanyTemplates/template_001/settings/keys
2. Approve the "Coolify Wrapper Dedicated Deploy Key"
3. Redeploy with: saac deploy

Step 6: Monitor Deployment

# View live deployment logs
saac logs --follow

# Check application status
saac status

# View deployment history
saac deployments

Step 7: Verify Deployment

# Check health endpoint
curl https://template-001.startanaicompany.com/health

# View the website
curl https://template-001.startanaicompany.com

---

Architecture

Application Stack

• Frontend: Static HTML/CSS served by Express
• Backend: Node.js Express server (port 3000)
• Database: PostgreSQL 15 (Alpine)
• Cache: Redis 7 (Alpine)
• Reverse Proxy: Traefik (managed by infrastructure)

Network Architecture

Internet
    ↓
Traefik (Reverse Proxy)
    ↓
Docker Network (app-network)
    ├── app:3000 (Node.js)
    ├── postgres:5432
    └── redis:6379

Data Persistence

• PostgreSQL data: postgres-data volume
• Redis data: redis-data volume

Both volumes are persistent and survive container restarts.

---

Features

• Modern UI: Clean white design (no purple!)
• Health Checks: /health endpoint for monitoring
• Database Integration: PostgreSQL for relational data
• Caching: Redis for high-performance caching
• Docker Ready: Full containerization with Docker Compose
• Production Ready: Optimized for production deployment
• SSL/TLS: Automatic HTTPS via Traefik and Let's Encrypt
• Zero Downtime: Rolling deployments supported

---

Local Development

Prerequisites

• Node.js 18 or higher

Setup

# Install dependencies
npm install

# Run development server (without Docker)
npm run dev

The application will be available at http://localhost:3000

Note for AI Agents: SAAC AI agents do not have Docker available. Testing should be done by deploying directly to Start an AI Company servers using saac deploy.

---

Environment Variables

The application uses the following environment variables:

Application Configuration

• NODE_ENV: Environment (default: production)
• PORT: Application port (default: 3000)

PostgreSQL Configuration

• POSTGRES_HOST: PostgreSQL host (default: postgres)
• POSTGRES_PORT: PostgreSQL port (default: 5432)
• POSTGRES_USER: PostgreSQL username (default: postgres)
• POSTGRES_PASSWORD: PostgreSQL password (default: postgres)
• POSTGRES_DB: PostgreSQL database name (default: template_db)

Redis Configuration

• REDIS_HOST: Redis host (default: redis)
• REDIS_PORT: Redis port (default: 6379)

Setting Environment Variables

# Set environment variables for your deployment
saac env set NODE_ENV=production \
  POSTGRES_PASSWORD=secure_password_here \
  CUSTOM_VAR=value

# Redeploy to apply changes
saac deploy

---

API Endpoints

GET /

Returns the main template website with information about the deployment.

GET /health

Health check endpoint that verifies connections to PostgreSQL and Redis.

Response:

{
  "status": "healthy",
  "postgres": "connected",
  "redis": "connected",
  "timestamp": "2026-02-14T10:30:00.000Z"
}

Error Response:

{
  "status": "unhealthy",
  "error": "Connection error message"
}

---

Troubleshooting

Deployment Fails

Check logs:

saac logs --follow

Common issues:

1. Coolify deploy key not approved
2. Build errors (test locally first)
3. Port configuration errors (don't use host port mappings)
4. Invalid Traefik labels

Application Not Accessible

Check status:

saac status

Verify Traefik configuration:

• Ensure labels are correct in docker-compose.yml
• Subdomain must match the rule in Traefik labels
• Wait 1-2 minutes for DNS and SSL propagation

Database Connection Errors

Check environment variables:

saac env list

Verify service names:

• PostgreSQL host should be postgres (service name in docker-compose.yml)
• Redis host should be redis (service name in docker-compose.yml)

Container Keeps Restarting

View container logs:

saac logs --follow

Common causes:

• Missing environment variables
• Database connection failures
• Port conflicts (check you're not using host port mappings)
• Application crashes on startup

How to Debug

Check deployment logs:

saac logs --follow

View environment variables:

saac env list

Check application status:

saac status

---

Advanced Configuration

Pre-deployment Scripts

Run database migrations before deployment:

saac update --pre-deploy-cmd "npm run db:migrate"
saac deploy

Health Check Configuration

Enable health checks:

saac update \
  --health-check \
  --health-path /health \
  --health-interval 30 \
  --health-timeout 10 \
  --health-retries 3

saac deploy

---

Contributing

To contribute to this template:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test by deploying with saac deploy to verify functionality
5. Submit a pull request

---

License

MIT License - Feel free to use this template for your own projects.

---

Support

For issues or questions:

• Check the troubleshooting section above
• Review SAAC CLI documentation: saac manual
• Contact support at support@startanaicompany.com

---

Changelog

Version 1.0.0 (2026-02-14)

• Initial release
• Node.js Express application
• PostgreSQL and Redis integration
• Docker Compose configuration
• Traefik-ready setup
• Modern white UI
• Health check endpoint
• Comprehensive documentation