deploy

package module
v0.0.4 Latest Latest
Warning

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

Go to latest
Published: Feb 21, 2026 License: MIT Imports: 17 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 three modes:

  • cloudflare: uploads build artifacts to Cloudflare Pages via API.
  • 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.Deploy{Store: db, Process: mgr, Downloader: dl, Checker: checker}
d.Run()

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 deploy.yaml if it does not exist.

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 CFClient added in v0.0.4

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

CFClient handles Cloudflare API calls for Pages deployment.

func NewCFClient added in v0.0.4

func NewCFClient(store Store) *CFClient

NewCFClient creates a CFClient backed by the provided Store.

func NewCFClientWithURL added in v0.0.4

func NewCFClientWithURL(store Store, baseURL string) *CFClient

NewCFClientWithURL creates a CFClient with a custom base URL (for tests).

func (*CFClient) Deploy added in v0.0.4

func (c *CFClient) Deploy(outputDir, jsFileName, wasmFileName string) error

Deploy uploads the Pages build output to Cloudflare Pages. outputDir must contain _worker.js and the .wasm file.

func (*CFClient) IsConfigured added in v0.0.4

func (c *CFClient) IsConfigured() bool

IsConfigured returns true if a scoped Pages token exists in the store.

func (*CFClient) SetLog added in v0.0.4

func (c *CFClient) SetLog(f func(...any))

func (*CFClient) Setup added in v0.0.4

func (c *CFClient) Setup(accountID, bootstrapToken, projectName string) error

Setup uses a bootstrap token to create a scoped Pages:Edit token. Stores CF_ACCOUNT_ID, CF_PAGES_TOKEN, CF_PROJECT in the Store.

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 {
	Store      Store
	Process    ProcessManager
	Downloader Downloader
	Checker    HealthChecker
	ConfigPath string
	// contains filtered or unexported fields
}

Deploy is the main orchestrator for all deployment modes. Store must be injected — kvdb.KVStore satisfies the Store interface directly.

func (*Deploy) GetSteps added in v0.0.4

func (d *Deploy) GetSteps() []*wizard.Step

GetSteps implements the interface expected by tinywasm/wizard.New(). Returns the initial steps; method-specific steps are injected dynamically via the Step 1 OnInputFn after the user chooses a deploy method.

func (*Deploy) IsConfigured added in v0.0.4

func (d *Deploy) IsConfigured() bool

IsConfigured returns true if a deploy method has been stored.

func (*Deploy) Run added in v0.0.3

func (d *Deploy) Run() error

Run executes the deployment based on the stored DEPLOY_METHOD. Called from cmd/deploy/main.go for standalone daemon mode.

func (*Deploy) SetLog added in v0.0.4

func (d *Deploy) SetLog(f func(...any))

SetLog injects a logger (called by tinywasm/app after registration with TUI).

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       Store
}

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 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 Store added in v0.0.4

type Store interface {
	Get(key string) (string, error)
	Set(key, value string) error
}

Store is a flat key-value store for deploy configuration and secrets. kvdb.KVStore satisfies this interface directly — no adapter needed.

Keys used by deploy:

DEPLOY_METHOD       → "cloudflare" | "webhook" | "ssh"
DEPLOY_GITHUB_PAT   → GitHub Personal Access Token
DEPLOY_HMAC_SECRET  → HMAC-SHA256 secret for webhook validation
DEPLOY_SERVER_HOST  → host:port for webhook or SSH host
DEPLOY_SSH_USER     → SSH username
DEPLOY_SSH_KEY      → SSH private key path
CF_ACCOUNT_ID       → Cloudflare account ID
CF_PAGES_TOKEN      → Cloudflare scoped Pages:Edit token (auto-created)
CF_PROJECT          → Cloudflare Pages project name

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"`
}

Directories

Path Synopsis
cmd
deploy command

Jump to

Keyboard shortcuts

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