Option A — Docker Compose (Recommended)

1. Clone the repository

2. Start with Docker Compose

This builds the image, creates the deploy-engine bridge network, and starts dockpoly-engine container. Visit http://dockplay.mywire.org:80.

Option B — Local Development

1. Install dependencies

2. Start development server

3. Run tests

4. Rebuild after changes

Verify it's working

You should receive a JSON array of containers. An empty array [] is valid — it means no containers are running on the deploy-engine network yet.

Port Map

Project Structure

nexadock/
├── index.ts              # Management API server (port 3000)
├── proxy.ts              # Reverse proxy server (port 4000)
├── config/
│   ├── app.config.ts     # Environment & app config
│   ├── docker.config.ts  # Dockerode socket client
│   └── swagger.config.ts # OpenAPI spec & Swagger UI setup
├── routes/
│   └── managementApp.route.ts
├── controller/
│   └── managementApp.controller.ts
├── services/
│   ├── container.service.ts
│   ├── image.service.ts
│   ├── network.service.ts
│   └── volume.service.ts
├── middleware/
│   └── errorHandler.middleware.ts
├── types/                # TypeScript interface definitions
├── views/
│   ├── landing.ejs       # Landing page
│   ├── index.ejs         # Dashboard console
│   ├── docs.ejs          # This documentation
│   └── partials/
│       └── header.ejs    # Shared navbar component
├── public/
│   ├── style.css         # Global CSS design system
│   ├── app.js            # Client-side JS
│   └── favicon.svg       # NexaDock logo
└── tests/
    └── managementApp.test.ts

How Deployment Works

When you hit POST /container, NexaDock does not just call docker run. It executes a precise multi-step orchestration sequence:

Container Lifecycle State Machine

Deploy a Container

Full Request Body Schema

Power Control Actions

All power control actions follow POST /container/:identifier/:action. The identifier can be the container name or ID (first 12 chars).

Delete Container

Naming Best Practices

Search Docker Hub (Auto-complete)

Used by the dashboard's deploy modal for real-time image search with star counts and official image badges.

{
  "results": [
    {
      "name": "postgres",
      "description": "The PostgreSQL object-relational database system",
      "star_count": 14000,
      "is_official": true,
      "is_automated": false,
      "pull_count": 1000000000
    }
  ]
}

List Local Cached Images

Inspect Full Image Metadata (A-Z)

Returns architecture, OS, creation date, layer digests, size, environment variables, labels, exposed ports, entrypoint, and more.

Delete Local Image

How it Works

Request → http://web-demo.dockplay.mywire.org:80/api/users
  ↓
  proxy.ts parses Host header → "web-demo.dockplay.mywire.org"
  ↓
  Extracts subdomain → "web-demo"
  ↓
  docker.getContainer("web-demo").inspect()
  ↓
  Finds container on "deploy-engine" bridge network
  ↓
  Resolves internal IP → 172.18.0.4
  ↓
  http-proxy-middleware → http://172.18.0.4:80/api/users
  ↓
  Response returned to browser

Root Domain Routes

Accessing a Deployed Container

Attach an Existing Container to the Network

Then immediately access it via:

Port Auto-selection Logic

The proxy selects the container's exposed port in this priority order:

1. Port 80/tcp (standard HTTP)
2. Port 3000 or 8080
3. Any non-443 port
4. First exposed port
5. Falls back to 80

List All Networks

Delete a Network

Recreate the deploy-engine Network

If accidentally deleted, recreate it with:

List All Volumes

Delete a Volume

Containers

Images

Networks & Volumes

Docker Compose

Container Operations

Image Operations

Network & Volume

Run Tests

Expected Output

bun test v1.3.14

tests/managementApp.test.ts:
(pass) should list Docker containers active on internal network
(pass) should list local cached Docker images
(pass) should list Docker networks including deploy-engine bridge
(pass) should list Docker storage volumes
(pass) should search Docker Hub for official image auto-complete

 5 pass
 0 fail
 45 expect() calls
Ran 5 tests across 1 file. [2.23s]

TypeScript Type Check

Zero TypeScript errors expected on a clean build.

Should You Commit .env?

Safe Practice — .env.example

Commit a template file with no real values. Other developers copy it and fill in their own values:

# .env.example — Safe to commit. Contains no real secrets.
PORT=4000
MANAGEMENT_PORT=3000
MANAGEMENT_HOST=127.0.0.1
DOMAIN=localhost
DOCKER_NETWORK=deploy-engine
NODE_ENV=production

Current .env — All Variables

How Variables Are Loaded

NexaDock reads environment variables directly from process.env via config/app.config.ts. All variables have hardcoded fallback defaults, meaning the app works even without any .env file:

// config/app.config.ts
export const config = {
    port:           Number(process.env.PORT)            || 4000,
    managementPort: Number(process.env.MANAGEMENT_PORT) || 3000,
    managementHost: process.env.MANAGEMENT_HOST         || '127.0.0.1',
    domain:         process.env.DOMAIN                  || 'localhost',
    dockerNetwork:  process.env.DOCKER_NETWORK          || 'deploy-engine',
    nodeEnv:        process.env.NODE_ENV                || 'production',
};

Docker Compose Injection

docker-compose.yml reads .env via env_file and also injects variables individually with fallback syntax:

services:
  app:
    env_file:
      - .env          # <-- reads the .env file
    environment:
      - PORT=${PORT:-4000}                     # fallback if not in .env
      - MANAGEMENT_PORT=${MANAGEMENT_PORT:-3000}
      - MANAGEMENT_HOST=${MANAGEMENT_HOST:-127.0.0.1}
      - DOMAIN=${DOMAIN:-localhost}
      - DOCKER_NETWORK=${DOCKER_NETWORK:-deploy-engine}
      - NODE_ENV=${NODE_ENV:-production}

Adding .env to .gitignore

Environment Variables

docker-compose.yml

services:
  app:
    build: .
    container_name: dockpoly-engine
    ports:
      - "4000:4000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - deploy-engine

networks:
  deploy-engine:
    driver: bridge
    name: deploy-engine