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

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 remote

The wizard handles everything: Docker installation, Swarm initialization, 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
  - Dockerfile.[service]

config.yml — Project name, build strategy, health checks (reference)
servers.yml — Servers and environment variables (reference)
docker/ — Docker Compose stack and Dockerfiles

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

GitHub organizations: Fork the Dockflow repo and update the uses URL in your workflow file.

GitHub Actions

Create .github/workflows/deploy.yml:


name: Github CI/CD
 
on:
  push:
    branches:
      - '*'
    tags:
      - '*'
 
# Note: Make sure your .dockflow/config.yml has project_name set:
# project_name: "my-app"
 
jobs:
  build:
    if: github.ref_type == 'branch'
    uses: Shawiizz/dockflow/.github/workflows/[email protected]
    with:
      free-disk-space: false
 
  deploy-tag:
    if: github.ref_type == 'tag'
    uses: Shawiizz/dockflow/.github/workflows/[email protected]
    with:
      tag: ${{ github.ref_name }}
      free-disk-space: false
    secrets: inherit
 
  deploy-branch:
    if: github.ref_type == 'branch'
    uses: Shawiizz/dockflow/.github/workflows/[email protected]
    with:
      version: ${{ github.ref_name }}-${{ github.sha }}
      free-disk-space: false
    secrets: inherit

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

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.