Overview

UGA HOST is the deployment engine inside QSSN PaaS. It covers two distinct hosting surfaces:

Every project — backend or frontend — gets a live URL under gss-tec.com, automatic HTTPS, and access to the full management dashboard at qssn-cloud-manager.pages.dev.

Installation

Install the UGA HOST CLI globally via npm:

npm install -g ugahost@latest

Verify the installation:

ugahost --version

The CLI is open source. View the source code, report issues, or contribute on GitHub:

github.com/GSS-creator/UGA-HOST

Authentication

UGA HOST uses a two-layer authentication model. Your account is tied to GitHub OAuth — that is how you sign in to the dashboard. Your CLI and API access is controlled by a personal API key that you generate from the dashboard and paste into ugahost login.

GitHub OAuth Flow

Every UGA HOST account is backed by a GitHub identity. There is no username/password registration — GitHub is the only sign-in method.

Full flow

Emails sent during account lifecycle

API Keys

API keys are what authenticate the CLI and any direct HTTP calls you make to the platform API. They are separate from your JWT session token.

Format

Every API key is prefixed with ugahost_ followed by 64 hex characters (32 random bytes):

ugahost_a3f8c2e1d4b7a9f0e2c4d6b8a1f3e5d7c9b2a4e6f8d0b2c4a6e8f0d2b4c6a8

How to create an API key

Key validation on every request

Every CLI command sends Authorization: Bearer ugahost_…. The platform middleware:

1. Detects the ugahost_ prefix and routes to APIKeyManager.validateAPIKey()
2. Queries api_keys WHERE api_key = ? AND is_active = 1
3. Checks expires_at — rejects if the current time is past expiry
4. Updates last_used_at = datetime('now') on the matched row
5. Returns the developer_id and email so the rest of the request proceeds as that developer

Revoking a key

In the dashboard go to Settings → API Keys, find the key row, and click Revoke. This sets is_active = 0 — the key stops working immediately on the next request. A revocation email is sent to your account. The row is kept in the database (soft-delete) so audit history is preserved. Use Delete to remove it permanently.

CLI Login — ugahost login

Run ugahost login to authenticate the CLI. It prompts for your email and API key, validates them against the platform, and saves the credentials locally:

ugahost login

# Prompts:
#   Email:    you@example.com
#   API Key:  ****************  (input masked)

What happens under the hood

{
  "email":  "you@example.com",
  "apiKey": "ugahost_a3f8c2…",
  "apiUrl": "https://qssn-paas-management.gastonsoftwaresolutions234.workers.dev"
}

ugahost init

Run ugahost init inside your project directory. It will interactively ask:

This writes a ugahost.json file to your project directory:

{
  "name": "my-api",
  "subdomain": "my-api",
  "language": "nodejs",
  "port": 3000,
  "pythonMode": "standard"
}

After the first deploy, a projectId field is added automatically. This ID is used for all subsequent redeploys and API operations.

Deploy Flow

Running ugahost deploy executes this pipeline:

The CLI distinguishes between a first deploy and a redeploy:

Deploying a Node.js App

UGA HOST Node.js projects run as Cloudflare Workers — a V8-isolate environment, not a Node.js process. Two coding styles are supported:

Style 1 — Native Cloudflare Worker Recommended

Write a standard export default { fetch(request, env) {} } module. The env object automatically contains all your environment variables (including Turso credentials) as Cloudflare plain-text bindings.

export default {
  async fetch(request, env) {
    const url = new URL(request.url);

    // env.TURSO_DATABASE_URL and env.TURSO_AUTH_TOKEN are injected automatically
    if (url.pathname === '/') {
      return new Response('Hello from UGA HOST!');
    }

    return new Response('Not found', { status: 404 });
  }
};

Style 2 — Express-compatible (polyfilled)

Standard Express apps also work. The platform injects a require() polyfill that intercepts require('express'), require('cors'), and require('dotenv'). Remove app.listen() — it is stripped automatically by the CLI before upload.

const express = require('express');
const app = express();
app.use(express.json());

app.get('/', (req, res) => {
  res.json({ status: 'ok' });
});

// DO NOT call app.listen() — stripped by the CLI
// Access env vars via process.env.MY_VAR

Entry file

The CLI always reads index.js from the current directory. No other entry point is supported for Node.js.

Deploying a Python App

Python projects run as isolated containers managed by the UGA HOST Python Runtime. The container starts on the first request and stays warm as long as it receives traffic.

Entry file

The CLI reads app.py from the current directory.

Standard mode (default) Recommended

Start a regular HTTP server. The platform routes HTTP traffic to the port specified in PORT environment variable.

from flask import Flask, jsonify
import os

app = Flask(__name__)

@app.route('/')
def index():
    return jsonify({ 'status': 'ok' })

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=int(os.environ['PORT']))

Supported frameworks

