# Application Deployment System

## Overview

The platform includes a comprehensive application deployment system that allows users to deploy applications from Git repositories directly through the dashboard. The system supports multiple application types and handles the entire deployment lifecycle from git clone to running containers with automatic nginx proxy configuration.

## Supported Application Types

### 1. **Node.js / npm** (`npm`)
- Standard Node.js applications
- Auto-detects and runs `npm install` and `npm start`
- Default port: 3000

### 2. **React** (`react`)
- React applications (Vite, Create React App, etc.)
- Builds production bundle with `npm run build`
- Serves with `npm run preview`
- Default port: 3000

### 3. **Next.js** (`nextjs`)
- Next.js applications
- Builds with `npm run build`
- Starts production server with `npm start`
- Default port: 3000

### 4. **PHP** (`php`)
- PHP applications
- Uses Apache with PHP 8.2
- Automatically installs PDO and MySQLi extensions
- Default port: 80

### 5. **Python** (`python`)
- Python applications (Flask, Django, FastAPI, etc.)
- Auto-installs dependencies from `requirements.txt`
- Runs with custom start command or `python app.py`
- Default port: 3000

### 6. **Static HTML** (`static`)
- Static websites (HTML, CSS, JavaScript)
- Served with nginx
- No build process required
- Default port: 80

### 7. **Custom Docker** (`docker`)
- Applications with custom Dockerfile
- Uses existing Dockerfile in repository
- Complete control over build process
- Configurable port

## Architecture

### Components

1. **Deployment Service** (`services/api/src/services/deployment.ts`)
   - Handles git cloning
   - Generates Dockerfiles based on app type
   - Builds Docker images
   - Manages container lifecycle
   - Tracks deployment status

2. **Nginx Service** (`services/api/src/services/nginx.ts`)
   - Generates dynamic nginx configurations
   - Creates proxy rules for applications
   - Supports slug-based routing (`/app-slug/`)
   - Supports custom domain routing
   - Auto-reloads nginx on changes

3. **Database Schema**
   - `__sys_applications`: Stores application metadata
   - `__sys_deployments`: Tracks deployment history and logs

### Deployment Flow

```
User submits deployment form
         ↓
Create application record in database
         ↓
Create deployment record (status: pending)
         ↓
Clone git repository
         ↓
Generate Dockerfile based on app type
         ↓
Build Docker image
         ↓
Stop existing container (if any)
         ↓
Start new container
         ↓
Update nginx configuration
         ↓
Reload nginx
         ↓
Mark deployment as deployed
```

## API Endpoints

### Deploy Application
```bash
POST /api/applications/:id/deploy
```

Starts deployment of an application.

**Response:**
```json
{
  "message": "Deployment started",
  "appId": "uuid"
}
```

### Stop Application
```bash
POST /api/applications/:id/stop
```

Stops a running application.

### Get Deployments
```bash
GET /api/applications/:id/deployments?page=1&limit=20
```

Lists all deployments for an application.

### Get Deployment Logs
```bash
GET /api/applications/:id/deployments/:deploymentId/logs
```

Returns build and deployment logs.

### Get Container Logs
```bash
GET /api/applications/:id/logs
```

Returns runtime container logs.

## Nginx Routing

### Slug-based Routing

Applications are accessible at `/<slug>/`:

```
http://localhost:8888/my-app/
```

### Custom Domain Routing

Applications can be configured with custom domains:

```nginx
server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://saas-app-{id}:3000;
    }
}
```

## Environment Variables

Applications can define environment variables in the deployment form:

```
NODE_ENV=production
API_KEY=your-api-key
DATABASE_URL=postgresql://...
PORT=3000
```

## Build Commands

### Default Build Commands by Type

| Type    | Build Command                        | Start Command    |
|---------|--------------------------------------|------------------|
| npm     | `npm install`                        | `npm start`      |
| react   | `npm install && npm run build`       | `npm run preview`|
| nextjs  | `npm install && npm run build`       | `npm start`      |
| php     | (none)                               | (apache)         |
| python  | `pip install -r requirements.txt`    | `python app.py`  |
| static  | (none)                               | (nginx)          |

