# 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

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

```bash
# Use development environment
cp .env.development .env
```

### 2. Generate SSL Certificates (for WSS testing)

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

### 3. Start Services

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

```bash
# 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](docs/DEPLOYMENT.md)** - Complete production deployment instructions
- **[Architecture](docs/ARCHITECTURE.md)** - System architecture diagrams
- **[WebSocket API](docs/WEBSOCKET.md)** - Real-time WebSocket documentation
- **[API Keys](API_KEYS.md)** - API authentication guide
- **[Row Level Security](docs/ROW_LEVEL_SECURITY.md)** - Database security

---

## 🛠️ Common Commands

### View Logs

```bash
# All services
docker-compose logs -f

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

### Restart Services

```bash
# All services
docker-compose restart

# Specific service
docker-compose restart api-service
```

### Check Service Status

```bash
# List all containers
docker-compose ps

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

### Database Access

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

```bash
# Pull latest code
git pull origin main

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

---

## 🐛 Troubleshooting

### DNS Not Resolving

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

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

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

```bash
# 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/](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! 🎉**