dployr

module

v0.4.3 Latest Latest Go to latest Published: Nov 27, 2025 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/dployr-io/dployr

Links

Open Source Insights

README ¶

dployr

Your app, your server, your rules!

Overview

dployr is a self‑hosted platform with a globally distributed control‑plane (“base”) and lightweight agents that run on your infrastructure.

You interact with base through:

The web dashboard (dployr‑app), or
The CLI (dployr‑cli)

Both use the same programmatic, RBAC‑aware API with full auditing. Anything you do in the UI can be scripted with the CLI or called directly.

It consists of four components:

dployr‑base — Globally distributed control‑plane (API, scheduling, storage). Single source of truth.
dployrd — Daemon on each instance. Connects to base over mTLS, executes tasks, and reports status.
dployr‑cli — RBAC‑aware command‑line client that talks to base from anywhere.
dployr‑app — Web dashboard built on the same API for managing projects, deployments, and environments.

Quickstart (5 minutes)

Linux/macOS

# First time install
curl -sSL https://raw.githubusercontent.com/dployr-io/dployr/master/install.sh \
  | bash -s -- --token "<bootstrap_token>"

# Install latest version
curl -sSL https://raw.githubusercontent.com/dployr-io/dployr/master/install.sh | bash

# Start the daemon
dployrd

Windows (PowerShell as Administrator)

iwr "https://raw.githubusercontent.com/dployr-io/dployr/master/install.ps1" -OutFile install.ps1
.\install.ps1  # add -Token $env:DPLOYR_INSTALL_TOKEN (first time install)

dployrd.exe

Verify

Version: dployrd --version
Logs (JSON): /var/log/dployrd/app.log (Linux/macOS) or ProgramData on Windows
Daemon should start and log a websocket mTLS connection attempt to Base.

Quick deploy

dployr deploy \
  --name hello-world \
  --source remote \
  --runtime nodejs \
  --version 20 \
  --remote https://github.com/dployr-io/dployr-examples \
  --branch master \
  --build-cmd "npm install" \
  --run-cmd "npm start" \
  --working-dir "nodejs" \
  --port 3000

Concepts

CLI vs Daemon: CLI issues commands; daemon (dployrd) executes and syncs with Base.
Sync: long‑lived WSS + mTLS. Daemon generates a client cert and publishes it to Base.
Tokens: bootstrap_token (long‑lived, stored in DB) → exchanged for short‑lived access_token (auto‑refreshed).
Persistence: SQLite for instance metadata, tokens, deployments, services, task results.
Logging: structured JSON to stdout + /var/log/dployrd/app.log for remote debugging.

Troubleshooting

No bootstrap token: set it in config or rerun installer with --token.
WS auth errors (401/403): daemon clears access_token and reacquires; check logs.
mTLS/cert issues: ensure pinned CA/cert path is correct if you customized certs.
Permissions: service managers may require admin/root for install/start.
Where are logs? /var/log/dployrd/app.log (Linux/macOS). On Windows, see ProgramData/dployr.

Dependencies

dployr relies on a few external tools to provide core functionality:

Dependency	Purpose	Platform
Caddy	Reverse proxy and automatic HTTPS management	All
vfox	Runtime and version management (Node, Python, Go, etc.)	All
SQLite	Embedded database for persistence and data storage	All
systemd	Linux service manager for running `dployrd` as a background daemon	Linux
launchd	macOS service manager for running `dployrd` as a background daemon	macOS
NSSM	Windows service manager for running `dployrd` as a background daemon	Windows

Note: Each operating system uses its native service manager: systemd on Linux, launchd on macOS, and NSSM on Windows. These binaries are automatically downloaded and configured during installation when possible.

Supported Runtimes

Static files
Node.js
Python
Go
PHP
Ruby
.NET
Java
Docker containers
K3s clusters (roadmap)
Custom runtimes

Installation

Quick Install

Linux/macOS

# First-time setup 
curl -sSL https://raw.githubusercontent.com/dployr-io/dployr/master/install.sh \
  | bash -s -- --token "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

# Install latest version 
curl -sSL https://raw.githubusercontent.com/dployr-io/dployr/master/install.sh \
  | bash 

# Install specific version
curl -sSL https://raw.githubusercontent.com/dployr-io/dployr/master/install.sh \
  | bash -s -- --version v0.1.1-beta.17

Note: You’ll need administrator privileges (sudo) to install, but the dployr daemon itself runs as dployr user, not as root. For details about permissions and setup, visit https://docs.dployr.dev/permissions.

Config locations:

Linux: /etc/dployr/config.toml

macOS: /usr/local/etc/dployr/config.toml

Windows: C:\ProgramData\dployr\config.toml

Manual Installation

Linux

# Download the latest release
curl -L https://github.com/dployr-io/dployr/releases/latest/download/dployr-Linux-x86_64.tar.gz -o dployr.tar.gz

# Extract and install
tar -xzf dployr.tar.gz
sudo mv dployr dployrd /usr/local/bin/
chmod +x /usr/local/bin/dployr /usr/local/bin/dployrd

# Install Caddy 
sudo apt update && sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install caddy

Windows (PowerShell as Administrator)

# Install latest version
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/dployr-io/dployr/master/install.ps1" -OutFile "install.ps1"
.\install.ps1

# Install specific version
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/dployr-io/dployr/master/install.ps1" -OutFile "install.ps1"
.\install.ps1 -Version v0.1.1-beta.17 -Token $env:DPLOYR_INSTALL_TOKEN

# Custom install directory
.\install.ps1 -Version latest -InstallDir "C:\dployr" -Token $env:DPLOYR_INSTALL_TOKEN

Package Managers

Homebrew (macOS)

