deploy

package module
v0.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 21, 2026 License: MIT Imports: 15 Imported by: 0

README

deploy

Project Badges

Automated Continuous Deployment (CD) agent for Windows/Linux Server. Receives webhooks from GitHub Actions via a configurable public Endpoint, downloads releases, performs health checks, and executes automatic rollbacks.

Documentation

Document Description
Architecture & Design Executive summary, security model, workflow, and setup
Implementation Guide [TEMPORARY] Phase 1 Windows work prompt
System Components Directory layout, keyring, and network ports
Process Flow High-level deployment flow on Windows Server
Deployment Workflow Detailed sequence diagram (GitHub Actions → Windows)
Setup Flow Interactive first-run setup wizard flow

Quick Summary

  • Push-based: GitHub Actions triggers deployment via POST to a configurable endpoint (set via the DEPLOY_ENDPOINT secret)
  • Security: HMAC-SHA256 request validation + cross-platform keyring for secret storage
  • Resilient: Automatic rollback if health check fails after deploy
  • Zero-dependency binary: Single .exe, no runtime required

Dependencies

  • tinywasm/keyring — Cross-platform secret storage (DPAPI on Windows, Keychain on macOS, Secret Service on Linux)

Documentation

Overview

Package deploy implements a lightweight continuous deployment agent. It supports two modes:

  • webhook: an HTTP daemon on the server that GitHub Actions triggers via POST.
  • ssh: generates a shell script that GitHub Actions runs via SSH on the server.

Usage:

d := deploy.New(keys, mgr, downloader, checker, files)
d.Run("deploy.yaml")

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CreateDefaultConfig added in v0.0.3

func CreateDefaultConfig(path string) error

CreateDefaultConfig creates a default config file at the given path.

func CreateShortcut added in v0.0.3

func CreateShortcut(linkPath, targetPath, workDir string) error

func SSHCommand added in v0.0.3

func SSHCommand(sshKey, sshUser, sshHost, script string) string

SSHCommand returns the ssh command string to run the generated script on a remote host. Intended for GitHub Actions step generation / documentation.

func SSHScript added in v0.0.3

func SSHScript(app AppConfig, downloadURL, githubPAT string) string

SSHScript generates a shell script that a GitHub Action runs via SSH to deploy a new binary version directly on the server.

The generated script:

  1. Downloads the release asset from GitHub
  2. Stops the service (systemctl or pkill)
  3. Replaces the binary (with backup)
  4. Starts the service
  5. Checks health URL

Types

type AppConfig added in v0.0.3

type AppConfig struct {
	Name              string         `yaml:"name"`
	Version           string         `yaml:"version"`
	Executable        string         `yaml:"executable"`
	Path              string         `yaml:"path"`
	Port              int            `yaml:"port"`
	HealthEndpoint    string         `yaml:"health_endpoint"`
	HealthTimeout     time.Duration  `yaml:"health_timeout"`
	StartupDelay      time.Duration  `yaml:"startup_delay"`
	BusyRetryInterval time.Duration  `yaml:"busy_retry_interval"` // default: 10s
	BusyTimeout       time.Duration  `yaml:"busy_timeout"`        // default: 5m
	Rollback          RollbackConfig `yaml:"rollback"`
}

AppConfig represents a single application configuration.

type Checker added in v0.0.3

type Checker struct {
	// contains filtered or unexported fields
}

func NewChecker added in v0.0.3

func NewChecker() *Checker

func (*Checker) Check added in v0.0.3

func (c *Checker) Check(url string) (*HealthStatus, error)

Check performs a health check on the given URL.

type Config added in v0.0.3

type Config struct {
	Updater ConfigUpdater `yaml:"updater"`
	Apps    []AppConfig   `yaml:"apps"`
}

Config represents the application configuration.

func Load added in v0.0.3

func Load(path string) (*Config, error)

Load loads the configuration from the specified path.

type ConfigUpdater added in v0.0.3

type ConfigUpdater struct {
	Port     int         `yaml:"port"` // default: 8080
	LogLevel string      `yaml:"log_level"`
	LogFile  string      `yaml:"log_file"`
	TempDir  string      `yaml:"temp_dir"`
	Retry    RetryConfig `yaml:"retry"`
}

ConfigUpdater holds updater-specific configuration.

type Deploy

type Deploy struct {
	Keys       KeyManager
	Process    ProcessManager
	Downloader Downloader
	Checker    HealthChecker
	ConfigPath string
}