### Custom Commands

Users can override the default build and start commands in the deployment form.

## Docker Configuration

### Container Naming

Containers are named using the pattern:
```
saas-app-{application-id}
```

### Network

All deployed applications run in the `saas-network` Docker network, allowing them to communicate with other platform services.

### Restart Policy

Containers use `unless-stopped` restart policy to automatically restart after host reboot.

## Security Considerations

1. **Privileged Mode**: The API service runs in privileged mode to manage Docker containers
2. **Docker Socket**: API service has access to `/var/run/docker.sock`
3. **Isolation**: Each application runs in its own container
4. **Network**: Applications use the internal Docker network
5. **Environment Variables**: Sensitive data should be passed as environment variables

## Usage Example

### From Dashboard

1. Navigate to **Applications** page
2. Click **Deploy Application**
3. Fill in the form:
   - **Name**: My App
   - **Slug**: my-app
   - **Type**: React
   - **Repository URL**: https://github.com/user/repo.git
   - **Branch**: main
   - **Build Command**: npm install && npm run build
   - **Start Command**: npm run preview
   - **Port**: 3000
   - **Environment Variables**:
     ```
     VITE_API_URL=http://localhost:8888/api
     NODE_ENV=production
     ```
4. Click **Create & Deploy**
5. Monitor deployment in the deployments list
6. Access at `http://localhost:8888/my-app/`

### From API

```bash
# Create 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": "react",
    "repositoryUrl": "https://github.com/user/repo.git",
    "branch": "main",
    "buildCommand": "npm install && npm run build",
    "startCommand": "npm run preview",
    "port": 3000,
    "environment": {
      "NODE_ENV": "production"
    }
  }'

# Deploy
curl -X POST http://localhost:8888/api/applications/{id}/deploy \
  -H "Authorization: Bearer $TOKEN"

# Check logs
curl http://localhost:8888/api/applications/{id}/logs \
  -H "Authorization: Bearer $TOKEN"
```

## Troubleshooting

### Deployment Failed

1. Check deployment logs:
   ```bash
   curl http://localhost:8888/api/applications/{id}/deployments/{deploymentId}/logs
   ```

2. Check container logs:
   ```bash
   docker logs saas-app-{id}
   ```

3. Verify git repository is accessible
4. Check Dockerfile generation
5. Ensure build commands are correct

### Application Not Accessible

1. Check application status in dashboard
2. Verify nginx configuration:
   ```bash
   docker exec saas-gateway cat /etc/nginx/conf.d/apps-proxy.conf
   ```
3. Test nginx configuration:
   ```bash
   docker exec saas-gateway nginx -t
   ```
4. Check container is running:
   ```bash
   docker ps | grep saas-app-
   ```

### Container Keeps Restarting

1. Check container logs for errors
2. Verify start command is correct
3. Check port configuration
4. Ensure all dependencies are installed during build

## Limitations

1. **Git Authentication**: Currently supports only public repositories
2. **Build Timeout**: Long builds may timeout (default: 10 minutes)
3. **Resource Limits**: No resource limits per container (configurable)
4. **Secrets Management**: Environment variables are stored in plain text
5. **SSL**: Custom domains require manual SSL certificate setup

## Future Enhancements

- [ ] Support for private Git repositories (SSH keys, tokens)
- [ ] Build artifact caching
- [ ] Multi-container applications (docker-compose support)
- [ ] Blue-green deployments
- [ ] Automatic SSL with Let's Encrypt
- [ ] Resource quotas and limits
- [ ] Health checks and auto-restart
- [ ] Deployment rollback
- [ ] Horizontal scaling
- [ ] CI/CD webhooks for automatic deployments

## References

- [Docker API Documentation](https://docs.docker.com/engine/api/)
- [Nginx Reverse Proxy](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/)
- [Dockerode](https://github.com/apocas/dockerode)