# Light Cloud - Complete Documentation

> Light Cloud is a deployment platform that enables developers to deploy applications (static sites and containers) and manage databases directly from GitHub repositories. Similar to Vercel or Netlify, but with support for both static hosting and containerized applications plus managed PostgreSQL databases.

---

## Platform Overview

### Key Features
- **30-Day Free Trial** - Up to 3 resources, no payment required for first 2 weeks
- **Static Site Deployments** - React, Next.js, Vue, Angular with global CDN
- **Container Deployments** - Node.js, Python, Go, Java, Ruby, PHP, .NET with auto-scaling
- **Managed Databases** - PostgreSQL databases with automated provisioning
- **GitHub Integration** - OAuth connection and GitHub App for auto-deployments
- **Multi-Environment Support** - Auto-create environments per branch
- **Custom Domains** - Automatic SSL and DNS management
- **Real-time Updates** - Socket.IO-based live deployment status
- **Usage-based Billing** - Pay only for what you use via Stripe

### Console URLs
- **Production Console**: https://console.light-cloud.com
- **API Endpoint**: https://api.light-cloud.com

---

## Supported Frameworks & Runtimes

### Static Site Frameworks
| Framework | Auto-Detection | Build Command | Output Directory |
|-----------|---------------|---------------|------------------|
| React | `package.json` with `react` | `npm run build` | `build` |
| Next.js (Static) | `next.config.js` with `output: "export"` | `npm run build` | `out` |
| Vue.js | `package.json` with `vue` | `npm run build` | `dist` |
| Angular | `angular.json` | `npm run build` | `dist/{project}` |
| Svelte | `package.json` with `svelte` | `npm run build` | `build` |
| Plain HTML | `index.html` in root | None | Root directory |

### Container Runtimes
| Runtime | Auto-Detection | Default Port |
|---------|---------------|--------------|
| Node.js | `package.json` | 8080 |
| Python | `requirements.txt` or `pyproject.toml` | 8080 |
| Go | `go.mod` | 8080 |
| Java | `pom.xml` or `build.gradle` | 8080 |
| Ruby | `Gemfile` | 8080 |
| PHP | `composer.json` | 8080 |
| .NET | `*.csproj` or `*.fsproj` | 8080 |
| Custom | `Dockerfile` | User-defined |

### Full-Stack Frameworks (Container)

**Node.js Frameworks:**
| Framework | Detection |
|-----------|-----------|
| Next.js (SSR) | API routes or no `output: "export"` |
| Nuxt.js | `nuxt` in dependencies |
| Remix | `@remix-run/node` in dependencies |
| Express.js | `express` in dependencies |
| Fastify | `fastify` in dependencies |
| NestJS | `@nestjs/core` in dependencies |
| Koa | `koa` in dependencies |
| Hono | `hono` in dependencies |
| AdonisJS | `@adonisjs/core` in dependencies |

**Python Frameworks:**
| Framework | Detection |
|-----------|-----------|
| Django | `django` in requirements |
| Flask | `flask` in requirements |
| FastAPI | `fastapi` in requirements |
| Starlette | `starlette` in requirements |
| Tornado | `tornado` in requirements |

**Go Frameworks:**
| Framework | Detection |
|-----------|-----------|
| Gin | `github.com/gin-gonic/gin` in go.mod |
| Fiber | `github.com/gofiber/fiber` in go.mod |
| Echo | `github.com/labstack/echo` in go.mod |
| Chi | `github.com/go-chi/chi` in go.mod |

**Ruby Frameworks:**
| Framework | Detection |
|-----------|-----------|
| Rails | `rails` in Gemfile |
| Sinatra | `sinatra` in Gemfile |
| Hanami | `hanami` in Gemfile |

**PHP Frameworks:**
| Framework | Detection |
|-----------|-----------|
| Laravel | `laravel/framework` in composer.json |
| Symfony | `symfony/framework-bundle` in composer.json |
| Slim | `slim/slim` in composer.json |

**Java Frameworks:**
| Framework | Detection |
|-----------|-----------|
| Spring Boot | Spring dependencies in pom.xml |
| Quarkus | `quarkus` in pom.xml |
| Micronaut | `micronaut` in pom.xml |

**.NET Frameworks:**
| Framework | Detection |
|-----------|-----------|
| ASP.NET Core | `Microsoft.AspNetCore` in .csproj |
| Minimal APIs | .NET 6+ project |