func (*Deploy) Run added in v0.0.3

func (d *Deploy) Run() error

Run executes the main deployment loop.

type Downloader added in v0.0.3

type Downloader interface {
	Download(url, dest, token string) error
}

type HMACValidator added in v0.0.3

type HMACValidator struct {
	// contains filtered or unexported fields
}

func NewHMACValidator added in v0.0.3

func NewHMACValidator(secret string) *HMACValidator

func (*HMACValidator) ValidateRequest added in v0.0.3

func (v *HMACValidator) ValidateRequest(payload []byte, signature string) error

type HTTPDownloader added in v0.0.3

type HTTPDownloader struct {
	// contains filtered or unexported fields
}

func NewDownloader added in v0.0.3

func NewDownloader() *HTTPDownloader

func (*HTTPDownloader) Download added in v0.0.3

func (d *HTTPDownloader) Download(url, dest, token string) error

type Handler added in v0.0.3

type Handler struct {
	Config     *Config
	ConfigPath string
	Validator  *HMACValidator
	Downloader Downloader
	Process    ProcessManager
	Checker    HealthChecker // Use interface
	Keys       KeyManager
}

func (*Handler) HandleUpdate added in v0.0.3

func (h *Handler) HandleUpdate(w http.ResponseWriter, r *http.Request)

type HealthChecker added in v0.0.3

type HealthChecker interface {
	Check(url string) (*HealthStatus, error)
}

type HealthStatus added in v0.0.3

type HealthStatus struct {
	Status     string `json:"status"`
	CanRestart bool   `json:"can_restart"`
}

func ParseHealthResponse added in v0.0.3

func ParseHealthResponse(r io.Reader) (*HealthStatus, error)

type KeyManager added in v0.0.3

type KeyManager interface {
	Get(service, user string) (string, error)
	Set(service, user, password string) error
}

KeyManager defines the interface for managing secrets.

type LinuxManager added in v0.0.3

type LinuxManager struct{}

func (*LinuxManager) Start added in v0.0.3

func (m *LinuxManager) Start(exePath string) error

func (*LinuxManager) Stop added in v0.0.3

func (m *LinuxManager) Stop(exeName string) error

type ProcessManager added in v0.0.3

type ProcessManager interface {
	Start(exePath string) error
	Stop(exeName string) error
}

ProcessManager defines the interface for managing processes.

func NewProcessManager added in v0.0.3

func NewProcessManager() ProcessManager

type RetryConfig added in v0.0.3

type RetryConfig struct {
	MaxAttempts int           `yaml:"max_attempts"`
	Delay       time.Duration `yaml:"delay"`
}

RetryConfig holds retry configuration.

type RollbackConfig added in v0.0.3

type RollbackConfig struct {
	Enabled               bool `yaml:"enabled"`
	KeepVersions          int  `yaml:"keep_versions"` // Only -older
	AutoRollbackOnFailure bool `yaml:"auto_rollback_on_failure"`
}

RollbackConfig holds rollback configuration.

type SystemKeyManager added in v0.0.3

type SystemKeyManager struct{}

SystemKeyManager implements KeyManager using the system keyring.

func NewSystemKeyManager added in v0.0.3

func NewSystemKeyManager() *SystemKeyManager

NewSystemKeyManager creates a new SystemKeyManager.

func (*SystemKeyManager) Get added in v0.0.3

func (m *SystemKeyManager) Get(service, user string) (string, error)

func (*SystemKeyManager) Set added in v0.0.3

func (m *SystemKeyManager) Set(service, user, password string) error

type UpdateRequest added in v0.0.3

type UpdateRequest struct {
	Repo        string `json:"repo"`
	Tag         string `json:"tag"`
	Executable  string `json:"executable"`
	DownloadURL string `json:"download_url"`
}

type Wizard added in v0.0.3

type Wizard struct {
	Keys   KeyManager
	Stdin  io.Reader
	Stdout io.Writer
}

func NewWizard added in v0.0.3

func NewWizard(keys KeyManager) *Wizard

func (*Wizard) MainLoop added in v0.0.3

func (w *Wizard) MainLoop() error

func (*Wizard) Run added in v0.0.3

func (w *Wizard) Run() error

Run checks for configuration and launches the wizard if needed.

func (*Wizard) RunAdmin added in v0.0.3

func (w *Wizard) RunAdmin() error

RunAdmin launches the admin menu.

Directories

Path Synopsis
cmd
deploy command

Jump to

Keyboard shortcuts

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