docs: Add Quick Start guide and update .env.example for development

- Add comprehensive QUICKSTART.md with step-by-step instructions
- Update .env.example to use port 8888 for development
- Include troubleshooting section
- Add application deployment examples
- Document all supported application types

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

Co-Authored-By: Claude <noreply@anthropic.com>

.env.example

@@ -10,8 +10,10 @@ NODE_ENV=production
 # PORT CONFIGURATION
 # ============================================
 # Nginx Gateway
-HTTP_PORT=80
-HTTPS_PORT=443
+# For development, use 8888 to avoid conflicts with system services
+# For production, use 80/443
+HTTP_PORT=8888
+HTTPS_PORT=8443
 
 # Database
 POSTGRES_PORT=5432

QUICKSTART.md

@@ -0,0 +1,264 @@
+# 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
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# Rebuild specific service
+docker compose build api-service
+
+# Restart service
+docker compose up -d api-service
+```
+
+### 3. View Logs
+
+```bash
+# Follow logs
+docker compose logs -f api-service
+
+# View all logs
+docker compose logs --tail=100
+```
+
+### 4. Access Database
+
+```bash
+# 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](docs/DEPLOYMENT.md) for production deployment guide.
+
+## Documentation
+
+- [Architecture](docs/ARCHITECTURE.md)
+- [Deployment System](docs/DEPLOYMENT-SYSTEM.md)
+- [API Documentation](docs/API.md)
+- [WebSocket Guide](docs/WEBSOCKET.md)
+- [URL Structure](docs/URL_STRUCTURE.md)
+
+## 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! 🚀