Dependencies — requirements.txt

Place a requirements.txt file in the same directory. It is uploaded alongside app.py and installed into the container automatically.

flask==3.0.3
requests==2.32.3
libsql-client==0.3.1

Health check after deploy

After uploading, the CLI calls GET /runtime-health to verify the container started. Cold-start timeouts (503) are non-fatal — the deploy is still considered successful and the container will start on the first real request.

Redeploying

Once ugahost.json contains a projectId, every subsequent ugahost deploy is a redeploy. The platform:

• Reads all saved environment variables from the database
• Re-injects Turso credentials (TURSO_DATABASE_URL, TURSO_AUTH_TOKEN) from the project record
• Deploys the new code with the full env set intact
• Updates last_deployed_at and caches the code snapshot for future env-change redeploys

Python Pre-deploy Validation

Before any Python code reaches the platform, the CLI runs a local validation pass. If any check fails, the deploy is aborted with a descriptive error message — no code is uploaded.

Check pipeline

All validation rules

Node.js Pre-deploy Processing

Node.js code is not validated as strictly as Python, but the CLI applies two transformations before upload:

1. app.listen() removal

Any app.listen(...) call (including multi-line callback blocks) is stripped from the code. Workers do not have a listening port — the platform handles all routing.

2. Export injection

If the code contains none of export default, module.exports, or globalThis.app, the following is appended automatically:

// Export for UGA HOST
globalThis.app = app;

If your code already has export default { fetch(...) }, no injection occurs and the native Worker entry point is used as-is.

Turso Database — Auto Provisioning

Every project gets a dedicated Turso (libSQL / SQLite) database provisioned automatically on first deploy. You never need to create one manually.

What happens on first deploy

Credentials available in your app

Accessing the Database in Your App

Node.js — native Worker (recommended)

Use the Turso HTTP API directly. The credentials are already on env:

async function query(env, sql, args = []) {
  const url = env.TURSO_DATABASE_URL
    .replace('libsql://', 'https://') + '/v2/pipeline';
  const res = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${env.TURSO_AUTH_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      requests: [
        { type: 'execute', stmt: { sql, args: args.map(v => ({ type: 'text', value: String(v) })) } },
        { type: 'close' }
      ]
    })
  });
  const data = await res.json();
  return data.results?.[0];
}

Python — using libsql-client

import os, libsql_client

client = libsql_client.create_client_sync(
    url=os.environ['TURSO_DATABASE_URL'],
    auth_token=os.environ['TURSO_AUTH_TOKEN']
)

rows = client.execute("SELECT * FROM users").rows

Schema initialization pattern

Because Workers and containers cold-start, the recommended pattern is to run CREATE TABLE IF NOT EXISTS on every startup:

async function initDb(env) {
  await query(env, `CREATE TABLE IF NOT EXISTS users (
    id            INTEGER PRIMARY KEY AUTOINCREMENT,
    username      TEXT    NOT NULL UNIQUE,
    created_at    TEXT    NOT NULL DEFAULT (datetime('now'))
  )`);
}

Database CLI Commands

The ugahost db subcommand gives you full database access from the terminal. All commands must be run from a directory containing a deployed ugahost.json.

Quick examples

# Create a table with a single SQL statement
ugahost db query "CREATE TABLE posts (id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, body TEXT)"

# Insert a row
ugahost db insert posts '{"title":"Hello","body":"World"}'

# SELECT with a filter (JSON key=value)
ugahost db find posts '{"title":"Hello"}'

# Raw SQL with JOIN
ugahost db query "SELECT u.username, COUNT(p.id) as posts FROM users u LEFT JOIN posts p ON p.user_id = u.id GROUP BY u.id"

Migrations — ugahost db migrate

ugahost db migrate <file> runs a script of SQL statements (or a structured JSON migration) against your live Turso database. Every statement is executed individually, with a real-time progress line printed for each one — so you can see exactly which step succeeded or failed.

How it works

SQL migration file (.sql) Most common

Create a plain .sql file with one or more statements separated by ;:

-- migrations/001_init.sql
-- Creates the core schema for the auth API

CREATE TABLE IF NOT EXISTS users (
  id            INTEGER  PRIMARY KEY AUTOINCREMENT,
  username      TEXT     NOT NULL UNIQUE,
  email         TEXT     UNIQUE,
  salt          TEXT     NOT NULL,
  password_hash TEXT     NOT NULL,
  role          TEXT     NOT NULL DEFAULT 'user',
  created_at    TEXT     NOT NULL DEFAULT (datetime('now'))
);

CREATE TABLE IF NOT EXISTS sessions (
  id         INTEGER  PRIMARY KEY AUTOINCREMENT,
  token      TEXT     NOT NULL UNIQUE,
  user_id    INTEGER  NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  created_at TEXT     NOT NULL DEFAULT (datetime('now')),
  expires_at TEXT
);