---

## Deployment Types

### Static Sites
- **Frameworks**: React, Next.js (static), Vue, Angular, Svelte, plain HTML
- **Hosting**: Global CDN with edge caching
- **Auto-detection**: Framework and build settings detected from repository
- **SSL**: Automatic certificate provisioning
- **Pricing**: ~$0.039/GB storage, ~$0.21/GB bandwidth

### Container Applications
- **Runtimes**: Node.js, Python, Go, Java, Ruby, PHP, .NET, or custom Dockerfile
- **Node.js**: Next.js SSR, Nuxt, Remix, Express, Fastify, NestJS, Koa, Hono, AdonisJS
- **Python**: Django, Flask, FastAPI, Starlette, Tornado
- **Go**: Gin, Fiber, Echo, Chi
- **Ruby**: Rails, Sinatra, Hanami
- **PHP**: Laravel, Symfony, Slim
- **Java**: Spring Boot, Quarkus, Micronaut
- **.NET**: ASP.NET Core, Minimal APIs
- **Hosting**: Managed container platform with auto-scaling
- **Auto-generated Dockerfiles**: For common runtimes when no Dockerfile exists
- **Configuration**:
  - CPU: 1-8 vCPU
  - Memory: 256MB-32GB
  - Min/Max instances: 0-100
  - Port: Configurable (default 8080)
- **Scale-to-zero**: By default, containers only run when receiving traffic
- **Pricing**: From ~$0.06/hour (256MB) to ~$0.70/hour (32GB)

#### Memory/CPU Compatibility
| Memory | Valid CPU Range |
|--------|-----------------|
| 512Mi, 1Gi | 1-2 |
| 2Gi, 4Gi | 1-4 |
| 8Gi | 2-8 |
| 16Gi | 4-8 |

### Managed Databases (PostgreSQL)
- **Tiers**: Dev (shared), Starter, Pro, Business, Enterprise
- **Features**: Automated provisioning, connection string management
- **High availability**: Optional for Pro tier and above
- **Pricing**: From ~$0.02/hour (Dev) to ~$0.46/hour (Enterprise)

---

## GitHub Integration

### OAuth Connection
- Personal GitHub account linking for repository access
- Required scopes: `repo` for private repository access

### GitHub App Installation
- Organization-wide installation for team access
- Enables auto-deploy for all team members
- Installation token takes precedence over personal OAuth token

### Auto-Deploy Features
| Setting | Default | Description |
|---------|---------|-------------|
| `autoDeployOnPush` | `true` | Deploy when code is pushed to branch |
| `autoDeployBranches` | `true` | Auto-create environments for new branches |
| `autoDeleteStaleEnvs` | `true` | Auto-delete non-production environments when branch deleted |

### Webhook Events Handled
| Event | Action |
|-------|--------|
| `push` | Deploy existing environments or auto-create new |
| `push` (deleted=true) | Auto-delete environment |
| `delete` | Auto-delete environment |
| `create` | Logged (push event follows) |
| `pull_request` (merged) | Logged (push handles deploy) |

### Protection Rules
- Production environments (`is_production: true`) are never auto-deleted
- Same commit that previously failed won't be auto-deployed again

---

## Subdomain Routing

### Auto-Generated Subdomains
Format: `{branch}-{app-slug}-{org-slug}.light-cloud.io`

Examples:
- `main-dashboard-startup.light-cloud.io`
- `feature-auth-api-hudson-llc.light-cloud.io`
- `develop-frontend-acme-corp.light-cloud.io`

### Architecture
1. User visits `main-my-app-acme-corp.light-cloud.io`
2. DNS resolves to edge network (wildcard DNS)
3. Edge worker intercepts request
4. Worker calls backend: `GET /api/applications/lookup/{subdomain}`
5. Backend returns target URL
6. Worker proxies request to target
7. Response returned with subdomain preserved

### Custom Domains
- Users can set custom domains (e.g., `app.mycompany.com`)
- CNAME record required pointing to environment URL
- Automatic SSL provisioning
- DNS verification required before activation

### Security
- Users cannot set custom domains ending with `.light-cloud.io`
- Prevents subdomain hijacking and impersonation

---

## Environments

