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:

```bash
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:

```bash
saac status
```

If the command is not found, install it:

```bash
npm install -g @startanaicompany/cli
```

### 3. Login to SAAC

Use your credentials to login:

```bash
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:

```bash
# 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:**
```bash
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:**

```yaml
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`:

```yaml
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**

```bash
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

```bash
# 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
```bash
# Created with Express, PostgreSQL, and Redis dependencies
```

**server.js** - Main application server
```bash
# Node.js Express server with PostgreSQL and Redis connections
# Health check endpoint at /health
```

**public/index.html** - Frontend website
```bash
# Modern white design with template information
```

**Dockerfile** - Container configuration
```bash
# Node.js 18 Alpine image
# Production dependencies only
```

**docker-compose.yml** - Multi-container orchestration
```bash
# 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

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

### Step 4: Commit and Push

```bash
# 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

```bash
# 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

```bash
# View live deployment logs
saac logs --follow

# Check application status
saac status

# View deployment history
saac deployments
```

### Step 7: Verify Deployment

```bash
# Check health endpoint (includes git commit ID)
curl https://template-001.startanaicompany.com/health

# You should see a response like:
# {
#   "status": "healthy",
#   "postgres": "connected",
#   "redis": "connected",
#   "timestamp": "2026-02-14T10:30:00.000Z",
#   "git_commit": "eb6b6e0...",
#   "version": "1.0.0"
# }

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

**Note:** The `git_commit` field in the health endpoint shows which version is deployed, making it easy for AI agents to track deployments.

---

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

```bash
# 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

```bash
# 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, and returns deployment version information.

**Response:**
```json
{
  "status": "healthy",
  "postgres": "connected",
  "redis": "connected",
  "timestamp": "2026-02-14T10:30:00.000Z",
  "git_commit": "eb6b6e0a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q",
  "version": "1.0.0"
}
```

**Error Response:**
```json
{
  "status": "unhealthy",
  "error": "Connection error message",
  "git_commit": "eb6b6e0a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q",
  "version": "1.0.0"
}
```

**Version Tracking:**
- `git_commit`: The Git commit SHA of the deployed code (auto-detected during build)
- `version`: Application version (defaults to 1.0.0, can be set via APP_VERSION env var)

This allows AI agents and monitoring tools to verify which version is currently running.

---

## Troubleshooting

### Deployment Fails

**Check logs:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
saac logs --follow
```

**View environment variables:**
```bash
saac env list
```

**Check application status:**
```bash
saac status
```

---

## Advanced Configuration

### Pre-deployment Scripts

Run database migrations before deployment:

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

### Health Check Configuration

Enable health checks:

```bash
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