appserver/QUICKSTART.md

Quick Start Guide - Development

Prerequisites

• Docker and Docker Compose installed
• Git
• 8GB RAM minimum
• Ports available: 8888, 8443, 5432, 6379, 3000-3003, 5173, 9000-9001, 9090

Quick Start (Development)

1. Clone and Setup

git clone <your-repo-url>
cd appserver

# Create .env file for development
echo "HTTP_PORT=8888" > .env
echo "HTTPS_PORT=8443" >> .env

2. Start Services

# Build and start all services
docker compose up -d

# Wait for services to be healthy (30-60 seconds)
docker compose ps

3. Access the Platform

• Dashboard: http://localhost:8888
• API: http://localhost:8888/api
• WebSocket: ws://localhost:8888/ws
• Grafana: http://localhost:3003 (admin/admin)
• Prometheus: http://localhost:9090
• MinIO Console: http://localhost:9001 (minioadmin/minioadmin_change_me)

4. Create Admin User

# Connect to database
docker exec -it saas-postgres psql -U saas_user -d saas_db

# Create admin user (in psql)
INSERT INTO __sys_users (email, password, role, email_verified)
VALUES ('admin@localhost', crypt('admin123', gen_salt('bf')), 'admin', true);

# Exit psql
\q

5. Login

1. Open http://localhost:8888
2. Login with: admin@localhost / admin123
3. Start deploying applications!

Deploy Your First Application

Option 1: Via Dashboard

1. Navigate to Applications page
2. Click Deploy Application
3. Fill in the form:
   • Name: My App
   • Slug: my-app
   • Type: Select your app type (npm, react, nextjs, etc.)
   • Repository URL: Your git repository URL
   • Branch: main (or your branch)
   • Port: 3000 (or your app's port)
4. Click Create & Deploy
5. Access your app at: http://localhost:8888/my-app/

Option 2: Via API

# Get auth token
TOKEN=$(curl -s -X POST http://localhost:8888/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@localhost","password":"admin123"}' \
  | jq -r '.accessToken')

# Create and deploy application
curl -X POST http://localhost:8888/api/applications \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "slug": "my-app",
    "appType": "npm",
    "repositoryUrl": "https://github.com/user/repo.git",
    "branch": "main",
    "buildCommand": "npm install",
    "startCommand": "npm start",
    "port": 3000,
    "environment": {
      "NODE_ENV": "production"
    }
  }'

# Get app ID from response, then deploy
APP_ID="<app-id>"
curl -X POST "http://localhost:8888/api/applications/$APP_ID/deploy" \
  -H "Authorization: Bearer $TOKEN"

# Check deployment logs
curl "http://localhost:8888/api/applications/$APP_ID/logs" \
  -H "Authorization: Bearer $TOKEN"

Supported Application Types

Type	Use Case	Example
npm	Node.js apps	Express, Fastify, Koa
react	React apps	Vite, CRA
nextjs	Next.js apps	Full-stack React
php	PHP apps	Laravel, WordPress
python	Python apps	Flask, Django, FastAPI
static	Static sites	HTML/CSS/JS
docker	Custom Docker	Any Dockerfile

Stopping and Cleaning Up

# Stop all services
docker compose down

# Stop and remove volumes (WARNING: deletes all data)
docker compose down -v

# View logs
docker compose logs -f api-service
docker compose logs -f auth-service

Troubleshooting

Port 80 already in use

If you see "address already in use" error:

# Make sure .env has port 8888
echo "HTTP_PORT=8888" > .env
echo "HTTPS_PORT=8443" >> .env

# Restart services
docker compose down
docker compose up -d

Database connection errors

# Check if database is running
docker compose ps postgres

# View database logs
docker compose logs postgres

# Reset database (WARNING: deletes all data)
docker compose down -v
docker compose up -d

Service keeps restarting

# Check service logs
docker compose logs <service-name>

# Common issues:
# - Database not ready: Wait 30 seconds
# - Wrong credentials: Check .env file
# - Port conflict: Change ports in .env

Application deployment fails

# Get app ID from dashboard
APP_ID="<your-app-id>"

# Check deployment logs
curl "http://localhost:8888/api/applications/$APP_ID/logs" \
  -H "Authorization: Bearer $TOKEN"

# Common issues:
# - Invalid git URL
# - Missing Dockerfile (for docker type)
# - Wrong build/start commands
# - Missing dependencies in repository

Development Workflow

1. Make Code Changes

Edit files in services/api, services/auth, or dashboard

2. Rebuild Service

# Rebuild specific service
docker compose build api-service

# Restart service
docker compose up -d api-service

3. View Logs

# Follow logs
docker compose logs -f api-service

# View all logs
docker compose logs --tail=100

4. Access Database

# Using psql
docker exec -it saas-postgres psql -U saas_user -d saas_db

# Using adminer (if available)
# Open http://localhost:8080

Production Deployment

See docs/DEPLOYMENT.md for production deployment guide.

Documentation

• Architecture
• Deployment System
• API Documentation
• WebSocket Guide
• URL Structure

Support

• GitHub Issues: https://github.com/yourusername/appserver/issues
• Documentation: See docs/ directory
• Examples: See examples/ directory

What's Next?

1. ✅ Create your first application deployment
2. ✅ Explore the dashboard features
3. ✅ Set up custom domains for your apps
4. ✅ Configure email templates
5. ✅ Set up RLS policies for data security
6. ✅ Monitor with Grafana dashboards
7. ✅ Scale your applications

Happy coding! 🚀