brew install dployr-io/dployr/dployr

Chocolatey (Windows)

choco install dployr

Scoop (Windows)

scoop bucket add dployr https://github.com/dployr-io/scoop-dployr
scoop install dployr

Configuration

Configuration files are stored at ~/.dployr/config.toml:

address = "localhost"
port = 7879
max-workers = 5
secret = "your-secret-key"

Usage

Start the Daemon

dployrd

Authenticate

dployr login --email user@example.com

Deploy an Application

dployr deploy \
  --name old-county-times \
  --source remote \
  --runtime php \
  --version 8.3 \
  --remote https://github.com/dployr-io/dployr-examples \
  --branch master \
  --build-cmd "composer install" \
  --run-cmd "php -S localhost:3000" \
  --working-dir "php" \
  --port 3000

For detailed deployment examples—including interactive guides—visit: https://docs.dployr.dev/runtimes/quick-deploy

List Deployments

dployr list

Manage Services

dployr services list
dployr services get <service-id>

Configure Proxy

dployr proxy add --domain myapp.com --upstream http://localhost:3000
dployr proxy list
dployr proxy status

API

The daemon exposes a REST API on port 7879 (configurable).

Full spec: api/openapi.yaml
Interactive docs: docs.dployr.dev

Authentication

Most endpoints require JWT authentication:

Authorization: Bearer <jwt-token>

Development

Prerequisites

Go 1.24+
Git

Build

make build          # Build both binaries
make build-cli      # Build CLI only
make build-daemon   # Build daemon only

Test

make test

Release

./scripts/release.sh patch    # Patch release
./scripts/release.sh minor    # Minor release
./scripts/release.sh major    # Major release

License

MIT License — see LICENSE for details.

Documentation

Complete documentation available at https://docs.dployr.dev

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
dployr command
dployrd command
internal
auth Package auth implements token validation and auth middleware integration.	Package auth implements token validation and auth middleware integration.
db Package db offers utilities for managing the application's SQLite database, including initialization, schema migration, and embedded migration handling.	Package db offers utilities for managing the application's SQLite database, including initialization, schema migration, and embedded migration handling.
deploy Package deploy implements deployment orchestration, handlers, and integration logic for managing application deployments in the daemon.	Package deploy implements deployment orchestration, handlers, and integration logic for managing application deployments in the daemon.
proxy Package proxy provides types and handlers for managing reverse proxy applications.	Package proxy provides types and handlers for managing reverse proxy applications.
scripts Package scripts embeds and exposes shell scripts required by the daemon for deployment, system management, and runtime integration.	Package scripts embeds and exposes shell scripts required by the daemon for deployment, system management, and runtime integration.
service Package service coordinates service management, lifecycle operations, and integration with other components of the daemon, such as deployment and proxy.	Package service coordinates service management, lifecycle operations, and integration with other components of the daemon, such as deployment and proxy.
store Package store provides concrete persistence implementations backing the persistence interfaces defined in pkg/store (currently SQLite).	Package store provides concrete persistence implementations backing the persistence interfaces defined in pkg/store (currently SQLite).
stream Package stream provides types and handlers for streaming application logs to clients.	Package stream provides types and handlers for streaming application logs to clients.
svc_runtime Package svc_runtime provides cross-platform abstractions for managing system services (such as systemd on Linux, launchd on macOS, and NSSM on Windows) used to run and control background application processes.	Package svc_runtime provides cross-platform abstractions for managing system services (such as systemd on Linux, launchd on macOS, and NSSM on Windows) used to run and control background application processes.
system Package system implements the daemon's system service: sync, install/upgrade, registration, and health.	Package system implements the daemon's system service: sync, install/upgrade, registration, and health.
web Package web provides the HTTP server and multiplexer for the daemon's web API.	Package web provides the HTTP server and multiplexer for the daemon's web API.
worker Package worker implements the daemon's background deployment worker, job queue, and concurrency management.	Package worker implements the daemon's background deployment worker, job queue, and concurrency management.
pkg
auth Package auth implements authentication primitives and middleware for the daemon's HTTP API.	Package auth implements authentication primitives and middleware for the daemon's HTTP API.
core/deploy Package deploy defines core deployment types, handlers, and orchestration interfaces used by the daemon for managing application deployments.	Package deploy defines core deployment types, handlers, and orchestration interfaces used by the daemon for managing application deployments.
core/proxy Package proxy provides types and handlers for managing reverse proxy applications.	Package proxy provides types and handlers for managing reverse proxy applications.
core/service Package service models services and provides HTTP handlers for service operations used by the daemon.	Package service models services and provides HTTP handlers for service operations used by the daemon.
core/stream Package stream provides types and handlers for streaming application logs to clients.	Package stream provides types and handlers for streaming application logs to clients.
core/system Package system defines the public contract for daemon-level operations in dployr.	Package system defines the public contract for daemon-level operations in dployr.
core/utils
core/worker Package worker defines the daemon's background deployment worker, job queue, and concurrency management.	Package worker defines the daemon's background deployment worker, job queue, and concurrency management.
shared Package shared provides configuration, logging, error helpers, and constants used across dployrd.	Package shared provides configuration, logging, error helpers, and constants used across dployrd.
store Package store defines data models and interfaces for persistence in dployr.	Package store defines data models and interfaces for persistence in dployr.
tasks Package tasks models remotely-triggered actions and their results for dployr's distributed task system.	Package tasks models remotely-triggered actions and their results for dployr's distributed task system.
version Package version exposes build-time version metadata (version, commit, build date, Go runtime) for dployr binaries.	Package version exposes build-time version metadata (version, commit, build date, Go runtime) for dployr binaries.
version