DockDock

TypeScript CLI to build and deliver your Docker Compose project to remote servers. It can clone from GitHub (with deploy keys) or upload a tar archive, install Docker/Compose on the server when needed, and build in three modes: local, target, or separate builder IP. It also handles optional Git submodules that are meant to be cloned on the server.

Highlights

• Interactive config: Reads DEPLOY.json/deploy.json; if missing, prompts and writes deploy.json.
• GitHub integration (optional): Generates per-repo SSH keys on the server, updates SSH config, and adds GitHub deploy keys via gh.
• Submodules support: Reads .gitmodules from GitHub and only initializes submodules marked onServer=true.
• Docker/Compose bootstrap: Installs or verifies Docker and Docker Compose on the chosen server via apt-get.
• Flexible build modes: local, target, and ip (separate build server); images can be streamed to the target via SSH.

Requirements

• Node.js 18+
• SSH access to your remote host(s)
• For GitHub flows: GitHub CLI (gh) authenticated locally (gh auth login)
• Remote servers assumed Debian/Ubuntu-based (uses apt-get)

Install (local dev)

npm install
npm run build
npm link  # optional: expose `dockdock` globally during development

You can also run without linking:

npx ts-node src/cli.ts --help

Configuration

On each run, the CLI loads DEPLOY.json (preferred) or deploy.json from the current working directory. If neither exists and you run a command that needs config, it will prompt you and write deploy.json.

Fields:

• serverAddress (string): Target/builder server IP/hostname
• username (string): SSH user (default root)
• password (string): SSH password (optional if using SSH keys)
• port (number): SSH port (default 22)
• serverDir (string): Project directory on the server (default ~/project)
• githubProject (string, optional): owner/name; enables GitHub clone flows
• buildMode ("local" | "target" | "ip"): Build location
• buildServerIp (string, optional): Required if buildMode = "ip"
• connectBuildServerToGithub (boolean, default true): If false, code is sent as a tar archive instead of cloning on the server

Example deploy.json:

{
  "serverAddress": "203.0.113.10",
  "username": "root",
  "password": "your-ssh-password",
  "port": 22,
  "serverDir": "~/apps/my-app",
  "githubProject": "owner/repo",
  "buildMode": "target",
  "buildServerIp": "198.51.100.5",
  "connectBuildServerToGithub": true
}

Tip: Prefer SSH keys over passwords for production. Keep deploy.json out of source control.

CLI

dockdock --help

Commands:

• init — Initialize or update deployment settings via prompts (writes deploy.json if missing). Prints a summary of loaded config.

  dockdock init

• stage-server — Place project files on the target server (ignores buildMode).

  • If githubProject is set and connectBuildServerToGithub is true: sets up SSH and clones on the server (plus submodules with onServer=true).
  • Otherwise: creates a tar archive of your local project (respects .gitignore) and uploads/extracts it on the server.

  dockdock stage-server

• stage-builder — Same as stage-server but stages on the builder server (useful when buildMode=ip).

  dockdock stage-builder

• build — Build the project according to buildMode.

  • Always ensures Docker/Compose exist on the selected server.
  • local: runs docker-compose build locally, then streams the image to the target (docker save | ssh docker load).
  • target: prepares code on target (clone or archive upload) and runs docker-compose build on the target.
  • ip: builds on builder and streams the image to the target.

  dockdock build

• deploy — Convenience pipeline: stage (clone or archive) on selected server, build, and if not building on target, stream the image to the target.

  dockdock deploy

Note: The current pipeline builds and (for local/ip) transfers images to the target but does not run docker-compose up -d. Use stage-server to ensure compose files exist on the target, then start services manually on the target, for example:

ssh <user>@<target> "cd <serverDir> && docker-compose up -d"

Build Modes

• local

  • Build runs on your machine (docker-compose build).
  • Image is streamed to the target: docker save | ssh docker load.
  • Start containers on the target manually.

• target

  • Code is prepared on the target (clone or uploaded archive).
  • Target runs docker-compose build.
  • Start containers on the target manually.

• ip

  • Code is prepared on the builder host (buildServerIp).
  • Builder runs docker-compose build and streams the image to the target.
  • Start containers on the target manually.

Submodules

• Only submodules marked with onServer=true in .gitmodules are initialized on the server.
• HTTPS GitHub URLs in .gitmodules are rewritten to SSH form using per-repo deploy keys.

Project Structure (src)

cli.ts                 # Commander CLI entry (init, stage-*, build, deploy)
flow/
  archiveAndSend.ts    # Create tar.gz and upload/extract on server
  buildProject.ts      # Ensure Docker/Compose, then build (local/remote)
  createImageOnTarget.ts# Helper flow (stage + build + send image)
  prepareRepository.ts # GitHub keys + clone main repo + submodules
  sendImageToTarget.ts # Stream built image to target via SSH
settings.ts            # Load config; interactive prompts if missing
utils/
  archive.ts           # tar plan respecting .gitignore
  build.ts             # remote build helpers (docker-compose)
  docker.ts            # Docker/Compose install/verify via apt-get
  github.ts            # Add deploy keys with `gh`, clone helpers
  gitmodules.ts        # Rewrite .gitmodules URLs to SSH on server
  local.ts             # Local shell exec
  remote.ts            # SSH exec + small FS helpers on server
  ssh.ts               # Per-repo SSH keys and ssh_config
  submodules.ts        # Read `.gitmodules` from GitHub via `gh api`
  transfer.ts          # SFTP put/uploadDir

Security

• Do not commit deploy.json with secrets.
• Prefer SSH keys to passwords for servers and GitHub.
• Ensure your SSH user has privileges to install packages (apt-get).

Troubleshooting

• GitHub CLI not authenticated: gh auth login.
• SSH connection errors: verify serverAddress, port, credentials, firewall.
• Docker/Compose missing: rerun dockdock build (it ensures installation).
• Submodules missing: ensure .gitmodules has onServer=true where intended.

DockDock ©