Zoro

Troubleshooting

Start here for symptoms, logs, domains, env vars, compute, integrations, and billing. Task-oriented fixes with links back to guides.

Troubleshooting overview

Fix common first-time problems: account access, dashboard navigation, wizard drafts, and blockers before the first deployment.

Getting started issues

Resolve failed builds, stuck deploys, unhealthy services, rollbacks, and database provisioning failures using logs and task guides.

Deployment issues

Choose build, runtime, or server logs, stream or historical views, and what to copy before opening a support ticket.

Logs and debugging

Fix DNS propagation, certificate status, default hostnames, and routing mismatches for custom domains on Services.

Domain and SSL issues

Fix variables that do not apply after save, wrong references, secrets handling, and confusion between Services and databases.

Environment variable issues

Resolve SSH key problems, unreachable Worker Nodes, Dokku preparation, disk or capacity limits, and managed compute eligibility.

Compute and worker node issues

Fix Git provider auth, Docker registry pulls, and cloud account linking failures that block builds and deploys.

Integration issues

Resolve dFlow Cloud payment failures, plan access questions, and where to find invoices without waiting on support.

Billing issues

Know when self-serve docs end, what evidence speeds up a ticket, and how dFlow Cloud support expectations differ from self-hosted.

When to contact support

Roadmap

Changelog

Introduction

Welcome to dFlow: what the platform is, what makes it different, and where to go next, including dFlow Cloud and self-hosting.

Welcome to dFlow

Beyond the welcome page: comparisons, trade-offs, and when another tool might be a better fit.

Why choose dFlow

Capabilities across applications, environments, services, compute, data, and platform operations.

What you can do with dFlow

Decide between dFlow Cloud and self-hosted dFlow before you open task-by-task guides.

Choose your path

Canonical terms used across dFlow documentation and the product UI.

Glossary

Getting Started

Decide dFlow Cloud vs self-hosted control plane, then follow the matching quick start and first-deploy path.

Shortest path on dFlow Cloud: account, Worker Node, Application, first Service deployment.

Quick start for dFlow Cloud

Install the control plane, then complete first-time Worker Node onboarding (SSH, Dokku, domain).

Quick start for Self-Hosted dFlow

Sign up for dFlow Cloud, verify email, and reach your dashboard at app.dflow.sh.

Create your account and workspace

What to expect after your first login: workspace, navigation, and where Applications and Worker Nodes live.

First login and dashboard tour

Configure a Service from Git, a Docker image, or a database template, then deploy.

Deploy your first app

Add a database Service inside an Application, deploy it, and know where credentials and connections live.

Create your first database

Pick a template from the marketplace or library, instantiate Services, and deploy with guided defaults.

Use your first template

After your first deploy: domains, team access, integrations, databases depth, and operations.

Next steps after setup

Core Concepts

Top-down map of organisations, applications, environments, services, and deployments.

How dFlow is structured

How the control plane, worker nodes, networking, builds, and monitoring fit together.

Platform architecture

Organisation as tenant boundary: members, billing, and how “tenant” maps to the product UI.

Organisations and tenants

Application entity and how it groups environments.

Applications

Environment isolation and compute attachment.

Environments

Services

Worker Nodes execute Services for Environments; how they relate to the control plane and managed compute.

Worker Nodes

What a Deployment represents, how it relates to Services and Environments, and where operations apply.

Deployments

How templates accelerate setup: marketplace, library, and relationship to Applications and Services.

Templates

Conceptual model for backups: scope by Service type, environments, and where task guides live.

Backups

Map legacy Projects to Applications, Environments, and Services; links for mixed legacy/new rollout states.

Legacy Projects vs Applications

dFlow Cloud

Why use dFlow Cloud, where to sign in, browser requirements, and how it relates to your Worker Nodes.

dFlow Cloud overview

After sign-up: what your cloud workspace is and the checklist to reach a first deployment.

Create your cloud workspace

Self-hosted Worker Nodes vs managed compute on dFlow Cloud; attach compute to Environments and separate from self-hosting the control plane.

Choose compute / managed infrastructure

When billing appears on dFlow Cloud, what to prepare, and links to subscription and usage docs.

Payment setup

Authorize GitHub, GitLab, or other providers on app.dflow.sh so Services can build from repositories.

Connect your Git provider

Plan, fair use, builds, and support expectations for dFlow Cloud vs self-hosted control planes.

Cloud limits and expectations

Org access, compute, Git, secrets, operations, and legacy Project migration habits on dFlow Cloud.

Cloud best practices

Self-Hosting dFlow

Why self-host the dFlow control plane, core Compose components, and links to install guides.

Self-hosting overview

CPU, RAM, storage, and software requirements for self-hosting the dFlow control plane.

System requirements

