Run & Deploy

Overview

Running and deploying Oblax applications involves two phases: local development with the built-in server, and production deployment to the Oblax platform (managed SaaS), your own microservices, and front-end applications.

The local development server provides live reload, automatic authentication, and module hot-reload. Production deployment leverages the managed platform, containerized microservices, and SDK integration.

Installation

Running and deploying requires the Oblax CLI installed, authenticated, and a project initialized.

Verify Prerequisites

obx version
obx login

Project Structure

Ensure you have a project with the standard /app structure and at least one module initialized.

Configuration

Local Development Server

Start the local development server:

obx run

What this starts:

• Local Oblax development server (default port: 8080)
• All initialized modules (forms, bookmarks, flux scripts, templates, acl)
• Live reload as you edit /app files
• API endpoints at http://localhost:8080/api/v1/...
• Automatic JWT authentication from your CLI session

Development Workflow

cd my-first-project
obx run

Visit http://localhost:8080 in your browser.

Changes to /app files are live-reloaded automatically:

• Forms: ./app/forms/*.json
• Bookmarks: ./app/bookmarks/*.json
• Flux scripts: ./app/flux-scripts/*.js
• Templates: ./app/templates/*.{html,json}
• ACL: ./app/acl/*.json

Development Server Features

Stop the Development Server

# Press Ctrl+C in the terminal where `obx run` is running

Production Deployment

Deploying Oblax to production involves three main components:

1. Oblax Platform (Managed)

The Oblax platform itself is a SaaS service. After creating your account:

• Your data is stored on Oblax’s infrastructure
• API endpoints: https://api.oblax.io (production) or https://api.staging.oblax.io (staging)
• No self-hosting required for the platform layer
• Your account, projects, and data are automatically replicated for high availability

2. Microservices (Self-Hosted or Containerized)

If your application uses Oblax microservices (generated by obxfw), deploy them to your infrastructure.

Using Docker:

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY dist/ ./dist/
EXPOSE 80
CMD ["node", "dist/main.go"]

Using Kubernetes:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: obx-forms-bff
spec:
  replicas: 3
  selector:
    matchLabels:
      app: obx-forms-bff
  template:
    metadata:
      labels:
        app: obx-forms-bff
    spec:
      containers:
        - name: obx-forms-bff
          image: oblax/obx-forms-bff:latest
          ports:
            - containerPort: 80
          env:
            - name: OBX_FORMS_DOM_HOST
              value: obx-forms-dom:50051
            - name: OBX_FORMS_DOM_PORT
              value: "50051"

Using Fly.io, Railway, or Render:

fly launch
fly scale count 3
fly deploy

3. Front-End Application

Your JavaScript/TypeScript front-end integrates with the Oblax platform SDK.

import { Oblax } from "@oblax/core";
import { platform as browserPlatform } from "@oblax/platform-browser";
import { session } from "@oblax/auth";
import { forms } from "@oblax/forms";

const oblax = new Oblax({
  clientAppId: "production-app-id",
  platform: browserPlatform(),
  modules: [session(), forms()],
  endpoint: "https://api.oblax.io",
  environment: "production",
});

Environment configuration: Use .env files or your CI/CD pipeline to set clientAppId, endpoint, and environment.

Usage

Deployment Checklist

Observability — Monitor Your Oblax Application

Oblax provides built-in observability for deployed applications.

Built-In Metrics

Logs

All Oblax platform actions are logged:

• CLI commands (obx push, obx pull, etc.)
• API requests (authenticated calls)
• Session creates/destroys/refreshes
• Form CRUD operations

Tracing

Oblax integrates with OpenTelemetry for distributed tracing:

import { Oblax } from "@oblax/core";
import { platform as browserPlatform } from "@oblax/platform-browser";

const oblax = new Oblax({
  clientAppId: "my-app",
  platform: browserPlatform(),
});

Traces are available in your Oblax dashboard under Traces or via your preferred tracing provider (Jaeger, Zipkin, etc.).

Rollback and Recovery

Rollback a Form Change

If you’ve pushed a form update that causes issues:

obx app forms pull <previous-id> --override
git checkout <previous-form-file>

Rollback a Microservice Deployment

If you’ve deployed a new microservice version that causes errors:

kubectl rollout undo deployment/obx-forms-bff
docker pull oblax/obx-forms-bff:previous-tag

Emergency Recovery

• Platform data is never lost — all data is stored on Oblax’s highly-available infrastructure
• Local /app directory is your source of truth — keep it git-backed for instant rollback
• JWT tokens can be refreshed — run obx login to obtain a fresh token
• Contact Oblax support for platform-level incidents

Development to Production Pipeline

Local → Staging → Production Flow

Phase 1: Local Development
obx run                    # Local dev server at localhost:8080
                           # Edit /app files, live reload
                           # Test all CRUD workflows

Phase 2: Staging Deployment
obx push                   # Sync local → platform (staging environment)
                           # Deploy microservices to staging infra
                           # Test with staging endpoint

Phase 3: Production Deployment
obx push --environment production  # Sync to production
                           # Deploy microservices to production infra
                           # Update clientAppId to production value
                           # Enable HTTPS/custom domain
                           # Monitor for 24h before declaring stable

CI/CD Integration

name: Oblax CI/CD
on:
  push:
    branches: [main]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Oblax CLI
        run: brew install oblax/tap/obx
      - name: Run tests
        run: obx test
      - name: Push to staging
        run: obx push --environment staging
      - name: Deploy to production
        run: obx push --environment production
      - name: Verify deployment
        run: obx verify --environment production