Getting Started

Dockflow deploys to a single server or a multi-node cluster — same workflow. All you need to get started is one Linux server.

Install the CLI

npm (any OS)


npm install -g @dockflow-tools/cli
dockflow --version

npx (no install)

Run any command directly without installing:


npx @dockflow-tools/cli <command>

For example:


npx @dockflow-tools/cli deploy production

Pin a specific version with npx @dockflow-tools/[email protected] <command>.

Linux / macOS


curl -fsSL https://raw.githubusercontent.com/Shawiizz/dockflow/main/install.sh | bash
dockflow --version

Windows


irm https://raw.githubusercontent.com/Shawiizz/dockflow/main/install.ps1 | iex
dockflow --version

Setup Your Server

You need a Debian/Ubuntu server with SSH access (root or sudo user).

Interactive (Recommended)

If the CLI is installed on the server:


dockflow setup

If the CLI is installed on your local machine:


dockflow setup root@your-server-ip

The wizard handles everything: Docker installation, orchestrator setup (Swarm or k3s), SSH keys, and deployment user creation. At the end, it generates a connection string — save it for later.

Create Your Project


dockflow init

This generates the following structure at the root of your project:

- config.yml
- servers.yml
- - docker-compose.yml
  - accessories.yml
  - Dockerfile

config.yml — Project name, build strategy, health checks (reference)
servers.yml — Servers and environment variables (reference)
docker/ — Docker Compose stack, accessories, and Dockerfile
hooks/ — Pre/post build and deploy hook scripts (reference)

Deploy

CLI

Create a .env.dockflow file at the root of your project with the connection string(s) from setup:


PRODUCTION_MAIN_SERVER_CONNECTION=eyJ...base64...

Then deploy:


dockflow deploy production

The .env.dockflow file is loaded automatically by the CLI. Do not commit it to your repository.

CI/CD

Workflow file

The CLI auto-detects the environment and version from your CI provider’s variables (tag name, branch, commit SHA). No external workflow dependency needed.

You can generate these files automatically with dockflow init.

GitHub Actions

Create .github/workflows/dockflow-build.yml and .github/workflows/dockflow-deploy.yml:


# .github/workflows/dockflow-build.yml
name: Build
 
on:
  push:
    branches: ['*']
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @dockflow-tools/cli build
        env:
          DOCKFLOW_SECRETS: ${{ toJSON(secrets) }}


# .github/workflows/dockflow-deploy.yml
name: Deploy
 
on:
  push:
    tags: ['*']
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @dockflow-tools/cli deploy
        env:
          DOCKFLOW_SECRETS: ${{ toJSON(secrets) }}

Pin a specific CLI version with npx @dockflow-tools/[email protected].

GitLab CI

Create .gitlab-ci.yml at the root of your project:


stages:
  - build
  - deploy
 
# CI: Build images on branch push (needs Docker)
build:
  stage: build
  image: node:24
  services:
    - docker:dind
  variables:
    DOCKER_HOST: tcp://docker:2375
    DOCKER_TLS_CERTDIR: ""
  before_script:
    - apt-get update -qq && apt-get install -y -qq docker.io
  script:
    - npx @dockflow-tools/cli build
  rules:
    - if: $CI_COMMIT_TAG
      when: never
    - when: always
 
# CD: Deploy on tag push (SSH-only, no Docker needed)
deploy:
  stage: deploy
  image: node:24
  script:
    - npx @dockflow-tools/cli deploy
  rules:
    - if: $CI_COMMIT_TAG

Bitbucket Pipelines

Create bitbucket-pipelines.yml at the root of your project:


image: node:24
 
definitions:
  services:
    docker:
      image: docker:dind
 
pipelines:
  # CI: Build images on branch push (needs Docker)
  branches:
    '*':
      - step:
          name: Build
          services:
            - docker
          script:
            - npx @dockflow-tools/cli build
 
  # CD: Deploy on tag push (SSH-only, no Docker needed)
  tags:
    '*':
      - step:
          name: Deploy
          script:
            - npx @dockflow-tools/cli deploy

Bitbucket Pipelines reads secrets from Repository variables — go to Repository Settings → Repository variables to add them.

Repository secrets

Add the connection string generated during setup to your CI/CD secrets:

Connection String (Recommended)

Secret Name	Description	Example
`[ENV]_[SERVERNAME]_CONNECTION`	Connection string per server	`PRODUCTION_MAIN_SERVER_CONNECTION`
`GIT_TOKEN`	Optional: for remote build strategy	GitHub/GitLab token

Where to add secrets:

GitHub: Settings → Secrets and variables → Actions
GitLab: Settings → CI/CD → Variables
Bitbucket: Repository Settings → Repository variables

Do not share connection strings — they contain SSH private keys.

Secret Name	Description	Example
`[ENV]_[SERVERNAME]_SSH_PRIVATE_KEY`	SSH private key	`PRODUCTION_MAIN_SERVER_SSH_PRIVATE_KEY`
`[ENV]_[SERVERNAME]_HOST`	Server IP/hostname	`PRODUCTION_MAIN_SERVER_HOST`
`[ENV]_[SERVERNAME]_USER`	SSH user (default: dockflow)	`PRODUCTION_MAIN_SERVER_USER`
`[ENV]_[SERVERNAME]_PORT`	SSH port (default: 22)	`PRODUCTION_MAIN_SERVER_PORT`
`[ENV]_[SERVERNAME]_PASSWORD`	Sudo password (optional)	`PRODUCTION_MAIN_SERVER_PASSWORD`
`GIT_TOKEN`	Optional: for remote build strategy	GitHub/GitLab token

Server names use underscores in secrets. A server named main_server becomes MAIN_SERVER in secret names.