Website | Examples | Discord

What is Dagu?

Dagu is a lightweight workflow engine with a modern Web UI. Workflows are defined in a simple, declarative YAML format and can be executed on schedule. It supports shell commands, remote execution via SSH, and Docker images. Built-in error notifications and logging out of the box.

For a quick feel of how it works, take a look at the examples.

Motivation

Legacy systems often have complex and implicit dependencies between jobs. When there are hundreds of cron jobs on a server, it can be difficult to keep track of these dependencies and to determine which job to rerun if one fails. It can also be a hassle to SSH into a server to view logs and manually rerun shell scripts one by one. Dagu aims to solve these problems by allowing you to explicitly visualize and manage pipeline dependencies as a DAG, and by providing a web UI for checking dependencies, execution status, and logs and for rerunning or stopping jobs with a simple mouse click.

Why Not Use an Existing Workflow Scheduler Like Airflow?

There are many existing tools such as Airflow, but many of these require you to write code in a programming language like Python to define your DAG. For systems that have been in operation for a long time, there may already be complex jobs with hundreds of thousands of lines of code written in languages like Perl or Shell Script. Adding another layer of complexity on top of these codes can reduce maintainability. Dagu was designed to be easy to use, self-contained, and require no coding, making it ideal for small projects.

How it Works

Dagu executes your workflows defined in a simple, declarative YAML format.

For example, a simple sequential DAG:

schedule: "0 0 * * *" # Runs at 00:00 everyday

steps:
  - echo "Hello, dagu!"
  - echo "This is a second step"

Highlights

• Install by placing a single binary with zero dependency
• Run without DBMS or any cloud service
• Define workflows (DAG) in a declarative YAML format
• Use existing programs, scripts, and container images without any modification
• Schedule workflows with cron expressions
• Run in HA mode and distribute tasks to workers through built-in queue system.
• Modularize workflows by nesting them with sub DAGs (and inspect each sub-run in the UI).

CLI Preview

Web UI Preview

Table of Contents

• Quick Start
  • Quick Start
  • Docker-Compose
• Documentation
  • Documentation
  • Environment Variables
  • Architecture
  • Roadmap
• Development & Contributing
  • Development
  • Discussion
  • Contributing
  • Acknowledgements
• License

Quick Start

1. Install dagu

macOS/Linux:

# Install to ~/.local/bin (default, no sudo required)
curl -L https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.sh | bash

# Install specific version
curl -L https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.sh | bash -s -- --version v1.17.0

# Install to custom directory
curl -L https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.sh | bash -s -- --install-dir /usr/local/bin

# Install to custom directory with custom working directory
curl -L https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.sh | bash -s -- --install-dir /usr/local/bin --working-dir /var/tmp

Windows (PowerShell):

# Install latest version to default location (%LOCALAPPDATA%\Programs\dagu)
irm https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.ps1 | iex

# Install specific version
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.ps1))) v1.24.0

# Install to custom directory
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.ps1))) latest "C:\tools\dagu"

Windows (CMD):

REM Install latest version to default location (%LOCALAPPDATA%\Programs\dagu)
curl -fsSL https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.cmd -o installer.cmd && installer.cmd && del installer.cmd

REM Install specific version
curl -fsSL https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.cmd -o installer.cmd && installer.cmd v1.24.0 && del installer.cmd

REM Install to custom directory
curl -fsSL https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.cmd -o installer.cmd && installer.cmd latest "C:\tools\dagu" && del installer.cmd

Docker:

docker run --rm \
  -v ~/.dagu:/var/lib/dagu \
  -p 8080:8080 \
  ghcr.io/dagu-org/dagu:latest \
  dagu start-all

Note: see documentation for other methods.

Homebrew:

brew update && brew install dagu

# Upgrade to latest version
brew update && brew upgrade dagu

npm:

# Install via npm
npm install -g --ignore-scripts=false @dagu-org/dagu

2. Create your first workflow

Note

: When you first start Dagu with an empty DAGs directory, it automatically creates example workflows to help you get started. To skip this, set DAGU_SKIP_EXAMPLES=true.

cat > ./hello.yaml << 'EOF'
steps:
  - echo "Hello from Dagu!"
  - echo "Running step 2"
EOF

3. Run the workflow

dagu start hello.yaml

4. Check the status and view logs