dFlow Cloud vs self-hosting the control plane, and how to pick an install path.

Installation options

Run the dFlow control plane from the official Compose stack: prerequisites, env files, and first boot.

Install with Docker / Docker Compose

Environment variables and secrets for the self-hosted control plane (Compose, URLs, integrations).

Environment configuration

Private networking for the self-hosted control plane, including Tailscale and access patterns.

Tailscale and networking

TLS certificates and hostnames for the self-hosted dashboard and Traefik (control plane).

Control plane domains and SSL

Outgoing email and related services for verification, notifications, and self-hosted dFlow.

Email and outgoing services

Upgrading images and Compose stacks and routine maintenance for self-hosted dFlow.

Upgrades and maintenance

Backing up control-plane data (for example MongoDB) and recovery expectations when self-hosting.

Backups and recovery

Common control-plane failures when self-hosting dFlow and what to check next.

Self-hosting troubleshooting

Short answers to frequent questions about operating self-hosted dFlow.

Self-hosting FAQ

What an Application is in the dashboard, how it relates to Environments and Services, and where to go next.

Applications overview

Create New Application wizard: Application details, Environment, Compute, Services activation, and draft continuation.

Create an application

Application Settings tab: name, description, danger zone delete, and how this differs from Environment settings.

Application settings

Draft, active, and archived Application status; wizard completion; badges and primary actions in the UI.

Application lifecycle

What the default Environment does for navigation, shortcuts, and highlights inside an Application.

Default environment

Restore archived Applications, delete drafts and active Applications, and use delete options safely.

Archive / delete / manage applications

What an Environment is in the dashboard, how it relates to Applications, Services, and Worker Nodes, and where to go next.

Environments overview

Use Add Environment from the Application Environments tab: Environment tier, Compute, and Activation.

Create an environment

Bind Worker Nodes or managed compute to an Environment during the wizard or from the Compute tab.

Attach compute to an environment

How Environment status appears in the UI, how it relates to the Add Environment wizard, and what to expect operationally.

Draft vs active environments

Environment Settings tab: name, default Environment flag, and Danger Zone delete.

Environment settings

Naming, isolation, compute attachment, and operational habits for Environments in dFlow.

Environment best practices

Service types in the dashboard, where they live under Applications and Environments, and links to create, configure, and operate them.

Services overview

Use Applications → Environment → Add service (or the new-Application wizard) to create Services; then configure and deploy.

Create a service

Git-backed application Services: what you configure, automatic vs manual deploys, and links to integrations and operations.

App services

How database Services fit the Applications model; point to Databases section for engines, credentials, backups, and troubleshooting.

Database services

Bring-your-own-image Services: configuration, registry auth, volumes, and operations vs Git-based App services.

Docker services

Environment variables: static values, references to other Services, secret() helper, and database reference variables.

Service settings

Scope of Services per Environment, shared compute, internal networking to databases, and links to Environment docs.

How services relate to environments

Deployments and Operations

Day-2 operations for Services: deploy, scale, route traffic, observe logs, and protect data.

Deployments overview

Trigger Deploy or Redeploy, choose cache behavior, use Restart and Stop, and recover from a bad release.

Redeploy and rollback

Build and deploy logs, runtime logs, and Worker Node (server) logs in dFlow.

Logs

Edit Variables on a Service, save, and redeploy so runtime picks up new configuration.

Environment variables

Replica counts and default resource limits per process from the Scaling tab on App and Docker Services.

Scaling

Attach persistent volumes to App and Docker Services; mount states and deletion behavior.

Volumes and persistent storage

How dFlow terminates TLS and routes HTTP to Services, and how to edit Nginx parameters on a Service.

Proxy and routing

Internal database backups, restore and delete actions, and the backup schedule dialog (scheduling UI is not fully enabled yet).

Deployment status badges, queued operations, restarts after config changes, and live log streaming.

Health checks and runtime behavior

Habits for safer deploys: staging first, narrow changes, secrets hygiene, backups, and observability.

Operational best practices

Add custom domains, set DNS records, choose certificate type, and mark a default hostname on a Service.

Domains and SSL

Worker Nodes and Compute

Worker Nodes overview

Managed compute

Self-hosted servers

Connect a Linux server as a Worker Node: SSH keys, wizard, Dokku prep, and verification.

Add a self-hosted server

Add an AWS server

Attach a server to an environment

Dokku integration

Compute troubleshooting

Charan

Integrations

Git Sources

Git Sources Overview

GitHub

Azure DevOps

Gitlab

Gitea

BitBucket

Cloud Providers

Providers Overview

Docker Registry

dFlow

Git providers, Docker registries, and cloud accounts used by dFlow Services and Worker Nodes.

Integrations overview

Install the dFlow GitHub App, choose org or personal access, and use GitHub-backed App Services.