Web App Deployment

CI/CD & Automation

Automate frontend deployments to Kodall with ready-to-run CI/CD pipelines, live health checks, instant rollbacks, and the Programmatic TypeScript API.

The @kodall/kodall-deploy package provides full automation capabilities for modern DevOps workflows, including automated CI/CD pipeline generation, instant zero-downtime rollbacks, live endpoint health monitoring, and a programmatic TypeScript API.

CI/CD Workflow Generator (`--init-ci`)

Generate ready-to-run pipeline configuration files automatically using the --init-ci flag:

BASH

npx kodall-deploy --init-ci

The interactive wizard prompts you to select your CI provider, target environment, and build commands. Alternatively, configure your pipeline directly using the templates below:

.github/workflows/deploy.yml

name: Deploy Web App to Kodall

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Install Dependencies
        run: npm ci

      - name: Build Application
        run: npm run build

      - name: Deploy to Kodall Production
        run: npx kodall-deploy -e prod --non-interactive
        env:
          KODALL_API_KEY_PROD: ${{ secrets.KODALL_API_KEY_PROD }}

.gitlab-ci.yml

stages:
  - build
  - deploy

build_app:
  stage: build
  image: node:20
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour

deploy_prod:
  stage: deploy
  image: node:20
  script:
    - npx kodall-deploy -e prod --non-interactive
  only:
    - main
  variables:
    KODALL_API_KEY: $KODALL_API_KEY_PROD

bitbucket-pipelines.yml

image: node:20

pipelines:
  branches:
    main:
      - step:
          name: Build & Deploy to Kodall
          caches:
            - node
          script:
            - npm ci
            - npm run build
            - npx kodall-deploy -e prod --non-interactive
          services:
            - docker

azure-pipelines.yml

trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'
    displayName: 'Install Node.js'

  - script: |
      npm ci
      npm run build
      npx kodall-deploy -e prod --non-interactive
    displayName: 'Build & Deploy to Kodall'
    env:
      KODALL_API_KEY_PROD: $(KODALL_API_KEY_PROD)

Jenkinsfile

pipeline {
    agent any
    tools {
        nodejs 'NodeJS-20'
    }
    stages {
        stage('Install & Build') {
            steps {
                sh 'npm ci'
                sh 'npm run build'
            }
        }
        stage('Deploy') {
            steps {
                withCredentials([string(credentialsId: 'kodall-api-key-prod', variable: 'KODALL_API_KEY')]) {
                    sh 'npx kodall-deploy -e prod --non-interactive'
                }
            }
        }
    }
}

CI Best Practice: Always pass --non-interactive in automated scripts to prevent hanging on user confirmation prompts.

Live Status & Health Inspection (`--status`)

Verify server availability, active storage file IDs, and response latency across all configured environments simultaneously:

BASH

# Check all environments
npx kodall-deploy --status

# Check a specific environment
npx kodall-deploy --status -e prod

Example Output:

TEXT

Target Instance                Status    Storage ID    Latency    Version
-------------------------------------------------------------------------
https://dev.kodall.company.com   ONLINE    40192         42ms       4.2.2
https://kodall.company.com       ONLINE    38910         38ms       4.2.2

Deployment History & Instant Rollbacks (`--rollback`)

Every deployment creates an immutable storage file record inside Kodall. If a regression occurs in production, you can perform an instant rollback to any previous version without rebuilding or re-uploading source assets:

BASH

# Interactive rollback selector (displays past releases with timestamps)
npx kodall-deploy --rollback -e prod

# Instant rollback to a specific storage file ID
npx kodall-deploy --rollback 38910 -e prod

Rendering diagram...

Programmatic TypeScript API

In addition to the CLI, @kodall/kodall-deploy exports a strongly typed programmatic Node.js / ESM library:

TYPESCRIPT

import {
  deploy,
  rollback,
  listEnvironments,
  checkAllEnvironmentsStatus,
  getDeploymentHistory
} from '@kodall/kodall-deploy'

1. Programmatic Deployment (`deploy`)

TYPESCRIPT

import { deploy } from '@kodall/kodall-deploy'

async function runDeploy() {
  const result = await deploy({
    env: 'prod',
    distPath: './dist',
    nonInteractive: true
  })

  if (result.success) {
    console.log('Successfully deployed web application!')
    console.log('Storage ID:', result.storageId)
    console.log('Live URL:', result.liveUrl)
  } else {
    console.error('Deployment failed:', result.error)
  }
}

2. Programmatic Rollback (`rollback`)

TYPESCRIPT

import { rollback } from '@kodall/kodall-deploy'

async function revertRelease() {
  const result = await rollback({
    env: 'prod',
    targetStorageId: 38910,
    nonInteractive: true
  })

  console.log('Rolled back successfully:', result.success)
}

3. Programmatic Status Inspection

TYPESCRIPT

import { checkAllEnvironmentsStatus } from '@kodall/kodall-deploy'

async function verifyFleet() {
  const statuses = await checkAllEnvironmentsStatus()

  for (const env of statuses) {
    console.log(`[${env.name}] ${env.instanceUrl} - ${env.isOnline ? 'ONLINE' : 'OFFLINE'} (${env.latencyMs}ms)`)
  }
}

TypeScript Types Export

The package exports full TypeScript interfaces for all configuration models and operational results:

TYPESCRIPT

export interface DeployConfig {
  web_app_name: string
  web_app_path: string
  dist_path?: string
  default_env?: string
  proxy_paths?: string[]
  environments: Record<string, EnvironmentConfig>
}

export interface EnvironmentConfig {
  type?: string
  instance: string
  api_key?: string
  proxy_paths?: string[]
}

export interface DeployResult {
  success: boolean
  storageId?: number
  liveUrl?: string
  latencyMs?: number
  error?: string
}

export interface StatusCheckResult {
  name: string
  instanceUrl: string
  isOnline: boolean
  activeStorageId?: number
  latencyMs?: number
  serverVersion?: string
}

Local Dev Proxy Suite

Native development proxy suite and Vite plugin with tailored adapters for Vite, Nuxt, Next.js, and Angular with automatic instance resolution and custom proxy paths.

Nuxt 3/4

Step-by-step guide to building, proxying, and deploying Nuxt 3/4 applications to a Kodall instance with @kodall/kodall-deploy.