README
¶
Matcha
Go library for deploying containerized applications with automatic SSL, zero-downtime updates, and SQLite backup management.
This is not a generic Docker orchestration tool. Matcha is purpose-built for deploying a specific stack: Caddy reverse proxy + Docker app container + SQLite database. It powers Fusionaly, Formlander, and Lognorth.
What it does
- Deploys your app behind Caddy with automatic Let's Encrypt SSL
- Blue-green deployments for zero downtime
- SQLite backups with retention policies
- Self-updating manager binaries
- DNS validation during setup
Usage
Embed matcha in your project's CLI:
package main
import "github.com/karloscodes/matcha"
var version = "dev" // set via ldflags
func main() {
m := matcha.New(matcha.Config{
Name: "myapp",
AppImage: "ghcr.io/user/myapp:latest",
BlueGreen: true,
CronUpdates: true,
Backups: true,
ManagerRepo: "user/myapp", // GitHub repo for self-updates
ManagerVersion: version,
})
// m.Install(), m.Update(), m.Status(), etc.
}
License
MIT
Documentation
¶
Index ¶
- type BackupFile
- type BackupType
- type Config
- type Matcha
- func (m *Matcha) AppContainerName(slot int) string
- func (m *Matcha) BackupDB() (string, error)
- func (m *Matcha) CaddyContainerName() string
- func (m *Matcha) Deploy() error
- func (m *Matcha) EnvPrefix() string
- func (m *Matcha) Exec(args ...string) error
- func (m *Matcha) GetConfig() Config
- func (m *Matcha) GetDomain() (string, error)
- func (m *Matcha) Install() error
- func (m *Matcha) NetworkName() string
- func (m *Matcha) Reload() error
- func (m *Matcha) RestoreDB() error
- func (m *Matcha) SaveImage() error
- func (m *Matcha) SelfUpdate() (bool, error)
- func (m *Matcha) SetImage(image string)
- func (m *Matcha) StartSpinner(name string) *Spinner
- func (m *Matcha) Status() error
- func (m *Matcha) Update() error
- type RetentionConfig
- type Spinner
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BackupFile ¶
type BackupFile struct {
Name string
Path string
BackupType BackupType
CreatedAt time.Time
Size int64
}
BackupFile represents a database backup file.
type BackupType ¶
type BackupType string
BackupType represents the type of backup (daily, weekly, monthly).
const ( BackupDaily BackupType = "daily" BackupWeekly BackupType = "weekly" BackupMonthly BackupType = "monthly" )
type Config ¶
type Config struct {
// Required
Name string // "fusionaly" → env prefix FUSIONALY_, container names, etc.
AppImage string // "karloscodes/fusionaly:latest"
// Optional with defaults
InstallDir string // default: /opt/{Name}
BinaryPath string // default: /usr/local/bin/{Name}
CaddyImage string // default: caddy:2-alpine
HealthPath string // default: /_health
AppPort int // default: 8080
// Feature flags
BlueGreen bool // dual containers, zero-downtime switch
CronUpdates bool // daily 3 AM auto-update cron job
Backups bool // SQLite backup with retention policy
// Self-update configuration (see selfupdate.go for conventions)
// When configured, Update() checks GitHub releases for newer versions
// and downloads the new binary automatically.
ManagerRepo string // GitHub repo for releases, e.g., "karloscodes/fusionaly"
ManagerVersion string // current version, e.g., "v1.4.37" (set via ldflags at build time)
}
Config defines how Matcha deploys your application.
type Matcha ¶
type Matcha struct {
// contains filtered or unexported fields
}
Matcha is the main orchestrator for deployments.
func (*Matcha) AppContainerName ¶
AppContainerName returns the app container name(s).
func (*Matcha) CaddyContainerName ¶
CaddyContainerName returns the Caddy container name.
func (*Matcha) NetworkName ¶
NetworkName returns the Docker network name.
func (*Matcha) SelfUpdate ¶
SelfUpdate checks for a newer manager version and updates if available. Returns true if an update was performed.
func (*Matcha) StartSpinner ¶
StartSpinner creates and starts an animated spinner for a step.
type RetentionConfig ¶
type RetentionConfig struct {
DailyDays int // Keep daily backups for N days (default: 7)
WeeklyDays int // Keep weekly backups for N days (default: 14)
MonthlyDays int // Keep monthly backups for N days (default: 90)
}
RetentionConfig defines the retention period for each backup type.
func DefaultRetention ¶
func DefaultRetention() RetentionConfig
DefaultRetention returns sensible default retention values.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package testrunner provides utilities for running integration tests in isolated environments using OrbStack VMs.
|
Package testrunner provides utilities for running integration tests in isolated environments using OrbStack VMs. |