npm package: @oxog/dockcraft
Description: Zero-dependency Docker orchestration toolkit for Node.js projects
Latest version: 1.0.0

# @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

```bash
npm install @oxog/dockcraft
```

## Quick Start

### CLI

```bash
# 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`:

```typescript
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:

```bash
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

```bash
# 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

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

### Main Function

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

### Port Utilities

```typescript
// 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

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

## Configuration

### App Configuration

```typescript
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

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

### Custom Services

```typescript
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

```typescript
// 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

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

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

### MySQL

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

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

### MongoDB

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

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

### Redis

```typescript
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](https://github.com/ersinkoc/dockcraft)