olares-dev

name	olares-dev
description	MUST USE when user asks to develop/create/build any application. Triggers: 开发/制作/创建/做一个/写一个/帮我做/帮我开发/build/create/make/develop/implement/code an app
license	MIT

Olares Development Skill

Standards for developing and deploying applications on the Olares platform.

---

⛔ Four Iron Rules (Violation = Failure)

When executing any development task, you MUST follow these rules:

#	Rule	Correct Approach	Violation (= You Failed)
1	After dev → Ask to publish	Response must end with publish prompt (see template below)	Omit publish prompt, end with "let me know if you have questions"
2	Database → PostgreSQL + schema	Use PostgreSQL with dedicated schema per app (not public)	Ask which DB, use public schema, recommend SQLite
3	Directory → Fixed location	Put project in /root/workspace/<app-name>/	Ask user where to put the project
4	API paths → Relative paths	Frontend API requests use relative paths or dynamic basePath	Use absolute paths like /api/xxx

Publish Prompt Template (Rule 1)

After development is complete, your response MUST end with this format:

---
## ✅ Development Complete!

📁 Project location: `/root/workspace/<app-name>/`

**Deploy to Olares?** Reply "publish" for one-click deployment.

PostgreSQL + Schema Isolation (Rule 2)

Each app MUST use its own schema. NEVER use the public schema.

import os
import psycopg2

# Create dedicated schema for this app
APP_NAME = "todo-app"
SCHEMA = APP_NAME.replace('-', '_')  # todo_app

def get_db():
    conn = psycopg2.connect(
        host=os.environ.get('DB_HOST'),
        port=os.environ.get('DB_PORT', '5432'),
        user=os.environ.get('DB_USER'),
        password=os.environ.get('DB_PASSWORD'),
        database=os.environ.get('DB_DATABASE'),
        options=f'-c search_path={SCHEMA}'  # Use dedicated schema
    )
    return conn

def init_db():
    conn = psycopg2.connect(...)  # Without options first
    cur = conn.cursor()
    cur.execute(f'CREATE SCHEMA IF NOT EXISTS {SCHEMA}')
    cur.execute(f'SET search_path TO {SCHEMA}')
    cur.execute('''
        CREATE TABLE IF NOT EXISTS todos (
            id SERIAL PRIMARY KEY,
            title TEXT NOT NULL,
            completed BOOLEAN DEFAULT FALSE
        )
    ''')
    conn.commit()
    conn.close()

API Path Handling (Rule 4) ⚠️ CRITICAL

Apps are deployed at /{app-name}/ subpath, NOT at root /.

Development vs Production:

Development:  http://localhost:8080/api/words     ← Works
Production:   https://domain.com/api/words       ← 404! Wrong!
              https://domain.com/ielts-vocab/api/words  ← Correct

Frontend MUST use dynamic basePath. Copy this pattern:

// ========================================
// MANDATORY: Put this at the TOP of your JS file
// ========================================
const BASE_PATH = (() => {
    const path = window.location.pathname;
    // Remove trailing filename if present (e.g., /app/index.html -> /app/)
    const dir = path.substring(0, path.lastIndexOf('/') + 1);
    return dir || '/';
})();

// ========================================
// All API calls MUST use BASE_PATH
// ========================================
// ❌ WRONG - will break in production
fetch('/api/words')
axios.get('/api/users')

// ✅ CORRECT - works everywhere
fetch(BASE_PATH + 'api/words')
fetch(`${BASE_PATH}api/users`)

// ========================================
// For static resources in HTML, use relative paths
// ========================================
// ❌ WRONG
// <link href="/static/style.css">
// <script src="/static/app.js">

// ✅ CORRECT (no leading slash = relative to current path)
// <link href="static/style.css">
// <script src="static/app.js">

Framework-Specific Solutions

Vue (Vite):

// vite.config.js - set base to './' for relative paths
export default defineConfig({
  base: './',  // Makes all assets relative
})

// In components, use import.meta.env.BASE_URL or relative fetch
fetch(import.meta.env.BASE_URL + 'api/words')

React (Create React App):

// package.json - add homepage
{ "homepage": "." }

// In components, use process.env.PUBLIC_URL or relative fetch
fetch(process.env.PUBLIC_URL + '/api/words')

// Or use runtime detection (works without build config)
const BASE = window.location.pathname.replace(/\/[^/]*$/, '/');
fetch(BASE + 'api/words')

Vue/React (Runtime detection - RECOMMENDED):

// Works with ANY framework, no build config needed
// Put in a shared utils file
export const getBasePath = () => {
  const path = window.location.pathname;
  return path.substring(0, path.lastIndexOf('/') + 1) || '/';
};

// Usage
import { getBasePath } from './utils';
fetch(getBasePath() + 'api/words');

Pure HTML/JS (No framework): Use the BASE_PATH pattern shown above.

Why this matters: Your app works at localhost:8080/ during development, but deploys to domain.com/{app-name}/. Absolute paths break.

