appserver/docs/DEPLOYMENT-SYSTEM.md

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

POST /api/applications/:id/deploy

Starts deployment of an application.

Response:

{
  "message": "Deployment started",
  "appId": "uuid"
}

Stop Application

POST /api/applications/:id/stop

Stops a running application.

Get Deployments

GET /api/applications/:id/deployments?page=1&limit=20

Lists all deployments for an application.

Get Deployment Logs

GET /api/applications/:id/deployments/:deploymentId/logs

Returns build and deployment logs.

Get Container Logs

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:

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

# 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:

   curl http://localhost:8888/api/applications/{id}/deployments/{deploymentId}/logs
   

2. Check container logs:

   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:

   docker exec saas-gateway cat /etc/nginx/conf.d/apps-proxy.conf
   

3. Test nginx configuration:

   docker exec saas-gateway nginx -t
   

4. Check container is running:

   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
• Nginx Reverse Proxy
• Dockerode