ilumin-cli 1.0.0 → 1.1.0

package/skills/ilumin-cloud/references/compose.md

@@ -0,0 +1,425 @@
+# Ilumin Compose Formatter
+
+This skill defines the mandatory rules and patterns for writing `docker-compose.yml` files compatible with the Ilumin Cloud platform. Follow every rule — small mistakes like a fixed router name or a wrong network definition are the most common causes of deployment failures.
+
+---
+
+## How Ilumin's Infrastructure Works
+
+Understanding the infrastructure prevents 90% of errors:
+
+```
+[Internet] → [Traefik v3 on port 80/443] → [Docker containers via labels]
+                                                      ↑
+                                          Reads routing rules from labels
+                                          Handles SSL via Let's Encrypt
+                                          Routes by hostname or path
+```
+
+- Traefik runs as a separate container on the `traefik` **external** Docker network.
+- All app containers that need public access must join the `traefik` network.
+- Containers that must stay private (databases, caches) must join only the `internal` network.
+- Containers on the same `internal` network communicate using the **service name** as hostname (e.g., `postgres:5432`).
+
+---
+
+## Mandatory Formatting Rules
+
+### 1. No Comments
+Remove **all** comments (lines starting with `#`) from the final compose file.
+
+### 2. No Resource Limits
+Remove any `deploy`, `resources`, `limits`, or `reservations` sections — Ilumin manages these at the infrastructure level.
+
+### 3. Image Version Variable
+Replace the image tag of the **main application** with `${APP_VERSION}`.
+
+```yml
+# ❌ Wrong
+image: n8n:latest
+image: ghost:5.82.2
+image: myapp:v2.1.0
+
+# ✅ Correct
+image: n8n:${APP_VERSION}
+image: ghost:${APP_VERSION}
+image: myapp:${APP_VERSION}
+```
+
+> **Critical:** `APP_VERSION` replaces the **entire tag** after the colon, including any `v` prefix. Never write `v${APP_VERSION}`.
+
+### 4. Database Password Variable
+Replace **all** database passwords with `${DB_PASSWORD}`:
+
+```yml
+# Applies to: POSTGRES_PASSWORD, MYSQL_ROOT_PASSWORD, MYSQL_PASSWORD, MARIADB_ROOT_PASSWORD, etc.
+- POSTGRES_PASSWORD=${DB_PASSWORD}
+- MYSQL_ROOT_PASSWORD=${DB_PASSWORD}
+- MYSQL_PASSWORD=${DB_PASSWORD}
+```
+
+### 5. Optional Admin Credentials
+If the app supports initial admin setup, use these standard variables:
+- `${APP_USERNAME}` — admin username
+- `${APP_PASSWORD}` — admin password
+- `${APP_EMAIL}` — admin email
+
+### 6. No Backslashes in URLs
+Never use `\` before `$` in URLs inside the compose file.
+
+```yml
+# ❌ Wrong
+- APP_URL=https://\${BASE_DOMAIN}
+
+# ✅ Correct
+- APP_URL=https://${BASE_DOMAIN}
+```
+
+---
+
+## Network Rules (Critical)
+
+```yml
+# ✅ Main app service (public-facing) — both networks
+networks:
+  - traefik
+  - internal
+
+# ✅ Dependency services (db, redis, queue) — internal only
+networks:
+  - internal
+```
+
+**Always define networks at the bottom of the file exactly like this:**
+
+```yml
+networks:
+  traefik:
+    external: true
+  internal:
+```
+
+> ⚠️ The `traefik` network must be `external: true`. Forgetting this causes Traefik to be unable to discover the container.
+
+---
+
+## Traefik Labels (Critical)
+
+Every public-facing service needs these labels. **Copy this block exactly** and replace `<appname>` with a unique identifier for the app.
+
+```yml
+labels:
+  - traefik.enable=true
+  - traefik.docker.network=traefik
+  - traefik.http.routers.<appname>.rule=Host(`${BASE_DOMAIN}`)${CUSTOM_DOMAIN:+ || Host(`${CUSTOM_DOMAIN}`)}
+  - traefik.http.routers.<appname>.entrypoints=websecure
+  - traefik.http.routers.<appname>.tls=true
+  - traefik.http.routers.<appname>.tls.certresolver=letsencrypt
+  - traefik.http.services.<appname>.loadbalancer.server.port=<PORT>
+```
+
+### Router Naming Rules (Most Common Error)
+
+The router/service name in Traefik labels **must be unique across all apps on the server**. Using generic names like `backend` or `frontend` causes conflicts when multiple apps are deployed.
+
+**Formula:** `{appname}{role}` — always prefix with the app name.
+
+```yml
+# ❌ WRONG — will conflict with any other app using the same generic name
+- traefik.http.routers.backend.rule=...
+- traefik.http.routers.frontend.rule=...
+
+# ✅ CORRECT — unique per app
+- traefik.http.routers.n8nmain.rule=...
+- traefik.http.routers.ghostblog.rule=...
+- traefik.http.routers.myappfrontend.rule=...
+- traefik.http.routers.myappbackend.rule=...
+```
+
+### Domain Rule Syntax
+
+The domain rule must use this exact syntax — it supports both the Ilumin base domain and an optional custom domain:
+
+```
+Host(`${BASE_DOMAIN}`)${CUSTOM_DOMAIN:+ || Host(`${CUSTOM_DOMAIN}`)}
+```
+
+> **Why this syntax?** `${CUSTOM_DOMAIN:+ || Host(...)}` is a shell parameter expansion that only adds the custom domain rule if the variable is set. This allows the platform to manage domain routing dynamically without requiring a compose file change.
+
+---
+
+## Multi-Service Compose Rules
+
+### Two Services, One Domain (Path Routing — Frontend + Backend)
+
+When your app has a frontend and a backend on the **same domain**:
+
+```yml
+# Frontend: answers on /  (no path prefix needed)
+labels:
+  - traefik.http.routers.myappfrontend.rule=Host(`${BASE_DOMAIN}`)${CUSTOM_DOMAIN:+ || Host(`${CUSTOM_DOMAIN}`)}
+  - traefik.http.services.myappfrontend.loadbalancer.server.port=3000
+
+# Backend: answers on /api
+labels:
+  - traefik.http.routers.myappbackend.rule=(Host(`${BASE_DOMAIN}`)${CUSTOM_DOMAIN:+ || Host(`${CUSTOM_DOMAIN}`)}) && PathPrefix(`/api`)
+  - traefik.http.services.myappbackend.loadbalancer.server.port=8000
+```
+
+### Two Services, Two Subdomains
+
+When you need separate subdomains for backend and frontend:
+
+```yml
+# Frontend — base domain
+labels:
+  - traefik.http.routers.myappfrontend.rule=Host(`${BASE_DOMAIN}`)${CUSTOM_DOMAIN:+ || Host(`${CUSTOM_DOMAIN}`)}
+
+# Backend — api subdomain prefix
+labels:
+  - traefik.http.routers.myappbackend.rule=Host(`api.${BASE_DOMAIN}`)${CUSTOM_DOMAIN:+ || Host(`api.${CUSTOM_DOMAIN}`)}
+
+# Other services follow the same prefix pattern:
+# db.${BASE_DOMAIN}, admin.${BASE_DOMAIN}, etc.
+```
+
+---
+
+## HTTP → HTTPS Redirect (Optional but Recommended)
+
+To redirect HTTP traffic to HTTPS, add these labels alongside the main router:
+
+```yml
+labels:
+  # ... (main HTTPS router labels above) ...
+  
+  # HTTP redirect router
+  - traefik.http.routers.<appname>-http.rule=Host(`${BASE_DOMAIN}`)${CUSTOM_DOMAIN:+ || Host(`${CUSTOM_DOMAIN}`)}
+  - traefik.http.routers.<appname>-http.entrypoints=web
+  - traefik.http.routers.<appname>-http.middlewares=redirect-to-https
+  - traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https
+```
+
+---
+
+## Architecture Options
+
+### Option 1: Unified Build (Recommended) ✅
+
+Serve the compiled frontend through the backend. One container, no CORS issues.
+
+- Build the frontend in Stage 1 of the Dockerfile.
+- Copy `dist/` into the backend Stage 2.
+- Backend serves static files from `/` and API from `/api`.
+- Only one Traefik router needed.
+
+### Option 2: Separate Containers
+
+Use path routing or subdomains. Requires proper CORS config on the backend.
+
+> The browser **cannot** access `http://backend:8000` — the Docker internal network is not accessible from the user's browser. The frontend must call the public domain (e.g., `/api` relative path or `https://api.domain.com`).
+
+---
+
+## Common Errors and Fixes
+
+| Error | Cause | Fix |
+|---|---|---|
+| App unreachable (502 Bad Gateway) | Wrong port in `loadbalancer.server.port` | Set the port the container actually listens on |
+| App unreachable (no SSL / cert error) | Missing `tls=true` or `certresolver=letsencrypt` | Add both TLS labels |
+| Two apps conflict (first works, second doesn't) | Duplicate router names in Traefik labels | Use unique names: `{appname}{role}` |
+| Database not reachable from app | DB container not on `internal` network | Ensure both app and DB are on `internal` |
+| Traefik can't discover container | `traefik` network not set as `external: true` | Fix the network definition at the bottom |
+| URL contains `v${APP_VERSION}` | Manually adding `v` before the variable | Remove the `v` — `APP_VERSION` already includes it |
+| URL contains backslash `\$` | Escaping `$` in compose | Remove `\` — dollar signs don't need escaping in compose YAML |
+| Custom domain not working | `manage_domain` not called after install | Call `manage_domain` and configure CNAME at DNS provider |
+
+---
+
+## Reference Examples
+
+### Minimal Single App (Uptime Kuma)
+
+```yml
+services:
+  uptime-kuma:
+    image: louislam/uptime-kuma:${APP_VERSION}
+    volumes:
+      - uptime_data:/app/data
+    networks:
+      - traefik
+      - internal
+    labels:
+      - traefik.enable=true
+      - traefik.docker.network=traefik
+      - traefik.http.routers.uptimekuma.rule=Host(`${BASE_DOMAIN}`)${CUSTOM_DOMAIN:+ || Host(`${CUSTOM_DOMAIN}`)}
+      - traefik.http.routers.uptimekuma.entrypoints=websecure
+      - traefik.http.routers.uptimekuma.tls=true
+      - traefik.http.routers.uptimekuma.tls.certresolver=letsencrypt
+      - traefik.http.services.uptimekuma.loadbalancer.server.port=3001
+    restart: unless-stopped
+
+volumes:
+  uptime_data:
+
+networks:
+  traefik:
+    external: true
+  internal:
+```
+
+### App + Database (WordPress + MySQL)
+
+```yml
+services:
+  wordpress:
+    image: wordpress:${APP_VERSION}
+    depends_on:
+      - mysql
+    environment:
+      - WORDPRESS_DB_HOST=mysql
+      - WORDPRESS_DB_USER=wordpress
+      - WORDPRESS_DB_PASSWORD=${DB_PASSWORD}
+      - WORDPRESS_DB_NAME=wordpress
+    volumes:
+      - wordpress_data:/var/www/html
+    networks:
+      - traefik
+      - internal
+    labels:
+      - traefik.enable=true
+      - traefik.docker.network=traefik
+      - traefik.http.routers.wordpress.rule=Host(`${BASE_DOMAIN}`)${CUSTOM_DOMAIN:+ || Host(`${CUSTOM_DOMAIN}`)}
+      - traefik.http.routers.wordpress.entrypoints=websecure
+      - traefik.http.routers.wordpress.tls=true
+      - traefik.http.routers.wordpress.tls.certresolver=letsencrypt
+      - traefik.http.services.wordpress.loadbalancer.server.port=80
+    restart: unless-stopped
+
+  mysql:
+    image: mysql:5.7
+    environment:
+      - MYSQL_ROOT_PASSWORD=${DB_PASSWORD}
+      - MYSQL_DATABASE=wordpress
+      - MYSQL_USER=wordpress
+      - MYSQL_PASSWORD=${DB_PASSWORD}
+    volumes:
+      - mysql_data:/var/lib/mysql
+    networks:
+      - internal
+    restart: unless-stopped
+
+volumes:
+  wordpress_data:
+  mysql_data:
+
+networks:
+  traefik:
+    external: true
+  internal:
+```
+
+### App + Database (Baserow + PostgreSQL)
+
+```yml
+services:
+  baserow:
+    image: baserow/baserow:${APP_VERSION}
+    depends_on:
+      - postgres
+    volumes:
+      - baserow_data:/baserow/data
+    environment:
+      - BASEROW_PUBLIC_URL=https://${BASE_DOMAIN}
+      - DATABASE_HOST=postgres
+      - DATABASE_NAME=baserow
+      - DATABASE_USER=postgres
+      - DATABASE_PASSWORD=${DB_PASSWORD}
+    networks:
+      - traefik
+      - internal
+    labels:
+      - traefik.enable=true
+      - traefik.docker.network=traefik
+      - traefik.http.routers.baserow.rule=Host(`${BASE_DOMAIN}`)${CUSTOM_DOMAIN:+ || Host(`${CUSTOM_DOMAIN}`)}
+      - traefik.http.routers.baserow.entrypoints=websecure
+      - traefik.http.routers.baserow.tls=true
+      - traefik.http.routers.baserow.tls.certresolver=letsencrypt
+      - traefik.http.routers.baserow.service=baserow
+      - traefik.http.services.baserow.loadbalancer.server.port=80
+    restart: unless-stopped
+
+  postgres:
+    image: postgres:16
+    environment:
+      - POSTGRES_USER=postgres
+      - POSTGRES_PASSWORD=${DB_PASSWORD}
+      - POSTGRES_DB=baserow
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    networks:
+      - internal
+    restart: unless-stopped
+
+volumes:
+  baserow_data:
+  postgres_data:
+
+networks:
+  traefik:
+    external: true
+  internal:
+```
+
+### Custom App (Fixed Domain, No Variables)
+
+Used when the user wants to hardcode a specific domain. Inform the user that Ilumin's domain management panel will NOT work in this mode — they must manage DNS manually.
+
+```yml
+services:
+  app:
+    image: myapp:${APP_VERSION}
+    container_name: myapp
+    restart: unless-stopped
+    environment:
+      - NODE_ENV=production
+    networks:
+      - traefik
+      - internal
+    labels:
+      - traefik.enable=true
+      - traefik.docker.network=traefik
+      - traefik.http.routers.myapp.rule=Host(`app.mycompany.com`)
+      - traefik.http.routers.myapp.entrypoints=websecure
+      - traefik.http.routers.myapp.tls=true
+      - traefik.http.routers.myapp.tls.certresolver=letsencrypt
+      - traefik.http.routers.myapp-http.rule=Host(`app.mycompany.com`)
+      - traefik.http.routers.myapp-http.entrypoints=web
+      - traefik.http.routers.myapp-http.middlewares=redirect-to-https
+      - traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https
+      - traefik.http.services.myapp.loadbalancer.server.port=3000
+
+networks:
+  traefik:
+    external: true
+  internal:
+```
+
+---
+
+## Pre-Deploy Compose Checklist
+
+- [ ] All image versions replaced with `${APP_VERSION}` (no `v` prefix before the variable)
+- [ ] All database passwords replaced with `${DB_PASSWORD}`
+- [ ] No hardcoded secrets or credentials in the file
+- [ ] Main service is on both `traefik` and `internal` networks
+- [ ] Database/cache services are on `internal` network only
+- [ ] Network definitions at the bottom: `traefik` is `external: true`, `internal` has no extra config
+- [ ] Traefik router name is unique (format: `{appname}{role}`)
+- [ ] Domain rule uses exact syntax with `${BASE_DOMAIN}` and `${CUSTOM_DOMAIN:+ ...}` expansion
+- [ ] `loadbalancer.server.port` matches the actual port the container listens on
+- [ ] TLS labels present: `tls=true` + `tls.certresolver=letsencrypt`
+- [ ] No `\` backslashes before `$` in URLs
+- [ ] No comments (`#`) in the final file
+- [ ] No `deploy`, `resources`, `limits`, or `reservations` sections
+- [ ] All volumes declared in the `volumes:` section at the bottom

package/skills/ilumin-cloud/references/recommended-stack.md

@@ -0,0 +1,179 @@
+# Ilumin Recommended Stack
+
+When the user hasn't specified which infrastructure services to use, follow this recommended stack. These services are optimized for Ilumin Cloud — they are lightweight, self-hosted, and integrate well with each other via the `internal` Docker network.
+
+---
+
+## How Internal Communication Works
+
+All services in the same `docker-compose.yml` (or on the same `internal` Docker network) can communicate using the **service name as the hostname**.
+
+```
+App Container  →  [internal network]  →  postgres:5432
+App Container  →  [internal network]  →  redis:6379
+NocoDB         →  [internal network]  →  postgres:5432
+```
+
+> The key rule: **both the app and the service it connects to must share the same network** (always `internal`). The public internet never touches these internal services — only the main app container is exposed via Traefik.
+
+---
+
+## 1. 🗄️ Database: NocoDB + PostgreSQL
+
+**NocoDB** is the recommended database layer for Ilumin apps. It is a lightweight, self-hosted Airtable alternative that sits on top of PostgreSQL and exposes a full REST + GraphQL API, a visual UI, and programmatic table creation via API — no raw SQL required for most operations.
+
+### Why NocoDB?
+- Full REST API to read/write/create tables from any app or AI agent
+- Visual interface for non-developers to manage data
+- Integrates with webhooks, automations, and third-party tools
+- JWT-based API authentication via `NC_AUTH_JWT_SECRET`
+
+### Connecting Your App to NocoDB
+
+NocoDB exposes an HTTP API. Your app does **not** connect to NocoDB as a database directly — it makes API calls to NocoDB's REST endpoint.
+
+If your app is in the **same compose** or **same `internal` network**, use the internal hostname:
+
+```bash
+# Internal (same internal network) — preferred
+NOCODB_URL=http://nocodb:8080
+
+# External (different server or no shared network)
+NOCODB_URL=https://your-nocodb-domain.com
+```
+
+```python
+# Python example — connecting via internal network
+import httpx
+
+NOCODB_URL = os.getenv("NOCODB_URL", "http://nocodb:8080")
+NOCODB_API_KEY = os.getenv("NOCODB_API_KEY")  # = NC_AUTH_JWT_SECRET value
+
+headers = {
+    "xc-auth": NOCODB_API_KEY,
+    "Content-Type": "application/json"
+}
+
+# List records from a table
+response = httpx.get(f"{NOCODB_URL}/api/v1/db/data/noco/{{TABLE_ID}}/{{VIEW_ID}}", headers=headers)
+```
+
+### If NocoDB Is Already Installed
+
+Before installing a new NocoDB, check if one is already running on the server:
+
+1. Run `list_servers` to see installed apps.
+2. If NocoDB is already there, retrieve its `NC_AUTH_JWT_SECRET` env var — this is the API key your app uses to authenticate.
+3. Use the internal URL `http://nocodb:8080` if your app is in the same compose, or the public domain if separate.
+
+---
+
+## 2. ⚡ Cache & Sessions: Redis + RedisInsight
+
+**Redis** is the recommended solution for caching, session storage, and rate limiting. **RedisInsight** is the official Redis visual UI — install them together for observability.
+
+### Connecting Your App to Redis
+
+```bash
+# Internal connection string (same internal network)
+REDIS_URL=redis://redis:6379
+```
+
+```typescript
+// Node.js / TypeScript — ioredis
+import Redis from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL || 'redis://redis:6379');
+
+// Cache example
+await redis.set('key', 'value', 'EX', 3600); // expires in 1 hour
+const value = await redis.get('key');
+```
+
+```python
+# Python — redis-py
+import redis
+import os
+
+r = redis.from_url(os.getenv("REDIS_URL", "redis://redis:6379"))
+
+r.set("key", "value", ex=3600)
+value = r.get("key")
+```
+
+> **Network rule:** Redis is on `internal` only — it is **never** exposed publicly. RedisInsight (the UI) is on `traefik + internal` so it can be accessed via browser. Your app connects to `redis:6379` on the `internal` network.
+
+---
+
+## 3. 🔄 Job Queues: BullMQ (uses Redis)
+
+**BullMQ** is the recommended job queue solution. It uses Redis as its backend — so if Redis is already installed (from item 2), BullMQ is ready to use with no extra infrastructure.
+
+**BullMQ is a library, not a separate service.** It runs inside your application code.
+
+### When to use BullMQ
+- Sending emails asynchronously
+- Processing uploaded files or images
+- Scheduling recurring tasks (cron-like)
+- Handling webhooks with retry logic
+- Any long-running task that shouldn't block an HTTP response
+
+### BullMQ Integration (Node.js / TypeScript)
+
+```typescript
+import { Queue, Worker } from 'bullmq';
+import IORedis from 'ioredis';
+
+const connection = new IORedis(process.env.REDIS_URL || 'redis://redis:6379', {
+  maxRetriesPerRequest: null, // required for BullMQ
+});
+
+// --- Producer (add jobs to the queue) ---
+const emailQueue = new Queue('emails', { connection });
+
+await emailQueue.add('send-welcome', {
+  to: 'user@example.com',
+  subject: 'Welcome!',
+});
+
+// --- Worker (process jobs from the queue) ---
+const worker = new Worker('emails', async (job) => {
+  const { to, subject } = job.data;
+  await sendEmail(to, subject); // your email logic
+}, { connection });
+
+worker.on('completed', (job) => console.log(`Job ${job.id} completed`));
+worker.on('failed', (job, err) => console.error(`Job ${job?.id} failed:`, err));
+```
+
+### BullMQ Integration (Python — with rq or celery as alternatives)
+
+> BullMQ is Node.js-native. For Python apps, use **Celery + Redis** or **rq + Redis** instead — same Redis instance, same connection string.
+
+```python
+# Python — Celery with Redis broker
+from celery import Celery
+
+app = Celery('tasks', broker=os.getenv('REDIS_URL', 'redis://redis:6379/0'))
+
+@app.task
+def send_email(to: str, subject: str):
+    # your email logic
+    pass
+
+# Calling the task (async)
+send_email.delay('user@example.com', 'Welcome!')
+```
+
+---
+
+## Decision Guide
+
+| Need | Recommended Solution |
+|---|---|
+| Store and query structured data | NocoDB + PostgreSQL |
+| Cache API responses, store sessions | Redis |
+| Background jobs, async tasks, retries | BullMQ (Node.js) / Celery (Python) — both use Redis |
+| Visual database management | NocoDB UI (built-in) |
+| Visual Redis inspection | RedisInsight |
+| All of the above | Full stack compose above |