dagu status hello

5. Explore the Web UI

dagu start-all

Visit http://localhost:8080

Docker-Compose

Clone the repository and run with Docker Compose:

git clone https://github.com/dagu-org/dagu.git
cd dagu

Run with minimal setup:

docker compose -f deploy/docker/compose.minimal.yaml up -d
# Visit http://localhost:8080

Stop containers:

docker compose -f deploy/docker/compose.minimal.yaml down

You can also use the production-like configuration deploy/docker/compose.prod.yaml with OpenTelemetry, Prometheus, and Grafana:

docker compose -f deploy/docker/compose.prod.yaml up -d
# Visit UI at http://localhost:8080
# Jaeger at http://localhost:16686, Prometheus at http://localhost:9090, Grafana at http://localhost:3000

Note: It's just for demonstration purposes. For production, please customize the configuration as needed.

Looking for Kubernetes? See the example manifests in deploy/k8s/README.md.

Documentation

Full documentation is available at docs.dagu.cloud.

Helpful Links:

• Feature by Examples - Explore useful features with examples
• Remote Execution via SSH - Run commands on remote machines using SSH
• Distributed Execution - How to run workflows across multiple machines
• Scheduling - Learn about flexible scheduling options (start, stop, restart) with cron syntax
• Authentication - Configure authentication for the Web UI
• Configuration - Detailed configuration options for customizing Dagu

Changelog

For a detailed list of changes, bug fixes, and new features, please refer to the Changelog.

Environment Variables

Note: Configuration precedence: Command-line flags > Environment variables > Configuration file

Frontend Server Configuration

Environment Variable	Default	Description
DAGU_HOST	127.0.0.1	Web UI server host
DAGU_PORT	8080	Web UI server port
DAGU_BASE_PATH	-	Base path for reverse proxy setup
DAGU_API_BASE_URL	/api/v2	API endpoint base path
DAGU_TZ	-	Server timezone (e.g., Asia/Tokyo)
DAGU_DEBUG	false	Enable debug mode
DAGU_LOG_FORMAT	text	Log format (text or json)
DAGU_HEADLESS	false	Run without Web UI
DAGU_LATEST_STATUS_TODAY	false	Show only today's latest status
DAGU_WORK_DIR	-	Default working directory for DAGs
DAGU_DEFAULT_SHELL	-	Default shell for command execution
DAGU_CERT_FILE	-	TLS certificate file path
DAGU_KEY_FILE	-	TLS key file path

Path Configuration

Environment Variable	Default	Description
DAGU_HOME	-	Base directory that overrides all path configurations
DAGU_DAGS_DIR	~/.config/dagu/dags	Directory for DAG definitions
DAGU_LOG_DIR	~/.local/share/dagu/logs	Directory for log files
DAGU_DATA_DIR	~/.local/share/dagu/data	Directory for application data
DAGU_SUSPEND_FLAGS_DIR	~/.local/share/dagu/suspend	Directory for suspend flags
DAGU_ADMIN_LOG_DIR	~/.local/share/dagu/logs/admin	Directory for admin logs
DAGU_BASE_CONFIG	~/.config/dagu/base.yaml	Path to base configuration file
DAGU_EXECUTABLE	-	Path to dagu executable
DAGU_DAG_RUNS_DIR	{dataDir}/dag-runs	Directory for DAG run data
DAGU_PROC_DIR	{dataDir}/proc	Directory for process data
DAGU_QUEUE_DIR	{dataDir}/queue	Directory for queue data
DAGU_SERVICE_REGISTRY_DIR	{dataDir}/service-registry	Directory for service registry

Authentication

Environment Variable	Default	Description
DAGU_AUTH_BASIC_USERNAME	-	Basic auth username
DAGU_AUTH_BASIC_PASSWORD	-	Basic auth password
DAGU_AUTH_OIDC_CLIENT_ID	-	OIDC client ID
DAGU_AUTH_OIDC_CLIENT_SECRET	-	OIDC client secret
DAGU_AUTH_OIDC_CLIENT_URL	-	OIDC client URL
DAGU_AUTH_OIDC_ISSUER	-	OIDC issuer URL
DAGU_AUTH_OIDC_SCOPES	-	OIDC scopes (comma-separated)
DAGU_AUTH_OIDC_WHITELIST	-	OIDC email whitelist (comma-separated)

