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.

4. Connect Your Git Account (Required!)

Before deploying any application, you MUST connect your Git account via OAuth:

saac git connect

This will open a browser for OAuth authorization. Once connected, you can deploy unlimited applications without manually providing Git tokens.

5. 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:YourOrg/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

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

6. 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"

7. 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"

8. 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
• Test your Docker Compose configuration locally before deploying
• Check your build logs if deployment fails: saac logs --follow

9. 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
• Docker and Docker Compose (for local container testing)

Setup

# Install dependencies
npm install

# Run development server
npm run dev

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

Local Docker Testing

# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Stop and remove volumes (clean slate)
docker-compose down -v

---

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

Open remote shell:

saac shell

Inside the container:

# Check if app is running
ps aux | grep node

# View environment variables
printenv

# Check database connection
nc -zv postgres 5432

# Check Redis connection
nc -zv redis 6379

# View application logs
tail -f /var/log/app.log

---

Advanced Configuration

Custom Domain

To use a custom domain instead of *.startanaicompany.com:

saac domain add yourdomain.com

# Update Traefik labels in docker-compose.yml
# Then redeploy
saac deploy

Resource Limits

Set CPU and memory limits:

saac update \
  --cpu-limit 2 \
  --memory-limit 2G

saac deploy

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 locally with Docker Compose
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