CREATE INDEX IF NOT EXISTS idx_sessions_token  ON sessions(token);
CREATE INDEX IF NOT EXISTS idx_users_username  ON users(username);
CREATE INDEX IF NOT EXISTS idx_users_email     ON users(email)

Run it:

ugahost db migrate ./migrations/001_init.sql

Terminal output:

🔄 Running migration: 001_init.sql
   5 statement(s)

  ✅ [1/5] CREATE TABLE IF NOT EXISTS users ( id INTEGER PRIMARY KEY…
  ✅ [2/5] CREATE TABLE IF NOT EXISTS sessions ( id INTEGER PRIMARY K…
  ✅ [3/5] CREATE INDEX IF NOT EXISTS idx_sessions_token ON sessions(…
  ✅ [4/5] CREATE INDEX IF NOT EXISTS idx_users_username ON users(use…
  ✅ [5/5] CREATE INDEX IF NOT EXISTS idx_users_email ON users(email)

✅ Migration complete: 5/5 succeeded

Seed data in the same file

You can mix DDL (schema) and DML (data) in one file. Statements run in order:

-- migrations/002_seed.sql

INSERT INTO users (username, email, salt, password_hash, role)
VALUES ('admin', 'admin@example.com', 'abc123', 'hashed_value', 'admin');

INSERT INTO users (username, email, salt, password_hash, role)
VALUES ('alice', 'alice@example.com', 'def456', 'hashed_value', 'user');

INSERT INTO users (username, email, salt, password_hash, role)
VALUES ('bob', 'bob@example.com', 'ghi789', 'hashed_value', 'user')

ugahost db migrate ./migrations/002_seed.sql

JSON migration file (.json)

For programmatically generated migrations, use the JSON format. Each entry in operations has a sql field:

{
  "version": "003",
  "description": "Add posts table",
  "operations": [
    { "sql": "CREATE TABLE IF NOT EXISTS posts (id INTEGER PRIMARY KEY AUTOINCREMENT, user_id INTEGER NOT NULL, title TEXT NOT NULL, body TEXT, created_at TEXT NOT NULL DEFAULT (datetime('now')), FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE)" },
    { "sql": "CREATE INDEX IF NOT EXISTS idx_posts_user_id ON posts(user_id)" }
  ]
}

ugahost db migrate ./migrations/003_posts.json

Recommended project layout

my-api/
├── index.js          # or app.py
├── ugahost.json
└── migrations/
    ├── 001_init.sql  # schema — tables, indexes
    ├── 002_seed.sql  # initial data
    └── 003_posts.sql # subsequent changes

Import & Export

Export — ugahost db export

Dumps all rows from a table to a local JSON file. Useful for backups or moving data between projects.

# Export to auto-named file: users-export-1234567890.json
ugahost db export users

# Export to a specific file
ugahost db export users -o ./backups/users.json

Import — ugahost db import

Bulk-inserts rows from a JSON array file into a table. The id field is stripped automatically — the database assigns new IDs.

# Import from a previously exported file
ugahost db import users ./backups/users.json

# Import from a handwritten seed file
ugahost db import products ./seeds/products.json

The seed file must be a JSON array of objects whose keys match the table's column names:

[
  { "name": "Widget A", "price": 9.99, "stock": 100 },
  { "name": "Widget B", "price": 14.99, "stock": 50 }
]

Environment Variables

Env vars are stored securely in the platform database and injected into your Worker on every deploy. They are available in your code via the normal patterns for each language.

How injection works

When the platform deploys or redeploys your Worker it:

1. Reads all rows from backend_env_vars for your project
2. Merges them with Turso credentials from the project record
3. Passes the full set as Cloudflare plain_text bindings in the Worker metadata — making them available on env.VAR_NAME
4. Also sets them on globalThis.process.env.VAR_NAME (polyfill, for Express-style apps)

Env Commands

Examples

# Set a plain variable
ugahost env set NODE_ENV production

# Set a secret (API key, password, etc.)
ugahost env set STRIPE_SECRET_KEY sk_live_... --secret

# Interactive mode — prompts for key, value, and secret flag
ugahost env set

# Remove a variable
ugahost env unset NODE_ENV

Logs

All console.log, console.error, and console.warn calls in your app are captured and stored per-project.

# Fetch the last 100 log lines
ugahost logs

# Fetch more lines
ugahost logs --lines 500

Log levels are colour-coded in the terminal:

Status

ugahost status

Displays project details and current quota usage:

Full CLI Reference

Prerequisites

Repository Requirements

Account Requirements

Deployment Steps

my-project/
├── index.html     ← required
├── css/style.css
├── js/script.js
└── README.md

Best Practices

Repository Structure

Deployment Tips

Need Help?

The QSSN PaaS support team is available to help you succeed with your deployment.