UI Configuration

Environment Variable	Default	Description
DAGU_UI_NAVBAR_COLOR	#1976d2	UI header color (hex or name)
DAGU_UI_NAVBAR_TITLE	Dagu	UI header title
DAGU_UI_LOG_ENCODING_CHARSET	utf-8	Log file encoding
DAGU_UI_MAX_DASHBOARD_PAGE_LIMIT	100	Maximum items on dashboard
DAGU_UI_DAGS_SORT_FIELD	name	Default DAGs sort field
DAGU_UI_DAGS_SORT_ORDER	asc	Default DAGs sort order

Scheduler Configuration

Environment Variable	Default	Description
DAGU_SCHEDULER_PORT	8090	Health check server port
DAGU_SCHEDULER_LOCK_STALE_THRESHOLD	30s	Scheduler lock stale threshold
DAGU_SCHEDULER_LOCK_RETRY_INTERVAL	5s	Lock retry interval
DAGU_SCHEDULER_ZOMBIE_DETECTION_INTERVAL	45s	Zombie DAG detection interval (0 to disable)
DAGU_QUEUE_ENABLED	true	Enable queue system

Worker Configuration

This configuration is used for worker instances that execute DAGs. See the Distributed Execution documentation for more details.

Environment Variable	Default	Description
DAGU_COORDINATOR_HOST	127.0.0.1	Coordinator gRPC server bind address
DAGU_COORDINATOR_ADVERTISE	(auto)	Address to advertise in service registry (default: hostname)
DAGU_COORDINATOR_PORT	50055	Coordinator gRPC server port
DAGU_WORKER_ID	-	Worker instance ID
DAGU_WORKER_MAX_ACTIVE_RUNS	100	Maximum concurrent runs per worker
DAGU_WORKER_LABELS	-	Worker labels (format: key1=value1,key2=value2, e.g., gpu=true,memory=64G)
DAGU_SCHEDULER_PORT	8090	Scheduler health check server port
DAGU_SCHEDULER_LOCK_STALE_THRESHOLD	30s	Time after which scheduler lock is considered stale
DAGU_SCHEDULER_LOCK_RETRY_INTERVAL	5s	Interval between lock acquisition attempts

Peer Configuration

This configuration is used for communication between coordinator services and other services (e.g., scheduler, worker, web UI). See the Distributed Execution documentation for more details.

Environment Variable	Default	Description
DAGU_PEER_CERT_FILE	-	Peer TLS certificate file
DAGU_PEER_KEY_FILE	-	Peer TLS key file
DAGU_PEER_CLIENT_CA_FILE	-	Peer CA certificate file for client verification
DAGU_PEER_SKIP_TLS_VERIFY	false	Skip TLS certificate verification for peer connections
DAGU_PEER_INSECURE	true	Use insecure connection (h2c) instead of TLS

Development

Building from Source

Prerequisites

• Go 1.25+
• Node.js
• pnpm

1. Clone the repository and build server

git clone https://github.com/dagu-org/dagu.git && cd dagu
make

This will start the dagu server at http://localhost:8080.

2. Run the frontend development server

cd ui
pnpm install
pnpm dev

Navigate to http://localhost:8081 to view the frontend.

Running Tests

To ensure the integrity of the go code, you can run all Go unit and integration tests.

Run all tests from the project root directory:

make test

To run tests with code coverage analysis:

make make-coverage

Roadmap

See the full Roadmap for all capabilities and planned features.

Discussion

For discussions, support, and sharing ideas, join our community on Discord.

Recent Updates

Changelog of recent updates can be found in the Changelog section of the documentation.

Contributing

We welcome contributions of all kinds! Whether you're a developer, a designer, or a user, your help is valued. Here are a few ways to get involved:

• Star the project on GitHub.
• Suggest new features by opening an issue.
• Join the discussion on our Discord server.
• Contribute code: Check out our issues you can help with.

For more details, see our Contribution Guide and our Roadmap to see what's planned.

Acknowledgements

Contributors

Thanks to all the contributors who have helped make Dagu better! Your contributions, whether through code, documentation, or feedback, are invaluable to the project.

Sponsors & Supporters

Thanks for supporting Dagu’s development! Join our supporters: GitHub Sponsors

License

GNU GPLv3 - See LICENSE