@oxog/dockcraft

Zero-dependency Docker orchestration toolkit for Node.js projects.

A config-driven Docker setup generator that creates Dockerfile, docker-compose.yml, and environment configurations from a single TypeScript/JavaScript config. Supports built-in service presets, smart port management, connection string generation, and both CLI and programmatic APIs.

Features

• Zero Dependencies - No runtime dependencies, everything implemented from scratch
• Config-Driven - Generate all Docker files from a single config
• Built-in Presets - Pre-configured stacks (Express, Fastify, NestJS)
• Smart Port Management - Auto-resolve port conflicts
• Connection Strings - Auto-generate for all services
• CLI + API - Use interactively or programmatically
• Type-Safe - Full TypeScript support

Installation

npm install @oxog/dockcraft

Quick Start

CLI

# Interactive wizard
npx @oxog/dockcraft init

# Use a preset
npx @oxog/dockcraft init --preset express-postgres-redis

# Generate Docker files
npx @oxog/dockcraft generate

Programmatic

Create dockcraft.config.ts:

import { dockcraft } from '@oxog/dockcraft';

await dockcraft({
  name: 'my-api',
  app: {
    port: 3000,
    node: '20-alpine',
  },
  services: {
    postgres: { version: '16' },
    redis: { version: '7-alpine' },
  },
});

Generate files:

npx @oxog/dockcraft generate

This creates:

• Dockerfile - Multi-stage Node.js build
• docker-compose.yml - All services configured
• .dockerignore - Optimized file exclusion
• .env.example - Environment variables with connection strings

CLI Usage

# Initialize with wizard
dockcraft init

# Initialize with preset
dockcraft init --preset express-postgres-redis

# Generate from config
dockcraft generate

# Dry run (preview)
dockcraft generate --dry-run

# Check ports
dockcraft ports --check 3000,5432,6379

# List presets
dockcraft presets

API Usage

import {
  dockcraft,
  defineConfig,
  getPreset,
  listPresets,
  resolvePort,
  checkPort,
  getConnectionString,
} from '@oxog/dockcraft';

Main Function

await dockcraft({
  name: 'my-app',
  preset: 'express-postgres',
  app: {
    port: 3000,
    healthcheck: '/health',
  },
  services: {
    postgres: { version: '16' },
  },
  output: {
    dir: './docker',
    overwrite: false,
  },
});

Port Utilities

// Check if port is available
const available = await checkPort(3000);

// Resolve port (auto-find if taken)
const port = await resolvePort({
  preferred: 3000,
  strategy: 'auto', // 'fixed' | 'auto' | 'range'
});

// Find in range
const port = await resolvePort({
  preferred: 3000,
  range: [3000, 3100],
});

Connection Strings

const url = getConnectionString('postgres', {
  host: 'localhost',
  port: 5432,
  database: 'myapp',
  user: 'postgres',
  password: 'postgres',
});
// => postgres://postgres:postgres@localhost:5432/myapp

Configuration

App Configuration

app: {
  port: 3000,              // App port or 'auto'
  node: '20-alpine',       // Node.js version
  workdir: '/app',         // Working directory
  command: 'npm start',    // Start command
  buildCommand: 'npm run build',
  multiStage: true,        // Multi-stage build
  healthcheck: '/health',  // Health endpoint
  env: ['API_KEY'],        // Required env vars
  volumes: ['./data:/app/data'],
}

Service Configuration

services: {
  postgres: {
    version: '16',
    port: 5432,
    database: 'myapp',
    user: 'postgres',
    password: 'postgres',
  },
  redis: {
    version: '7-alpine',
    password: 'secret',
  },
}

Custom Services

services: {
  elasticsearch: {
    image: 'elasticsearch:8.11.0',
    port: 9200,
    env: {
      'discovery.type': 'single-node',
    },
    volumes: ['es_data:/usr/share/elasticsearch/data'],
  },
}

Presets

Available presets:

• express-postgres - Express + PostgreSQL
• express-postgres-redis - Express + PostgreSQL + Redis
• express-mongo - Express + MongoDB
• express-mongo-redis - Express + MongoDB + Redis
• express-mysql - Express + MySQL
• express-mysql-redis - Express + MySQL + Redis
• fastify-postgres - Fastify + PostgreSQL
• fastify-postgres-redis - Fastify + PostgreSQL + Redis
• nest-postgres - NestJS + PostgreSQL
• nest-mongo - NestJS + MongoDB
• node-minimal - Minimal Node.js setup

// Use preset
await dockcraft({
  name: 'my-api',
  preset: 'express-postgres-redis',
});

// Override preset values
await dockcraft({
  name: 'my-api',
  preset: 'express-postgres',
  app: { port: 8080 },
  services: {
    postgres: { version: '15' },
  },
});

Built-in Services

PostgreSQL

postgres: {
  version: '16',
  database: 'myapp',
  user: 'postgres',
  password: 'postgres',
}

Connection: postgres://user:pass@host:port/db

MySQL

mysql: {
  version: '8',
  database: 'myapp',
  user: 'mysql',
  password: 'mysql',
  rootPassword: 'root',
}

Connection: mysql://user:pass@host:port/db

MongoDB

mongo: {
  version: '7',
  database: 'myapp',
  user: 'mongo',
  password: 'mongo',
}

Connection: mongodb://user:pass@host:port/db

Redis

redis: {
  version: '7-alpine',
  password: 'secret',
}

Connection: redis://host:port

Generated Files

Dockerfile

Multi-stage build with:

• Builder stage with dependencies
• Production stage with minimal image
• Health check support
• Configurable Node version

docker-compose.yml

Complete setup with:

• All services with dependencies
• Port mappings
• Environment variables
• Volume definitions
• Health checks

.dockerignore

Optimized exclusions:

• node_modules
• .git
• Test files
• Documentation

.env.example

Environment template with:

• Connection strings
• Service configurations
• Required variables

License

MIT

GitHub: ersinkoc/dockcraft