{
  "compilerOptions": {
    "target": "ES2019",
    "module": "commonjs",
    "rootDir": "src",
    "outDir": "dist",
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "strict": false
  },
  "include": ["src/**/*"]
}

Public API

app (default export from app.ts)

import app, { initializeCaptainWithDelay } from './app'

app is the fully configured Express application with all middleware, routers, and proxy logic applied. Use it directly with http.createServer(app) or pass it to a test harness. initializeCaptainWithDelay bootstraps the CaptainManager asynchronously; call it once before the server starts accepting traffic.

initializeCaptainWithDelay

export function initializeCaptainWithDelay(): void

Triggers the Captain system initialization (Docker Swarm setup, Let's Encrypt, nginx config) after a short delay. Called once in server.ts. Do not call it more than once per process; it is not idempotent.

ApiStatusCodes (default export from api/ApiStatusCodes.ts)

import ApiStatusCodes from './api/ApiStatusCodes'
// Usage:
ApiStatusCodes.STATUS_OK             // 100
ApiStatusCodes.AUTHENTICATION_FAILED // 1100
ApiStatusCodes.SERVER_ERROR          // ...

A static map of numeric status codes used in every API response. Reference these codes when constructing BaseApi responses or writing custom route handlers that must conform to CapRover's response contract.

BaseApi (default export from api/BaseApi.ts)

import BaseApi from './api/BaseApi'
// BaseApi wraps response payload with status, description, and data fields

The standard response envelope used by all routes. Instantiate it with a status code and description, then attach data before sending. Ensures all API responses are consistent and parseable by the CapRover frontend.

Working examples

Scenario - Embedding the app in an existing server

You want to mount CapRover's Express app as a sub-application or run it alongside another service.

import * as http from 'http'
import app, { initializeCaptainWithDelay } from './src/app'

// Initialize Captain services before accepting connections
initializeCaptainWithDelay()

const server = http.createServer(app)
server.listen(3000, () => {
    console.log('CapRover backend running on port 3000')
})

server.on('error', (err: NodeJS.ErrnoException) => {
    console.error('Server error:', err)
    process.exit(1)
})

Scenario - Returning a typed API response from a custom route

You need to add a custom endpoint that returns data in the same format as existing CapRover routes.

import { Router, Request, Response } from 'express'
import ApiStatusCodes from './src/api/ApiStatusCodes'
import BaseApi from './src/api/BaseApi'

const router = Router()

router.get('/health', (req: Request, res: Response) => {
    const response = new BaseApi(ApiStatusCodes.STATUS_OK, 'System healthy')
    response.data = { uptime: process.uptime() }
    res.json(response)
})

export default router

Scenario - Importing and using Docker utilities

You want to query the local Docker daemon using CapRover's existing abstraction.

import DockerApi from './src/docker/DockerApi'

async function listServices() {
    const dockerApi = DockerApi.get()
    const services = await dockerApi.getServices()
    for (const svc of services) {
        console.log('Service:', svc.Spec?.Name)
    }
}

listServices().catch(console.error)

File walkthrough

• app.ts - Creates and configures the Express app: registers middleware (morgan, body-parser, cookie-parser), mounts all routers, sets up the HTTP proxy for NetData, and exports initializeCaptainWithDelay.
• server.ts - Entry point: checks for installer mode, calls initializeCaptainWithDelay, creates the HTTP server, and binds to the configured port.
• api/ApiStatusCodes.ts - Numeric status code constants for every API outcome.
• api/BaseApi.ts - Response envelope class wrapping status, description, and payload.
• api/CaptainError.ts - Typed error class used throughout the codebase for structured error propagation.
• datastore/ - Nedb/configstore-backed persistence: apps, registries, projects, and pro feature configs.
• docker/DockerApi.ts - Singleton Dockerode wrapper for all Swarm, service, and container operations.
• docker/DockerUtils.ts - Pure utility functions for Docker name validation and tag parsing.
• handlers/ - Stateless handlers that implement business logic; called by routers.
• injection/Injector.ts - Express middleware that attaches CaptainManager, DataStore, and DockerApi instances to res.locals.
• injection/InjectionExtractor.ts - Typed accessors to pull injected dependencies from res.locals without casting.
• models/ - TypeScript interface definitions for app definitions, registry info, JWT payloads, and all domain types.
• routes/ - Express routers organized by feature: login, user app management, webhooks, one-click apps, pro features, and static downloads.
• user/ - CaptainManager and related services that own the lifecycle of Docker Swarm, nginx, and Let's Encrypt.
• utils/ - Logger, CaptainConstants, EnvVars, CaptainInstaller, and generic utility helpers.
• scripts/ - Standalone scripts for bootstrapping or maintenance tasks.

Common pitfalls and fixes

• IS_CAPTAIN_INSTANCE not set: Without this env var, server.ts runs the installer path and exits immediately. Fix: always export IS_CAPTAIN_INSTANCE=1 for normal server operation.
• Docker socket not accessible: DockerApi connects to /var/run/docker.sock by default; the process must run as root or in the docker group. Fix: chmod 666 /var/run/docker.sock or add your user to the docker group.
• Missing views/ or public/ directory: EJS setup and serve-favicon will throw at startup if these directories don't exist. Fix: create views/ and public/ at the project root and place a favicon.ico in public/.
• esModuleInterop not enabled: Several imports use import x = require(...) syntax. Fix: set "esModuleInterop": true and "allowSyntheticDefaultImports": true in tsconfig.json.
• Port 3000 already in use: CapRover binds to serviceContainerPort3000 unconditionally. Fix: override via CaptainConstants or ensure the port is free before starting.
• configstore permissions error in non-home environments: Configstore writes to ~/.config. Fix: set XDG_CONFIG_HOME to a writable path or run with a user that has a valid home directory.

Vibe-coding prompt template

I have purchased the CapRover backend source block. The source files are in `source/`
and the integration guide is in `USAGE.md`. The upstream npm package is `user@example.com`.

Please integrate this source into my existing Node.js/TypeScript/Express project step by step:

1. Read USAGE.md fully before writing any code.
2. Copy source/ into src/ of my project.
3. Merge the required dependencies from USAGE.md into my package.json and run npm install.
4. Update my tsconfig.json as described in USAGE.md.
5. Create or confirm the views/ and public/ directories exist.
6. Wire initializeCaptainWithDelay and the app export into my existing server entry point.
7. Add any missing environment variables to my .env file.
8. Show me the final server entry point and confirm the app compiles with `npx tsc --noEmit`.
9. If there are conflicts with my existing routes, show me how to mount CapRover's routers
   under a sub-path (e.g., /caprover).
Only use symbols and imports that appear in source/ and USAGE.md. Do not invent APIs.

License and credit

CapRover is open source; see source/LICENSE if present, or the upstream repository at https://github.com/caprover/caprover. The upstream package on npm is caprover. Review the license before redistributing or embedding in a commercial product.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Automation, Utilities & Developer Tools

$6