dockdock

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.

$3

- 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.

$3

- 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)

$3

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

You can also run without linking:

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

$3

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:

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

$3

`bash
dockdock --help
`

Commands:

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

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

`bash
dockdock stage-server
`

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

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

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

`bash
ssh @ "cd && docker-compose up -d"
`

$3

- 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.

$3

- 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.

$3

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

$3

- 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).

$3

- 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 ©