@nicholasdigital/dock-it

v0.0.48

Published

5 months ago

A cli to run a a dock-it project

0High
0Medium
0Low

nwpray

dock-it

Dock-it is a wrapper around Docker to make it easier to spin up and manage mono repo environments.

About

Dock-it simplifies Docker-based development for monorepo environments by automatically generating Docker Compose configurations based on your project structure and configuration files.

Getting Started

Installation

You can install dock-it using npm or yarn:

Global Installation (Recommended)

# Using npm
npm install -g @nicholasdigital/dock-it

# Using yarn
yarn global add @nicholasdigital/dock-it

Local Installation (Project-specific)

# Using npm
npm install --save-dev @nicholasdigital/dock-it

# Using yarn
yarn add --dev @nicholasdigital/dock-it

Usage After Installation

Global: Use dock-it directly from any directory
Local: Use npx dock-it or add scripts to your package.json

Prerequisites

Node.js (version 16 or higher)
Docker and Docker Compose
npm or yarn package manager

Quick Start

Follow this complete example to create and run your first dock-it project:

1. Initialize Your Project

# Create a new project directory
mkdir my-dock-it-project
cd my-dock-it-project

# Initialize with npm (optional)
npm init -y

2. Create Root Configuration

Create a dock-it.config.js file in your project root:

// dock-it.config.js
module.exports = {
  name: "my-project",
};

3. Create a Workspace

# Initialize a simple React app workspace (automatically creates workspaces/web/)
dock-it init web --type react

# Create source directory for your React files
mkdir -p workspaces/web/src

This creates workspaces/web/dock-it.config.js:

module.exports = {
  name: "web",
  type: "react",
  entry: "./src/index.js",
};

4. Add Basic React Files

Create a simple React application:

# Create basic React files
cat > workspaces/web/src/index.js << 'EOF'
import React from 'react';
import ReactDOM from 'react-dom/client';

const App = () => <h1>Hello from dock-it!</h1>;

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<App />);
EOF

cat > workspaces/web/src/index.html << 'EOF'
<!DOCTYPE html>
<html>
<head><title>dock-it App</title></head>
<body><div id="root"></div></body>
</html>
EOF

5. Build and Run

# Build Docker containers
dock-it build

# Start your application
dock-it up

# Your React app will be available at http://localhost:3000

6. Development Workflow

# Stop containers only
dock-it down

# Stop containers AND clean up all volumes
dock-it clean

# Push to registry (for production)
dock-it push

Core Concepts

Understanding these key concepts will help you effectively use dock-it:

Packages and Workspaces

Root Package: The main project configuration (dock-it.config.js at project root)
- Defines project name and global settings
- Used as Docker Compose project name
- Can specify registry root for image publishing
Workspace Packages: Individual services/applications within your monorepo
- Located in subdirectories (typically workspaces/)
- Each has its own dock-it.config.js with service-specific configuration
- Can be different types: react, node, script, raw, module

Configuration System

dock-it uses a hierarchical configuration approach:

Discovery: Automatically finds all dock-it.config.js files in your project
Inheritance: Workspace configs inherit from root config settings
Type-based: Different package types use different Docker templates and build processes
Dependencies: Packages can depend on other packages for build order and volume mounting

Docker Integration

dock-it automates Docker workflow through:

Template System: Uses predefined Dockerfiles for each package type (docker/DockerFile.react, etc.)
Variable Substitution: Replaces template variables with actual package configuration
Compose Generation: Creates temporary Docker Compose files with proper service definitions
Multi-stage Builds: Supports both dev and prod build targets
Volume Management: Automatically mounts source code for development hot-reload

Dependency Resolution

dock-it intelligently handles package relationships:

Build Order: Ensures dependent packages are built first
Volume Mounting: Automatically mounts dependency source code in development
Shared Libraries: Enables code sharing between packages in the same monorepo
Watch Mode: Monitors dependency changes for hot-reload during development

Package Types

Each package type has specific behavior:

react: Frontend applications with webpack dev server and hot reload
node: Backend services with automatic bundling and process management
script: Custom scripts with configurable base images and npm scripts
raw: Use a base Docker image (like postgres, redis, nginx) with custom configuration layered on top. Ideal for third-party services that need initialization scripts, config files, or custom content added to a standard image.
module: Shared libraries and utilities used by other packages (does not generate Docker containers)

Example: Raw Package Type

The raw type lets you use standard Docker images with customization:

// workspaces/database/dock-it.config.js
module.exports = {
  name: "database",
  type: "raw",
  image: "postgres:14-alpine",
  ports: ["5432:5432"],
  volumes: ["db-data:/var/lib/postgresql/data"],
  environment: ["POSTGRES_PASSWORD=secret"],
  copy: {
    "./init.sql": "/docker-entrypoint-initdb.d/init.sql"
  },
  baseScripts: [
    "apk add --no-cache curl"
  ]
};

This creates a Postgres container with:

Custom initialization SQL
Additional packages installed
Persistent volume for data
Standard port mapping

Advanced Configuration

The `compose` Key

The compose key allows you to pass any docker-compose specific properties directly to the generated service definition. This is an escape hatch for features not explicitly supported by dock-it:

// workspaces/api/dock-it.config.js
module.exports = {
  name: "api",
  type: "node",
  entry: "./src/index.js",
  compose: {
    platform: "linux/amd64",        // Force specific architecture
    healthcheck: {                   // Add health checks
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"],
      interval: "30s",
      timeout: "10s",
      retries: 3
    },
    deploy: {                        // Swarm deployment settings
      replicas: 3,
      resources: {
        limits: {
          cpus: "0.5",
          memory: "512M"
        }
      }
    }
  }
};

Any properties in compose are spread directly into the docker-compose service definition, giving you full control over the generated configuration.

Commands

For detailed command documentation, see Command Reference.

Configuration

For complete configuration options, see Configuration Guide.

Examples

For real-world examples and tutorials, see Examples.

Documentation

Additional documentation:

Architecture Guide - System internals and extension points
Troubleshooting - Common issues and solutions

Troubleshooting

Common Issues

Container build failures:

# Check Docker is running
docker --version

# Build with debug output
dock-it build --debug

Port conflicts:

# Check what's using the port
lsof -i :3000

# Use different ports in package config
# ports: ["3001:3000"]

For more detailed troubleshooting, see Troubleshooting Guide.

Contributing

We welcome contributions! Please see our Contributing Guidelines for details on:

Setting up the development environment
Code style and conventions
Submitting pull requests
Reporting issues

Development Setup

# Clone the repository
git clone https://github.com/nicholasdigital/dock-it.git
cd dock-it

# Install dependencies
npm install

# Test your changes
npm test

Project Status

✅ Stable: Core functionality is production-ready
🚧 Active Development: New features and improvements ongoing
📖 Documentation: Comprehensive guides and examples available

License

ISC License