### Environment Status States
| Status | Description |
|--------|-------------|
| `pending` | Created, not yet deployed |
| `queued` | Deployment queued |
| `deploying` | Actively deploying |
| `deployed` | Successfully deployed, URL available |
| `failed` | Deployment failed, error message available |
| `deleting` | Deletion in progress |
| `delete_failed` | Deletion failed, can retry |

### Environment Naming Convention
| Branch | Environment Name |
|--------|-----------------|
| `main` | Production |
| `master` | Production |
| `feature/user-auth` | Feature User Auth |
| `dev` | Dev |
| `staging` | Staging |

### Environment Variables
Variables are merged in order of precedence (lowest to highest):
1. `Application.default_environment_vars` - Global defaults
2. `Application.environment_vars` - Legacy compatibility
3. `Environment.environment_vars` - Environment-specific overrides

---

## API Endpoints

### Application Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/applications` | POST | List applications (paginated) |
| `/api/applications/create` | POST | Create application with initial environment |
| `/api/applications/get` | POST | Get single application |
| `/api/applications/update` | POST | Update application settings |
| `/api/applications/delete` | POST | Delete application and all environments |
| `/api/applications/check-domain` | POST | Check custom domain status |

### Environment Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/environments/create` | POST | Create new environment |
| `/api/environments/get` | POST | Get single environment |
| `/api/environments/update` | POST | Update environment settings |
| `/api/environments/deploy` | POST | Deploy environment |
| `/api/environments/delete` | POST | Delete environment |
| `/api/environments/:id/progress` | POST | Webhook for progress updates |

---

## Real-Time Updates

### Socket.IO Events
| Room | Events | Purpose |
|------|--------|---------|
| `env:{envId}` | `environment:update` | Deployment progress, status changes |
| `app:{appId}` | `application:update` | Environment created/deleted |
| `db:{dbId}` | Status updates | Database provisioning progress |
| `org:{orgId}` | Installation events | GitHub App installation |

### Event Payload Example
```json
{
  "environmentId": "env-123",
  "status": "deploying",
  "deployment_stage": "Building project",
  "deployment_logs": [...],
  "deployed_url": null
}
```

---

## Permissions & Roles

### Roles
| Role | Description |
|------|-------------|
| **Owner** | Full access including billing management |
| **Admin** | Invite users, view billing (read-only), manage resources |
| **User** | Read-only access to resources |

### Permissions
| Permission | Owner | Admin | User |
|------------|:-----:|:-----:|:----:|
| `invite:users` | Yes | Yes | No |
| `read:users` | Yes | Yes | Yes |
| `read:billing` | Yes | Yes | No |
| `manage:billing` | Yes | No | No |
| `create:projects` | Yes | Yes | No |
| `read:projects` | Yes | Yes | Yes |
| `update:projects` | Yes | Yes | No |
| `delete:projects` | Yes | Yes | No |

---

## Billing

### Free Trial
- 30 days duration
- Up to 3 resources
- No credit card required for first 2 weeks
- Full feature access

### Pricing Model
- **Usage-Based**: Hourly billing for infrastructure
- **Scale-to-Zero**: Containers only billed when receiving traffic
- **Team Members**: $9/user/month
- **Billing Period**: Monthly via Stripe

### Container Pricing (per hour)
| Size | vCPU | Memory | Price/hour |
|------|------|--------|------------|
| Nano | 1 | 256 MB | ~$0.06 |
| Micro | 1 | 512 MB | ~$0.06 |
| Small | 1 | 1 GB | ~$0.07 |
| Medium | 2 | 2 GB | ~$0.13 |
| Large | 4 | 4 GB | ~$0.27 |
| XL | 4 | 8 GB | ~$0.36 |

### Database Pricing (per hour, always-on)
| Tier | vCPU | RAM | Price/hour |
|------|------|-----|------------|
| Dev | Shared | 0.6 GB | ~$0.02 |
| Starter | Shared | 1.7 GB | ~$0.05 |
| Pro | 1 | 4 GB | ~$0.11 |
| Business | 2 | 8 GB | ~$0.23 |
| Enterprise | 4 | 16 GB | ~$0.46 |

---

## Security

### Defense-in-Depth Layers
1. **Edge Layer**: Global edge network with built-in protections
2. **Network Layer**: WAF + Global Load Balancer
3. **Transport Layer**: TLS/SSL encryption (managed certificates)
4. **Application Layer**: JWT authentication, webhook signature validation
5. **Database Layer**: IP allowlisting + VPC networking

