AI-Optimized Guide

AI Integration Guide

This guide is specifically designed for AI models (Claude, GPT, and others) to understand how to deploy applications on the Rouic Platform. The instructions are structured for autonomous execution.

CONTEXT FOR AI MODELS

Platform: Rouic Platform — a self-hosted PaaS at system.rouic.com

API Base: $https://system.rouic.com/api/v1

Auth: Bearer token with "rk_" prefix in the Authorization header

Deploy flow: Create project → Set env vars → Trigger deploy → Poll status

OpenAPI spec: $https://system.rouic.com/api/v1/openapi.json

Deployment method: Git clone → Docker build → Blue-green deploy

Complete Deployment Workflow

Follow these steps in order to deploy an application. Each step includes the exact HTTP request to make.

1. Authenticate

→

2. Create/Select Project

→

3. Set Env Vars

→

4. Trigger Deploy

→

5. Monitor Status

Step 1: Authenticate

You need a Bearer token to authenticate all API requests. The token must have the deploy scope at minimum. The user provides this token.

Test authentication

bash

curl -s -o /dev/null -w "%{http_code}" \
  https://system.rouic.com/api/v1/projects \
  -H "Authorization: Bearer rk_YOUR_TOKEN"

# Expected: 200 (authenticated)
# If 401: token is invalid or expired

Token format

Prefix: rk_
Full example: rk_a1b2c3d4e5f6g7h8i9j0
Header: Authorization: Bearer rk_...

Step 2: Create or Select a Project

Option A: List existing projects

curl https://system.rouic.com/api/v1/projects \
  -H "Authorization: Bearer rk_YOUR_TOKEN"

# Response: array of project objects
# Find the project by slug to deploy to it

Option B: Create a new project

curl -X POST https://system.rouic.com/api/v1/projects \
  -H "Authorization: Bearer rk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "slug": "my-app",
    "gitUrl": "https://github.com/user/repo.git",
    "gitBranch": "main"
  }'

# Response: project object with id and slug
# Use the slug in subsequent deploy requests

Required fields for new projects

name (string, required): Human-readable name
slug (string, required): URL-safe identifier. Lowercase, alphanumeric, hyphens only.
gitUrl (string, optional but needed for deploy): Full Git clone URL
gitBranch (string, optional): Default branch, defaults to "main"

Option C: Get a specific project by slug

curl https://system.rouic.com/api/v1/projects/my-app \
  -H "Authorization: Bearer rk_YOUR_TOKEN"

# Response: detailed project info with services and deployments

Step 3: Set Environment Variables

Environment variables can be set as part of the deploy request (Step 4). They are upserted: existing keys are updated, new keys are created. Variables are encrypted at rest.

There is no separate endpoint for env vars. Include them in the env field of the deploy request. They will persist across future deployments.

Common env vars to set

json

{
  "env": {
    "NODE_ENV": "production",
    "DATABASE_URL": "postgresql://user:pass@container:5432/db",
    "REDIS_URL": "redis://container:6379",
    "SECRET_KEY": "your-secret-key",
    "S3_ACCESS_KEY": "minio-access-key",
    "S3_SECRET_KEY": "minio-secret-key",
    "S3_ENDPOINT": "https://s3.rouic.com"
  }
}

Step 4: Trigger Deployment

Deploy request

bash

curl -X POST https://system.rouic.com/api/v1/deploy \
  -H "Authorization: Bearer rk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-app",
    "ref": "main",
    "env": {
      "NODE_ENV": "production"
    }
  }'

Expected response (HTTP 202)

json

{
  "message": "Deployment started",
  "deployments": [
    {
      "deploymentId": "dep_abc123def456",
      "serviceName": "web",
      "url": "https://my-app.rouic.com"
    }
  ]
}

Deploy request fields

project (string, required): Project slug
ref (string, optional): Git branch, tag, or commit SHA. Defaults to project's configured branch.
services (string[], optional): Specific services to deploy. Omit to deploy all services.
env (object, optional): Key-value pairs of environment variables to upsert before deploying.

Important: The deploy endpoint returns 202 Accepted. The deployment runs asynchronously. You must poll the deployment status to know when it completes.

Step 5: Monitor Deployment Status

After triggering a deploy, use the deployment ID from the response to poll the status.

Poll deployment status

bash

curl https://system.rouic.com/api/v1/deployments/dep_abc123def456 \
  -H "Authorization: Bearer rk_YOUR_TOKEN"

Status values and their meaning

pendingDeployment created, waiting to start. Action: wait and re-poll.

buildingDocker image is being built. Action: wait and re-poll.

deployingImage built, performing blue-green deploy. Action: wait and re-poll.

runningDeployment succeeded. Container is live. Action: deployment complete. The URL field contains the live URL.

failedDeployment failed. Action: read buildLog for error details. Fix and re-deploy.

stoppedDeployment was manually stopped. Action: re-deploy if needed.

Polling strategy

Polling loop (bash)

bash

DEPLOY_ID="dep_abc123def456"
TOKEN="rk_YOUR_TOKEN"

while true; do
  STATUS=$(curl -s \
    https://system.rouic.com/api/v1/deployments/$DEPLOY_ID \
    -H "Authorization: Bearer $TOKEN" | jq -r '.status')

  echo "Status: $STATUS"

  case $STATUS in
    running)
      echo "Deployment successful!"
      break
      ;;
    failed)
      echo "Deployment failed. Check build logs."
      break
      ;;
    stopped)
      echo "Deployment stopped."
      break
      ;;
    *)
      # pending, building, deploying
      sleep 10
      ;;
  esac
