appserver

SaaS Platform - Quick Start Guide

🚀 Quick Deployment (Production)

1. Prerequisites

• Domain name with DNS configured:
  • A record: yourdomain.com → your server IP
  • A record: console.yourdomain.com → your server IP
  • A record: *.yourdomain.com → your server IP (wildcard)
• Server with Ubuntu/Debian/CentOS (4GB RAM, 2 CPU minimum)
• Ports 80 and 443 accessible from internet

2. Deploy

# Clone repository
git clone https://github.com/yourusername/saas-platform.git
cd saas-platform

# Run deployment script
chmod +x deploy.sh
./deploy.sh

The script will:

• ✅ Validate DNS records
• ✅ Install Certbot and generate SSL certificates
• ✅ Configure Nginx for HTTPS/WSS
• ✅ Create environment with random passwords
• ✅ Deploy all services with Docker Compose
• ✅ Setup auto-renewal for SSL certificates

3. Access

• Dashboard: https://console.yourdomain.com
• Main Site: https://yourdomain.com (Hello World app)
• WebSocket: wss://console.yourdomain.com/ws

---

💻 Development Setup (Local)

1. Copy Environment File

# Use development environment
cp .env.development .env

2. Generate SSL Certificates (for WSS testing)

cd ssl
./generate-certs.sh
cd ..

3. Start Services

docker-compose up -d

4. Access

• Dashboard: http://localhost:8888
• WebSocket: ws://localhost:8888/ws
• Secure WebSocket: wss://localhost:8443/ws (self-signed cert warning expected)

---

📁 Environment Files

.env.example (Template)

Production template with placeholders. The deploy.sh script generates a .env from this.

.env.development (Local Development)

Pre-configured for local development with:

• Non-standard ports (8888 for HTTP, 8443 for HTTPS)
• Weak passwords (only for dev!)
• Localhost domains
• Longer token expiration for easier testing

.env (Active Configuration)

• Production: Generated by deploy.sh with secure random passwords
• Development: Copy from .env.development

⚠️ Never commit .env to version control!

---

🔧 Port Configuration

Ports are configurable via environment variables in .env:

Service	Production	Development	Environment Variable
HTTP	80	8888	HTTP_PORT
HTTPS	443	8443	HTTPS_PORT
PostgreSQL	5432	5432	POSTGRES_PORT
Redis	6379	6379	REDIS_PORT

Why Different Ports in Development?

Development uses ports 8888/8443 to:

• Avoid conflicts with other local services
• Allow running multiple instances simultaneously
• No need for root/sudo permissions

---

🔐 Security

Production Checklist

• DNS records configured (A, console, wildcard)
• Firewall configured (ports 80, 443, 22 only)
• .env file permissions set to 600
• Random strong passwords generated
• SSL certificates auto-renewing
• Database backups scheduled
• Monitoring dashboards reviewed

Generate Secure Passwords

# Database password
openssl rand -base64 32

# JWT secret
openssl rand -base64 64

# MinIO keys
openssl rand -hex 16  # Access key
openssl rand -base64 32  # Secret key

---

📚 Documentation

• Deployment Guide - Complete production deployment instructions
• Architecture - System architecture diagrams
• WebSocket API - Real-time WebSocket documentation
• API Keys - API authentication guide
• Row Level Security - Database security

---

🛠️ Common Commands

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f api-service
docker-compose logs -f nginx

Restart Services

# All services
docker-compose restart

# Specific service
docker-compose restart api-service

Check Service Status

# List all containers
docker-compose ps

# Check health
curl http://localhost:8888/health  # Development
curl https://console.yourdomain.com/health  # Production

Database Access

# Connect to PostgreSQL
docker exec -it saas-postgres psql -U saas_user -d saas_platform

# Backup database
docker exec saas-postgres pg_dump -U saas_user saas_platform > backup.sql

# Restore database
cat backup.sql | docker exec -i saas-postgres psql -U saas_user -d saas_platform

Update Platform

# Pull latest code
git pull origin main

# Rebuild and restart
docker-compose down
docker-compose up -d --build

---

🐛 Troubleshooting

DNS Not Resolving

# Check DNS propagation
dig +short A yourdomain.com
dig +short A console.yourdomain.com
dig +short A test.yourdomain.com  # Test wildcard

# Wait for propagation (can take up to 48 hours)

Certificate Generation Failed

# Check port 80 is accessible
curl -I http://yourdomain.com

# Check Certbot logs
sudo cat /var/log/letsencrypt/letsencrypt.log

# Try manual renewal
sudo certbot renew --dry-run

Services Not Starting

# Check Docker daemon
sudo systemctl status docker

# Check logs for errors
docker-compose logs

# Rebuild containers
docker-compose down
docker-compose up -d --build

Cannot Access Dashboard

# Check if Nginx is running
docker ps | grep nginx

# Check Nginx logs
docker logs saas-gateway

# Check Nginx configuration
docker exec saas-gateway nginx -t

# Reload Nginx
docker exec saas-gateway nginx -s reload

---

🎯 Next Steps

After deployment:

1. Create Admin Account - Visit dashboard and register
2. Configure SMTP - Setup email sending in settings
3. Create API Keys - Generate keys for external access
4. Setup Monitoring - Configure Grafana dashboards
5. Schedule Backups - Automate database backups
6. Review Security - Check SSL, headers, and firewall

---

📝 Development vs Production

Feature	Development	Production
HTTP Port	8888	80
HTTPS Port	8443	443
SSL Certificates	Self-signed	Let's Encrypt
Passwords	Weak (for testing)	Strong random
Token Expiry	24h	15m
Domain	localhost	yourdomain.com
Node Environment	development	production
Hot Reload	Yes	No
Debug Logs	Verbose	Error only

---

💡 Tips

• Development: Use .env.development and access via http://localhost:8888
• Production: Use ./deploy.sh which generates .env automatically
• Testing: Test locally before deploying to production
• Backup: Always backup .env and database before updates
• Security: Keep .env secure with chmod 600 .env
• Monitoring: Check Grafana for service health and performance

---

🆘 Getting Help

• Documentation: Check docs/ directory
• Logs: Run docker-compose logs -f [service-name]
• Health Check: curl http://localhost:8888/health
• Issues: Report bugs on GitHub

---

Enjoy building with the SaaS Platform! 🎉