# 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! 🚀