done

Recommended poll interval: 10 seconds. A typical build + deploy takes 30 seconds to 5 minutes depending on project size.

Common Deployment Scenarios

Scenario 1: Deploy a Next.js App

Prerequisites: Repository has a Dockerfile, next.config uses output: 'standalone'.

Full workflow

bash

# 1. Create project (skip if exists)
curl -X POST https://system.rouic.com/api/v1/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Next App",
    "slug": "my-next-app",
    "gitUrl": "https://github.com/user/my-next-app.git",
    "gitBranch": "main"
  }'

# 2. Deploy with env vars
curl -X POST https://system.rouic.com/api/v1/deploy \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-next-app",
    "ref": "main",
    "env": {
      "DATABASE_URL": "postgresql://postgres:pass@mydb:5432/app",
      "NEXTAUTH_SECRET": "random-secret-string",
      "NEXTAUTH_URL": "https://my-next-app.rouic.com"
    }
  }'

# 3. Save the deploymentId from the response and poll
curl https://system.rouic.com/api/v1/deployments/DEPLOYMENT_ID \
  -H "Authorization: Bearer $TOKEN"

Scenario 2: Deploy an Express API

# Deploy an Express API listening on port 3000
curl -X POST https://system.rouic.com/api/v1/deploy \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-api",
    "ref": "main",
    "env": {
      "PORT": "3000",
      "DATABASE_URL": "postgresql://postgres:pass@myapi-db:5432/api",
      "JWT_SECRET": "your-jwt-secret",
      "CORS_ORIGIN": "https://my-frontend.rouic.com"
    }
  }'

Scenario 3: Deploy a Monorepo

A monorepo with "web" and "api" services. Each has its own Dockerfile in a subdirectory.

# Deploy all services
curl -X POST https://system.rouic.com/api/v1/deploy \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-monorepo",
    "ref": "main"
  }'

# Or deploy only the frontend
curl -X POST https://system.rouic.com/api/v1/deploy \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-monorepo",
    "ref": "main",
    "services": ["web"]
  }'

# Response will contain one deploymentId per service

Scenario 4: Deploy with a Database

Databases are created via the dashboard (not currently available via API). Once created, connect from your app using the container name as the hostname.

# Assuming you created a PostgreSQL database named "myapp-db" via the dashboard:

curl -X POST https://system.rouic.com/api/v1/deploy \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-app",
    "ref": "main",
    "env": {
      "DATABASE_URL": "postgresql://postgres:YOUR_DB_PASSWORD@myapp-db:5432/myapp"
    }
  }'

# The app connects to the database over the internal Docker network.
# No external port exposure needed.

Scenario 5: Deploy with Object Storage

# Assuming you created a storage bucket via the dashboard:

curl -X POST https://system.rouic.com/api/v1/deploy \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-app",
    "ref": "main",
    "env": {
      "S3_ENDPOINT": "https://s3.rouic.com",
      "S3_ACCESS_KEY": "your-minio-access-key",
      "S3_SECRET_KEY": "your-minio-secret-key",
      "S3_BUCKET": "my-uploads",
      "S3_REGION": "us-east-1"
    }
  }'

Error Handling

When the API returns an error, the response body contains a JSON object with an error field.

401"Invalid or expired token"

Resolution: Check that the token is correct and has not expired. Get a new token from the dashboard.

400"Project slug is required"

Resolution: Include the "project" field in the deploy request body.

404"Project not found"

Resolution: The slug doesn't match any project, or the token's user doesn't own it. List projects first to verify the slug.

400"Project has no git URL configured"

Resolution: The project needs a gitUrl before it can be deployed. Update it via the dashboard or recreate with a gitUrl.

400"No services configured for this project"

Resolution: Add at least one service to the project via the dashboard. A service defines the Dockerfile, port, and subdomain.

404"None of the specified services were found"

Resolution: The service names in the "services" array don't match any configured services. Check service names via GET /v1/projects/{slug}.

Build failures

If a deployment reaches the failed status, check the buildLog field in the deployment details for the error. Common causes:

Dockerfile not found: Verify the Dockerfile path in the service configuration.
Build errors: Syntax errors, missing dependencies, or failing build scripts.
Health check failed: The container started but didn't respond to the health check endpoint in time.
Port mismatch: The app is listening on a different port than configured in the service.

OpenAPI Spec

The full machine-readable API specification is available in OpenAPI 3.0.3 format:

Fetch the OpenAPI spec

bash

curl https://system.rouic.com/api/v1/openapi.json

This spec can be used to generate client SDKs, import into API testing tools, or used by AI models for tool-calling capabilities.

QUICK REFERENCE FOR AI MODELS

List projects

GET $https://system.rouic.com/api/v1/projects

Create project

POST $https://system.rouic.com/api/v1/projects

Body: { "name", "slug", "gitUrl", "gitBranch" }

Get project details

GET $https://system.rouic.com/api/v1/projects/{slug}

Trigger deployment

POST $https://system.rouic.com/api/v1/deploy

Body: { "project" (required), "ref", "services", "env" }

Check deployment status

GET $https://system.rouic.com/api/v1/deployments/{id}

Full API docs

API Reference →

Getting started

Documentation Home