### Edge Security Features
- **DDoS Protection**: Automatic mitigation of volumetric and application-layer attacks
- **Web Application Firewall (WAF)**: Protection against OWASP Top 10 vulnerabilities
- **Bot Management**: Detection and mitigation of malicious bot traffic
- **Rate Limiting**: Configurable request rate limits to prevent abuse
- **SSL/TLS**: Automatic HTTPS with modern TLS 1.3 support
- **HTTP/2 & HTTP/3**: Modern protocol support for performance and security
- **Always Online**: Cached content served during origin outages
- **IP Reputation**: Blocking of known malicious IP addresses
- **Geo-blocking**: Optional geographic access restrictions
- **Browser Integrity Check**: Validation of legitimate browser requests

---

## Notifications

### Notification Types
| Type | Source | Description |
|------|--------|-------------|
| `invitation` | system | User invited to organisation |
| `admin` | admin | Message from administrator |
| `system` | system | System-generated notifications |

### System Event Notifications
- **Organisation Invitation**: When user is invited to org
- **Deployment Failed**: When deployment fails, all org members notified

---

## Domains

| Domain | Purpose |
|--------|---------|
| `light-cloud.com` | Production platform |
| `light-cloud.io` | Customer subdomains |

---

## Next.js Support

### Deployment Mode Detection
| Configuration | Deployment Type | Hosting |
|--------------|-----------------|---------|
| `output: "export"` | Static | Global CDN |
| No output config (default) | Container (SSR) | Managed containers |
| Has API routes | Container (SSR) | Managed containers |

### Auto-Detection
- Checks `package.json` for `next` dependency
- Reads `next.config.js` for `output` setting
- Scans for API routes in `/app/api` or `/pages/api`

---

## Getting Started Tutorials

### Deploy a Static Website (React, Vue, Next.js)

**Step 1: Sign Up**
1. Go to https://console.light-cloud.com/signup
2. Sign up with GitHub or Google
3. Create your first organisation

**Step 2: Connect GitHub**
1. Click "Connect GitHub" in the dashboard
2. Authorize Light Cloud to access your repositories
3. (Optional) Install the GitHub App for auto-deployments

**Step 3: Create Application**
1. Click "New Application"
2. Select your repository containing the frontend code
3. Light Cloud auto-detects the framework (React, Vue, Next.js, etc.)
4. Confirm build settings:
   - Build command: `npm run build` (auto-detected)
   - Output directory: `dist` or `build` (auto-detected)
5. Click "Create"

**Step 4: Deploy**
1. Your first environment is created automatically (linked to `main` branch)
2. Click "Deploy" or push code to trigger auto-deploy
3. Wait for build to complete (~1-3 minutes)
4. Access your site at `main-{app}-{org}.light-cloud.io`

**Step 5: Custom Domain (Optional)**
1. Go to Environment → Domain tab
2. Enter your custom domain (e.g., `www.mysite.com`)
3. Add CNAME record pointing to your Light Cloud URL
4. SSL certificate is provisioned automatically

---

### Deploy a Backend API (Node.js, Python, Go)

**Step 1: Prepare Your Code**
Ensure your repository has one of:
- `package.json` with start script (Node.js)
- `requirements.txt` or `pyproject.toml` (Python)
- `go.mod` (Go)
- `Dockerfile` (custom)

**Step 2: Create Application**
1. Click "New Application"
2. Select repository
3. Choose "Container" deployment type
4. Configure:
   - Runtime: Auto-detected or select manually
   - Port: Your app's port (default 8080)
   - Memory: 512MB recommended for start
   - CPU: 1 vCPU

**Step 3: Environment Variables**
1. Go to Environment → Settings
2. Add required variables:
   ```
   DATABASE_URL=postgresql://...
   API_KEY=your-secret-key
   NODE_ENV=production
   ```
3. Variables are encrypted and injected at runtime

**Step 4: Deploy**
1. Click "Deploy"
2. Light Cloud builds Docker image automatically
3. Container starts and health check runs
4. API available at `main-{app}-{org}.light-cloud.io`

---

### Deploy Full-Stack Application (Frontend + Backend + Database)

