appserver/README.md

Self-Hostable SaaS Server Stack

A comprehensive, Docker-based SaaS platform inspired by Supabase but designed for self-hosting TypeScript applications.

Features

• Authentication Service: Complete auth system with JWT tokens, registration, login, password management
• API Service: Core API with organization management, application hosting, and deployment
• Database: PostgreSQL with Row Level Security (RLS) for multi-tenancy
• Caching: Redis for sessions and performance
• Storage: MinIO for S3-compatible file storage
• Monitoring: Prometheus + Grafana for observability
• API Gateway: Nginx-based routing and load balancing
• Real-time: WebSocket support for real-time features
• Database Admin: pgAdmin for database management
• MCP Server: Model Context Protocol server for AI/LLM integration

Quick Start

1. Clone and Setup

   cp .env.example .env
   # Edit .env with your configuration
   

2. Start Services

   npm run start
   # or
   docker-compose up -d
   

Access Points

Main Services

• API Gateway: http://localhost:8888
• Auth Service: http://localhost:8888/auth
• API Service: http://localhost:8888/api

Administration

• Database Admin (pgAdmin): http://localhost:5050
  • Login: admin@example.com / admin_password_change_me
• Storage UI (MinIO): http://localhost:9001
  • Login: minioadmin / minioadmin_change_me

Monitoring

• Prometheus: http://localhost:9090
• Grafana: http://localhost:3003
  • Login: admin / admin_password_change_me

Database

• PostgreSQL: localhost:5432
  • Database: saas_db
  • User: saas_user
  • Password: secure_password_change_me

Cache

• Redis: localhost:6379
  • Password: redis_secure_password_change_me

MCP Server Integration

For AI/LLM integration, see MCP Server Setup:

# Install MCP server
cd mcp-server && npm install -g .

# Configure Claude Desktop (see CLAUDE_DESKTOP_CONFIG.md)
# Add to ~/.config/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "saas-platform": {
      "command": "mcp-saas-server",
      "env": {
        "SAAS_API_URL": "http://localhost:8888",
        "SAAS_AUTH_URL": "http://localhost:8888/auth",
        "SAAS_STORAGE_URL": "http://localhost:8888/storage"
      }
    }
  }
}

Default Credentials

• pgAdmin: admin@example.com / admin_password_change_me
• MinIO Storage: minioadmin / minioadmin_change_me
• Grafana: admin / admin_password_change_me
• Database: saas_user / secure_password_change_me
• Redis: Password: redis_secure_password_change_me

✅ All Services Status

Service	Status	Port	Access
PostgreSQL	✅ Healthy	5432	localhost:5432
Redis	✅ Healthy	6379	localhost:6379
API Gateway	✅ Running	8888	http://localhost:8888
Auth Service	✅ Running	3001	http://localhost:3001
API Service	✅ Running	3000	http://localhost:3000
Real-time Service	✅ Running	3002	http://localhost:3002
MinIO Storage	✅ Healthy	9000/9001	http://localhost:9001
pgAdmin	✅ Running	5050	http://localhost:5050
Prometheus	✅ Running	9090	http://localhost:9090
Grafana	✅ Running	3003	http://localhost:3003

🚀 Platform Features Ready

• ✅ User authentication with JWT tokens
• ✅ Multi-tenant organization management
  
• ✅ TypeScript application hosting
• ✅ Deployment management with rollbacks
• ✅ File storage (S3-compatible)
• ✅ Real-time WebSocket support
• ✅ Complete monitoring stack
• ✅ AI/LLM integration via MCP
• ✅ 15 MCP tools for programmatic access

Services Overview

Authentication Service (Port 3001)

• User registration and login
• JWT-based authentication
• Token refresh mechanism
• Profile management
• Password reset (coming soon)

API Service (Port 3000)

• Organization management
• Application hosting and deployment
• File storage integration
• Real-time WebSocket support
• Audit logging

Database (Port 5432)

• PostgreSQL 15 with extensions
• Row Level Security for multi-tenancy
• Pre-configured schema for users, orgs, apps
• Connection pooling

Storage (Ports 9000/9001)

• MinIO S3-compatible storage
• Web UI for file management
• Integration with API service
• Automatic backups (configurable)

Monitoring

• Prometheus: Metrics collection
• Grafana: Data visualization and dashboards

Architecture

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│   Nginx     │    │   Auth       │    │  PostgreSQL │
│  Gateway    │◄──►│  Service     │◄──►│  Database   │
└─────────────┘    └──────────────┘    └─────────────┘
       │                   │
       ▼                   ▼
┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│    Redis    │    │    API       │    │   MinIO     │
│    Cache    │◄──►│  Service     │◄──►│   Storage   │
└─────────────┘    └──────────────┘    └─────────────┘

Environment Variables

Copy .env.example to .env and configure:

• Database: PostgreSQL credentials
• Redis: Cache configuration
• JWT: Secret for token signing
• MinIO: Storage credentials
• Grafana: Admin password

Development

Local Development

# Install dependencies
npm install

# Start in development mode
npm run dev

# View logs
npm run logs

# Stop services
npm run stop

Adding New Services

1. Create service directory in services/
2. Add Dockerfile and package.json
3. Add service to docker-compose.yml
4. Configure routing in nginx/conf.d/
5. Update monitoring as needed

TypeScript Application Hosting

The platform supports hosting TypeScript applications:

1. Create app in apps/ directory
2. Configure build/start commands
3. Use the API to register the application
4. Deploy via the deployment endpoints

API Documentation

Authentication Endpoints

• POST /auth/register - Register new user
• POST /auth/login - User login
• POST /auth/logout - User logout
• GET /auth/me - Get current user
• PUT /auth/profile - Update profile
• PUT /auth/password - Change password

Application Endpoints

• GET /api/applications - List applications
• POST /api/applications - Create application
• GET /api/applications/:id - Get application details
• PUT /api/applications/:id - Update application
• DELETE /api/applications/:id - Delete application

Deployment Endpoints

• POST /api/deployments - Create deployment
• GET /api/deployments/:id - Get deployment status
• POST /api/deployments/:id/rollback - Rollback deployment

Security Features

• Row Level Security (RLS) in PostgreSQL
• JWT-based authentication with refresh tokens
• Rate limiting on all endpoints
• CORS configuration
• Security headers via Helmet
• Encrypted password storage

Monitoring and Logging

• Structured logging across all services
• Prometheus metrics collection
• Grafana dashboards
• Health check endpoints
• Audit logging for all actions

Production Deployment

For production deployment:

1. Change default passwords in .env
2. Configure SSL certificates in nginx/ssl/
3. Set up external database or use persistent volumes
4. Configure backup strategies
5. Set up monitoring alerts
6. Review security settings

Contributing

1. Fork the repository
2. Create feature branch
3. Make changes
4. Test thoroughly
5. Submit pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

• Check the documentation
• Review logs via npm run logs
• Create an issue in the repository