Skip to Content
āš ļø Dockflow is currently under development. Bugs may occur. Please report any issues on GitHub.
Getting Started

Getting Started

Server Setup

Prerequisites:

  • A Debian/Ubuntu server with SSH access (root or sudo user)

Installation

Install the CLI and run setup remotely:

Windows:

irm https://raw.githubusercontent.com/Shawiizz/dockflow/main/install.ps1 | iex
dockflow setup remote

macOS:

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

The CLI will prompt you to connect to your Linux server via SSH. You can provide:

  • SSH host, port, username, and password/key
  • Or an existing Dockflow connection string
dockflow setup

The interactive wizard will guide you through:

  • Checking required dependencies (Ansible, SSH)
  • Creating a deployment user with sudo privileges
  • Configuring SSH key authentication
  • Installing Docker and initializing Swarm mode
  • Optionally installing Portainer for container management
  • Generating a connection string for CI/CD

Non-Interactive Setup (Linux only)

For automated provisioning, Terraform, or CI environments (must be run directly on the target host):

dockflow setup auto \
  --host $(hostname -I | awk '{print $1}') \
  --user dockflow \
  --password "your-secure-password" \
  --generate-key \
  --portainer \
  --portainer-password "portainer-admin-password"

Available options:

OptionDescriptionDefault
--hostPublic IP/hostname for connection stringRequired
--portSSH port22
--userDeployment usernamedockflow
--passwordUser password (for new user or sudo)Required
--ssh-keyPath to existing SSH private key-
--generate-keyGenerate a new SSH keyfalse
--skip-docker-installSkip Docker installationfalse
--portainerInstall Portainerfalse
--portainer-portPortainer HTTP port9000
--portainer-passwordPortainer admin password-
--portainer-domainPortainer domain name-

See dockflow setup auto --help for the complete list.

Create Project Structure

Create the following structure:

    • config.yml
    • servers.yml
      • docker-compose.yml
      • Dockerfile.[service]

Notes:

  • servers.yml defines your servers and environment variables
  • hooks/ and templates/ folders are optional

Copy CI Config File

GitHub users in organizations: Fork the dockflow repoĀ  and update the uses URL in your workflow file.

Create .github/workflows/deploy.yml:

name: Github CI/CD
 
on:
  push:
    branches:
      - '*'
    tags:
      - '*'
 
# Note: Make sure your .deployment/config.yml has project_name set:
# project_name: "my-app"
 
jobs:
  # Basic CI job to run on every push to branches (not used for deployment)
  build:
    if: github.ref_type == 'branch'
    uses: Shawiizz/dockflow/.github/workflows/[email protected]
    with:
      free-disk-space: false # Set to true if you need to free disk space during build (for big docker images)
 
  # Deploy your application on tag push
  deploy-tag:
    if: github.ref_type == 'tag'
    uses: Shawiizz/dockflow/.github/workflows/[email protected]
    with:
      tag: ${{ github.ref_name }}
      free-disk-space: false # Set to true if you need to free disk space during deployment (for big docker images)
    secrets: inherit
 
  # Deploy your application on push to branch
  deploy-branch:
    if: github.ref_type == 'branch'
    uses: Shawiizz/dockflow/.github/workflows/[email protected]
    with:
      version: ${{ github.ref_name }}-${{ github.sha }} # Note: the variable is called "version" specifically for branch deployments
      free-disk-space: false # Set to true if you need to free disk space during deployment (for big docker images)
    secrets: inherit

Add Repository Secrets

Configure secrets in your CI/CD settings:

Using Connection String (Easiest)

Secret NameDescriptionExample
[ENV]_[SERVERNAME]_CONNECTIONAll-in-one connection string per serverPRODUCTION_MAIN_SERVER_CONNECTION
GIT_TOKENOPTIONAL: For remote build optionGitHub/GitLab token

The connection string is automatically generated by the CLI during server setup. It contains all necessary connection details (Host, Port, User, Private Key, Password).

Do not share connection strings - they contain sensitive credentials including SSH private keys.

Server names in servers.yml use underscores in CI secrets. A server named main_server uses MAIN_SERVER in secrets.

Dynamic Variable Override System:

Any CI secret starting with [ENV]_ or [ENV]_[SERVERNAME]_ will automatically override corresponding environment variables defined in your servers.yml.

Configuration