---

🎯 Trigger Keywords

Development Triggers (loads this skill)

• Chinese: 制作 / 开发 / 创建 / 做一个 / 写一个 / 帮我做 / 帮我写 / 帮我开发 / 实现 / 编写
• English: build / create / make / develop / help me build / help me create / implement / code

Publish Triggers (executes deployment)

When user says these, immediately execute deployment:

• 发布 / publish / 好 / 可以 / OK / yes / 确认 / go / 上线 / deploy / ship it / release

---

📐 Development Workflow

User requests development
    ↓
Create project: /root/workspace/<app-name>/  ← Don't ask for directory
    ↓
Need database? → Use PostgreSQL directly  ← Don't ask for choice
    ↓
Write complete runnable code
    ↓
End response with publish prompt  ← Required!
    ↓
User confirms → Execute deployment

---

🚀 Deployment Commands

# Format
/root/.local/bin/olares-deploy <app-name> <image> <port> [startup-command]

# Example
/root/.local/bin/olares-deploy todo-app python:3.11-slim 8080 "pip install -r requirements.txt && python app.py"

# Note: Nginx is auto-configured after deployment (no manual step needed)

Deployment Mechanism (ConfigMap)

• Code is packaged into a Kubernetes ConfigMap (limit: 1MB)
• Works across all nodes (no hostPath dependency)
• To update code after changes: re-run the deploy command
• Keep app directory small: exclude node_modules/, .git/, __pycache__/, etc.

Post-Deployment Response Template

✅ Deployment successful!

🌐 Access URL: https://8cf849020.{username}.olares.com/{app-name}/
📁 Code directory: /root/workspace/{app-name}/

Management commands:
• View logs: /root/.local/bin/olares-manage logs {app-name}
• View status: /root/.local/bin/olares-manage info {app-name}
• Delete app: /root/.local/bin/olares-manage delete {app-name}

---

🛠️ Management Commands

/root/.local/bin/olares-manage list              # List all apps
/root/.local/bin/olares-manage info <app-name>   # Show app details
/root/.local/bin/olares-manage logs <app-name>   # View logs
/root/.local/bin/olares-manage delete <app-name> # Delete app
/root/.local/bin/olares-urls                     # Show all URLs

---

🌐 Network Architecture

Browser → https://8cf849020.{username}.olares.com/{app-name}/
    ↓
Olares Ingress → OpenCode Container:3000 (Nginx)
    ↓
    ├─ /           → localhost:4096 (OpenCode Server)
    └─ /{app-name}/ → {app-name}-svc:{port}

---

🔧 Troubleshooting

Issue	Cause	Solution
502 Bad Gateway	Pod not running	/root/.local/bin/olares-manage logs <app-name>
404 Not Found	Nginx not configured	python3 /root/.local/bin/olares-nginx-config
Database connection failed	Env vars not set	Check OlaresManifest.yaml
App directory too large	ConfigMap limit 1MB	Remove node_modules, .git, pycache etc.
Code changes not reflected	Need to redeploy	Re-run /root/.local/bin/olares-deploy to update ConfigMap

---

📚 Reference Documentation

Document	Content
docs/database-reference.md	PostgreSQL detailed usage
docs/deployment-reference.md	Deployment commands and network architecture
docs/helm-reference.md	Helm Chart packaging format
docs/github-submission.md	Market submission process

---

✅ Example: Correct Development Response

Alright, I'll create a todo app for you.

[Creating /root/workspace/todo-app/app.py]
[Creating /root/workspace/todo-app/requirements.txt]
[Creating /root/workspace/todo-app/static/index.html]

App created and tested:
- Backend: Flask + PostgreSQL
- Frontend: Clean HTML/CSS/JS
- API: GET/POST/DELETE /api/todos

---
## ✅ Development Complete!

📁 Project location: `/root/workspace/todo-app/`

**Deploy to Olares?** Reply "publish" for one-click deployment.

❌ Example: Wrong Development Response

First, which database would you like? PostgreSQL, MySQL, or SQLite?  ← Violates Rule 2
CREATE TABLE todos (...)  ← Violates Rule 2 (no schema, uses public by default)
Where would you like to put the project?  ← Violates Rule 3
App created! Let me know if you have questions.  ← Violates Rule 1
fetch('/api/todos')  ← Violates Rule 4 (should use relative path)

---

⚠️ Pre-Send Checklist (MANDATORY)

Before sending ANY development response, you MUST verify:

Check	Rule	If Failed
✅ Response ends with "Deploy to Olares?" prompt	Rule 1	STOP. Add the publish prompt before sending.
✅ Database uses dedicated schema (not public)	Rule 2	Fix the code to use app-specific schema
✅ Project in /root/workspace/<app-name>/	Rule 3	Move files to correct location
✅ Frontend uses relative API paths	Rule 4	Fix fetch() calls to use basePath

If ANY check fails, your response is INCOMPLETE. Fix it before sending.