**Architecture Example:**
```
Frontend (React)     → main-dashboard-myorg.light-cloud.io
Backend (Node.js)    → main-api-myorg.light-cloud.io
Database (PostgreSQL) → Managed, connection string provided
```

**Step 1: Create Database**
1. Go to Databases → "New Database"
2. Choose tier (Dev tier is great for starting)
3. Click "Create"
4. Wait for provisioning (~5 minutes)
5. Copy the connection string

**Step 2: Deploy Backend**
1. Create new application for your API
2. Select "Container" type
3. Add environment variable:
   ```
   DATABASE_URL=<paste connection string>
   ```
4. Deploy

**Step 3: Deploy Frontend**
1. Create new application for your frontend
2. Select "Static" type (or Container for SSR)
3. Add environment variable pointing to your API:
   ```
   VITE_API_URL=https://main-api-myorg.light-cloud.io
   ```
4. Deploy

**Step 4: Configure CORS (Backend)**
Update your backend to allow requests from frontend domain:
```javascript
// Node.js/Express example
app.use(cors({
  origin: 'https://main-dashboard-myorg.light-cloud.io'
}));
```

---

### Deploy Next.js Full-Stack (SSR + API Routes)

**Step 1: Check Configuration**
- If your app uses API routes (`/app/api/*` or `/pages/api/*`), it deploys as a container
- If using `output: 'export'` in `next.config.js`, it deploys as static

**Step 2: Create Application**
1. Click "New Application"
2. Select your Next.js repository
3. Light Cloud detects Next.js and deployment mode automatically
4. For SSR apps, container settings appear (memory, CPU)

**Step 3: Environment Variables**
Add your variables in Settings:
```
DATABASE_URL=postgresql://...
NEXTAUTH_SECRET=your-secret
NEXTAUTH_URL=https://main-myapp-myorg.light-cloud.io
```

**Step 4: Deploy**
1. Click "Deploy"
2. Next.js builds and starts
3. Both pages and API routes work at the same URL

---

### Branch Environments (Preview Deployments)

Light Cloud automatically creates preview environments for each branch:

**How It Works:**
1. Push a new branch: `git push origin feature/new-login`
2. Light Cloud auto-creates environment `feature-new-login-{app}-{org}.light-cloud.io`
3. Each push to the branch triggers a new deployment
4. When branch is deleted, environment is automatically cleaned up

**Settings (per application):**
| Setting | Default | Description |
|---------|---------|-------------|
| Auto-deploy on push | On | Deploy when code is pushed |
| Auto-create branch environments | On | Create environment for new branches |
| Auto-delete stale environments | On | Delete when branch is deleted |

**Note:** Production environments (main/master) are never auto-deleted.

---

### Connecting to Your Database

**From Container Applications:**
```javascript
// Node.js with Prisma
// .env
DATABASE_URL="postgresql://user:pass@host:5432/dbname"

// schema.prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}
```

```python
# Python with SQLAlchemy
import os
from sqlalchemy import create_engine

engine = create_engine(os.environ['DATABASE_URL'])
```

**From Local Development:**
1. Go to Database → Overview
2. Copy connection string
3. Whitelist your IP in Database → Settings
4. Connect with any PostgreSQL client

---

## Target Users

- Developers building side projects or MVPs without DevOps expertise
- Startups needing production infrastructure without dedicated DevOps teams
- Indie hackers and solopreneurs deploying full-stack applications
- Teams wanting Vercel-like experience with container and database support
- Anyone seeking simpler alternative to raw cloud providers

---

## Key Differentiators

1. **Full-stack platform**: Static sites + containers + databases in one place
2. **Scale-to-zero containers**: By default, unlike always-on alternatives
3. **Usage-based pricing**: Real cost visibility, no surprise bills
4. **GitHub-native**: Auto-deploy, branch environments, webhook integration
5. **Simpler than raw cloud**: More capable than static-only platforms

---

## Company

- **Website**: https://www.light-cloud.com
- **About**: https://www.light-cloud.com/about
- **Contact**: https://www.light-cloud.com/contact
- **Blog**: https://blog.light-cloud.com
- **Investors**: https://wefunder.com/light-cloud
- **Company**: Light Cloud, Inc., San Jose, California

## Legal

- **Privacy Policy**: https://www.light-cloud.com/legal/privacy-policy
- **Terms of Service**: https://www.light-cloud.com/legal/terms-of-service