StartAnAiCompanyTemplates/template_001
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add comprehensive documentation to README.md

Browse Source 
- AI Developer Agent instructions with step-by-step guide
- Critical port configuration explanation (no host port mappings)
- Complete deployment guide with all commands used
- Architecture documentation
- Environment variables reference
- API endpoints documentation
- Troubleshooting section
- Advanced configuration examples
- Local development setup

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
ryan.gogo
2026-02-14 06:30:54 +01:00
parent 95c13a841f
commit bf6bb394c2
1 changed files with 578 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

605
README.md
View File

@@ -2,56 +2,607 @@
This is a template site demonstrating how to deploy applications on Start an AI Company servers using Docker Compose and Traefik.
## Features
---
- Node.js Express application
- PostgreSQL database
- Redis caching
- Docker Compose configuration
- Traefik-ready (no host port mappings)
- Modern, clean white UI
## 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.
### 4. Connect Your Git Account (Required!)
Before deploying any application, you MUST connect your Git account via OAuth:
```bash
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:
```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:YourOrg/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
```
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:**
```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"
```
### 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**
```bash
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
```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
curl https://template-001.startanaicompany.com/health
# View the website
curl https://template-001.startanaicompany.com
```
---
## Architecture
- **App**: Node.js Express server running on port 3000 (internal)
- **Database**: PostgreSQL 15
- **Cache**: Redis 7
- **Routing**: Traefik handles external routing and SSL
### Application Stack
## Deployment
- **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)
Deploy using the SAAC command:
### Network Architecture
```bash
saac create application
```
Internet
↓
Traefik (Reverse Proxy)
↓
Docker Network (app-network)
├── app:3000 (Node.js)
├── postgres:5432
└── redis:6379
```
This will deploy the application to https://template-001.startanaicompany.com
### 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
```bash
# Install dependencies
npm install
# Run development server
npm run dev
```
## Docker Deployment
The application will be available at http://localhost:3000
### Local Docker Testing
```bash
# 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
- `PORT`: Application port (default: 3000)
- `POSTGRES_HOST`: PostgreSQL host
- `POSTGRES_PORT`: PostgreSQL port
- `POSTGRES_USER`: PostgreSQL user
- `POSTGRES_PASSWORD`: PostgreSQL password
- `POSTGRES_DB`: PostgreSQL database name
- `REDIS_HOST`: Redis host
- `REDIS_PORT`: Redis port
The application uses the following environment variables:
## Health Check
### Application Configuration
Visit `/health` endpoint to check service status.
- `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.
**Response:**
```json
{
"status": "healthy",
"postgres": "connected",
"redis": "connected",
"timestamp": "2026-02-14T10:30:00.000Z"
}
```
**Error Response:**
```json
{
"status": "unhealthy",
"error": "Connection error message"
}
```
---
## 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
**Open remote shell:**
```bash
saac shell
```
**Inside the container:**
```bash
# 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`:
```bash
saac domain add yourdomain.com
# Update Traefik labels in docker-compose.yml
# Then redeploy
saac deploy
```
### Resource Limits
Set CPU and memory limits:
```bash
saac update \
--cpu-limit 2 \
--memory-limit 2G
saac deploy
```
### 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 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