Cosmic Documentation

Introduction

Cosmic is a modern, developer-first platform designed to bridge the gap between your local environment and global production infrastructure. We leverage PM2 for advanced process orchestration and Nginx for high-performance static asset delivery.

Quickstart

Get your application live in under a minute with the Cosmic CLI.

cd my-app
cosmic launch

cosmic deploy

Architecture

Every application you deploy is handled intelligently based on its type. We orchestrate via two primary layers:

• Service Layer (PM2): Dynamically spins up and load-balances long-running node, python, or php processes.
• Static Layer (Nginx): For single-page applications and static sites, traffic never touches an application server—it is served directly from RAM via an aggressive cache policy.

Installation

Download and install the Cosmic CLI tool globally.

curl -fsSL https://cosmic.nisoko.co.ke/install.sh | bash

For Windows users, use the provided executable or PowerShell script.

CLI Commands

The Cosmic CLI is your command center. Once installed, log in to map the CLI to your production environment.

cosmic login             # Securely sign into your orchestrator profile
cosmic launch            # Interactive setup for new applications
cosmic deploy            # Ship current directory to the cluster
cosmic logs [app]        # Stream live stdout/stderr logs
cosmic domain attach     # Attach a custom FQDN to an app
cosmic secret set        # Add production secrets
cosmic rollback [app]    # Revert to a previous deployment version

Authentication

Cosmic uses secure JWT-based session persistence. When you login, we generate a 30-day token correctly mapped to your platform resources.

GitHub Integration

For seamless CI/CD, we utilize GitHub integrations. There are two primary ways to authenticate automation:

• OAuth (Recommended): Running cosmic launch prompts an OAuth flow, directly connecting your account with minimal friction.
• PAT (Personal Access Token): Ideal for headless CI/CD runners where browser interaction isn't possible.

The Cosmic Manifest

The cosmic.yaml file at the root of your repository acts as the absolute source of truth for your application's infrastructure requirements.

name: stellar-api
type: node
nature: service # 'service' for APIs, 'static' for frontends
resources:
  ram: 512       # MB
  disk: 1024     # MB
scripts:
  build: npm install && npm run build
  start: npm start
env:
  NODE_ENV: production

Nature Types

• service: Long-lived processes routed via reverse proxy to internal ports (e.g., Express, Fastify, Django).
• static: Pre-compiled assets served purely and instantly via Nginx (e.g., React, Angular).

Environment Variables & Secrets

Cosmic securely injects environment variables directly into your running processes during launch. Do not commit `.env` files. Instead, bind secrets to your deployed environments directly via the interface or CLI.

cosmic secret set my-app DATABASE_URL="postgres://..."

Domains & SSL

Securing and routing traffic to your app requires minimal configuration and is automatically backed by Let's Encrypt.

# Attach a domain and automatically provision Let's Encrypt SSL
cosmic domain attach my-app api.mydomain.com

Angular Deployment

Angular applications are built and compiled into a highly optimized static bundle. These are served directly from RAM using our global Nginx edge servers.

name: my-angular-app
type: node
nature: static
directory: dist/my-project/browser
scripts:
  build: npm install && npx ng build --configuration production

Key Configuration Notes

React / Vite

Vite ensures lightning-fast build times. Since it's a Single Page Application (SPA), all routing is handled entirely client-side. The orchestrator explicitly instructs Nginx to fallback to index.html to preserve your custom client routes natively.

name: react-vite-dashboard
type: node
nature: static
directory: dist
scripts:
  build: npm install && npm run build

Next.js

Deploying Next.js can be achieved in two ways on Cosmic: as a pure Static Export setup (which leverages pure Nginx routing) or as an ongoing Service (which handles server-side rendering).

Option 1: Static Export (Recommended)

This disables backend Next.js API features but provides milliseconds-latency edge load times.

module.exports = {
  output: 'export'
}

nature: static
directory: out
scripts:
  build: npm install && npx next build

Option 2: SSR Service

For fully dynamic Server-Side Rendered websites requiring backend code.

nature: service
scripts:
  build: npm install && npx next build
  start: npx next start -p $PORT

Node.js Services

Frameworks like Express, NestJS, and Fastify run as long-lived processes. Cosmic utilizes PM2 at the infrastructure layer to ensure they remain alive, restarting them on crash or out-of-memory errors instantly.

type: node
nature: service
scripts:
  build: npm install
  start: node server.js

Python (FastAPI, Flask, Django)

For high-performance Python services, Cosmic will automatically provision an isolated virtual environment and bridge it directly to PM2 using native Python daemonizers.

type: python
nature: service
scripts:
  build: pip install -r requirements.txt
  start: uvicorn main:app --host 0.0.0.0 --port $PORT

PHP Implementations

PHP operates fundamentally differently than NodeJS or Python. There is no daemon to keep alive; instead, Nginx inherently forwards incoming requests directly to the native PHP-FPM fast CGI socket layer.

type: php
nature: static
directory: public # Exposes the public dir, hides backend logic
scripts:
  build: composer install --no-dev --optimize-autoloader

Modern applications like Laravel require you to set the directory specifically to public so your root application code isn't directly routable over HTTP.

Safe Rollbacks

Deployments in Cosmic are versioned automatically. If a new deployment fails or yields unexpected behavior, you can instantly swap back without waiting for a re-build.

cosmic rollback my-app

Logs & Monitoring

Access realtime telemetry for your applications via our unified stream. For services, we pipe standard out and standard error directly from PM2.

cosmic logs my-app --tail 100