deploy

Documentation

Overview

Package deploy provides deployment management for the nSelf CLI. This file implements the blue-green deploy strategy adapter (T06).

Blue-green deploys:

• Spin up a "green" stack alongside the live "blue" stack.
• Run health checks on green.
• Flip Nginx upstream weights from blue → green (100% flip, no canary phase).
• Drain blue connections (60s grace via the bluegreen package).
• Tear down blue.
• On green failure: abort, keep blue running, log error.

This file is the strategy-path adapter called when the user passes --strategy=blue-green. It delegates all orchestration to the internal bluegreen package and writes outcome to .nself/state/deploy.json.

Package deploy provides deployment management for the nSelf CLI. This file implements the canary deploy strategy adapter (T06).

Canary deploys:

• Spin up a canary (green) stack alongside the live (blue) stack.
• Route N% of traffic to green via Nginx weighted upstream.
• Monitor health during a configurable soak window (default 300s / 5min).
• On healthy soak: gradually shift traffic 10% → 50% → 100%.
• On unhealthy soak: revert canary to 0%, tear down green stack, log.

This file is the strategy-path adapter called when the user passes --strategy=canary. It delegates all orchestration to the internal bluegreen package and writes outcome to .nself/state/deploy.json.

Package deploy provides deployment management commands for the nSelf CLI. This file implements the SLO-triggered rollback path (S88d.T05).

The SLO watcher (slo-watcher.ts in ping_api) calls:

nself deploy --rollback --service <service> --key <deploy-key>

This package handles that invocation: validates the deploy key, logs to np_auditlog_events, runs the rollback, and returns exit 0 on success or non-zero on failure.

Package deploy provides deployment management for the nSelf CLI. This file manages the unified deploy state file at .nself/state/deploy.json. It tracks which strategy was last used, its outcome, and provides the rollback target for `nself deploy rollback`.

Index

• Constants
• func SaveDeployState(projectRoot string, s StrategyState) error
• type AuditEvent
• type BlueGreenConfig
• type BlueGreenResult
  • func RunBlueGreen(ctx context.Context, cfg BlueGreenConfig) BlueGreenResult
• type CanaryConfig
• type CanaryResult
  • func RunCanary(ctx context.Context, cfg CanaryConfig) CanaryResult
• type RollbackConfig
• type RollbackResult
  • func ExecuteRollback(ctx context.Context, cfg RollbackConfig) RollbackResult
• type RollbackUIState
• type Strategy
• type StrategyState
  • func LoadDeployState(projectRoot string) (StrategyState, error)

Constants

const DeployStateFile = ".nself/state/deploy.json"

DeployStateFile is the path relative to project root where deploy state is persisted. All deploy strategies (rolling, blue-green, canary) write to this file.

Functions

func SaveDeployState

func SaveDeployState(projectRoot string, s StrategyState) error

SaveDeployState writes the deploy state to .nself/state/deploy.json. The file is written atomically via a temp file + rename to avoid partial reads. Permissions are 0600 because deploy state contains hostnames and error context.

Types

type AuditEvent

type AuditEvent struct {
	EventType    string    `json:"event_type"`
	Service      string    `json:"service"`
	Environment  string    `json:"environment"`
	Reason       string    `json:"reason"`
	Outcome      string    `json:"outcome"`
	PriorVersion string    `json:"prior_version,omitempty"`
	Error        string    `json:"error,omitempty"`
	TriggeredBy  string    `json:"triggered_by"`
	Timestamp    time.Time `json:"timestamp"`
}

AuditEvent is written to np_auditlog_events on rollback.

type BlueGreenConfig

type BlueGreenConfig struct {
	// ProjectRoot is the nSelf project root (contains docker-compose.yml).
	ProjectRoot string

	// Target is the deploy target: local, staging, prod.
	Target string

	// DryRun prints steps without executing them.
	DryRun bool

	// HealthTimeoutSec overrides the default 30-second health check timeout.
	// Zero means use the default.
	HealthTimeoutSec int

	// ForceMigration disables the migration compatibility check and performs a
	// full blue-green flip even when backward-incompatible migrations are pending.
	ForceMigration bool
}

BlueGreenConfig holds the parameters for a blue-green deploy.

type BlueGreenResult

type BlueGreenResult struct {
	// Success is true when the deploy completed without error.
	Success bool

	// Steps is the ordered list of deploy steps with their status.
	Steps []bluegreen.DeployStep

	// Duration is how long the deploy took.
	Duration time.Duration

	// RolledBack is true when an automatic rollback was triggered.
	RolledBack bool

	// Error is set on failure.
	Error string
}

BlueGreenResult is the outcome of a blue-green deploy.

func RunBlueGreen

func RunBlueGreen(ctx context.Context, cfg BlueGreenConfig) BlueGreenResult

RunBlueGreen executes a blue-green deploy:

1. Spins up the green stack alongside blue.
2. Health-checks green.
3. Flips Nginx upstream to 100% green (no canary phase).
4. Health-checks green at 100%.
5. Stops blue.
6. Persists state to .nself/state/deploy.json.

On green failure: aborts immediately, keeps blue running, returns error.

type CanaryConfig

type CanaryConfig struct {
	// ProjectRoot is the nSelf project root (contains docker-compose.yml).
	ProjectRoot string

	// Target is the deploy target: local, staging, prod.
	Target string

	// InitialPercent is the initial canary traffic percentage (1-99).
	// Defaults to 10 when zero.
	InitialPercent int

	// SoakMinutes is the canary soak period in minutes. Defaults to 5.
	SoakMinutes int

	// ErrorThresholdPct is the error rate percentage that triggers auto-rollback.
	// Defaults to 1.0.
	ErrorThresholdPct float64

	// HealthTimeoutSec overrides the default 30-second health check timeout.
	// Zero means use the default.
	HealthTimeoutSec int

	// ForceMigration disables the migration compatibility check.
	// Required when a migration is not backward-compatible with canary traffic.
	ForceMigration bool

	// DryRun prints steps without executing them.
	DryRun bool
}

CanaryConfig holds the parameters for a canary deploy.

type CanaryResult

type CanaryResult struct {
	// Success is true when the deploy completed without error.
	Success bool

	// Steps is the ordered list of deploy steps with their status.
	Steps []bluegreen.DeployStep

	// Duration is how long the deploy took.
	Duration time.Duration

	// FinalPercent is the final canary traffic percentage (100 on success, 0 on rollback).
	FinalPercent int

	// RolledBack is true when an auto-rollback was triggered during the soak.
	RolledBack bool

	// Error is set on failure.
	Error string
}

CanaryResult is the outcome of a canary deploy.

func RunCanary

func RunCanary(ctx context.Context, cfg CanaryConfig) CanaryResult

RunCanary executes a canary deploy:

1. Spins up the canary (green) stack alongside blue.
2. Health-checks green.
3. Routes InitialPercent of traffic to green via Nginx weighted upstream.
4. Monitors green health during the soak window.
5. On healthy: promotes green to 100% traffic, tears down blue.
6. On unhealthy: reverts to 0% canary, tears down green, returns error.
7. Persists state to .nself/state/deploy.json.

type RollbackConfig

type RollbackConfig struct {
	// Service is the nSelf service to roll back (e.g., "ping_api").
	Service string

	// DeployKey is the deploy authorization key (NSELF_DEPLOY_KEY).
	// Required — no anonymous rollbacks.
	DeployKey string

	// Reason is a human-readable reason for the rollback.
	// Set by the SLO watcher: "slo-watcher: <alert description>"
	Reason string

	// Environment is "prod", "staging", etc. Defaults to "prod".
	Environment string

	// MaxRetries is the maximum number of rollback retry attempts. Default: 1.
	MaxRetries int

	// ProjectRoot is the nSelf project root directory. Used to locate
	// docker-compose.yml and state files.
	ProjectRoot string
}

RollbackConfig holds the parameters for a deploy rollback.

type RollbackResult

type RollbackResult struct {
	// Success is true if the rollback completed without error.
	Success bool

	// Service is the service that was rolled back.
	Service string

	// PriorVersion is the version that was restored.
	PriorVersion string

	// Error is set if rollback failed.
	Error string

	// AuditEventID is the ID written to np_auditlog_events.
	AuditEventID string

	// Duration is how long the rollback took.
	Duration time.Duration

	// UIState is one of the 7 UI states for the rollback.
	UIState RollbackUIState
}

RollbackResult is the outcome of a deploy rollback.

func ExecuteRollback

func ExecuteRollback(ctx context.Context, cfg RollbackConfig) RollbackResult

ExecuteRollback performs a service rollback. It: 1. Validates the deploy key 2. Discovers the prior container image tag 3. Re-deploys the prior image 4. Logs an audit event 5. Returns a RollbackResult with the UI state

type RollbackUIState

type RollbackUIState string

RollbackUIState represents the 7 possible states for rollback UI.

const (
	UIStateLoading     RollbackUIState = "loading"           // rollback in progress
	UIStateEmpty       RollbackUIState = "empty"             // no prior version to roll back to
	UIStateError       RollbackUIState = "error"             // rollback command failed
	UIStatePopulated   RollbackUIState = "populated"         // rollback complete + verified
	UIStateOffline     RollbackUIState = "offline"           // no staging connection
	UIStatePermDenied  RollbackUIState = "permission-denied" // no deploy key
	UIStateRateLimited RollbackUIState = "rate-limited"      // circuit breaker engaged
)

type Strategy

type Strategy string

Strategy is the deploy strategy used.

const (
	StrategyRolling   Strategy = "rolling"
	StrategyBlueGreen Strategy = "blue-green"
	StrategyCanary    Strategy = "canary"
)

type StrategyState

type StrategyState struct {
	// SchemaVersion is the version of the StrategyState schema.
	// Set to 1 on all writes. Readers treat 0 (missing field) as the legacy default.
	SchemaVersion int `json:"schema_version"`

	// Strategy is the deploy strategy used.
	Strategy Strategy `json:"strategy"`

	// Target is the deploy target: local, staging, prod.
	Target string `json:"target"`

	// StartedAt is the timestamp when the deploy started.
	StartedAt time.Time `json:"started_at"`

	// CompletedAt is the timestamp when the deploy completed (success or failure).
	CompletedAt time.Time `json:"completed_at"`

	// Success reports whether the deploy succeeded.
	Success bool `json:"success"`

	// CanaryPercent is the final canary traffic split at completion (0 or 100 for non-canary).
	CanaryPercent int `json:"canary_percent"`

	// RolledBack is true when the deploy triggered an automatic rollback.
	RolledBack bool `json:"rolled_back"`

	// Error is the failure reason when Success is false.
	Error string `json:"error,omitempty"`

	// BlueGreenStateFile is the path to the underlying blue/green state file,
	// populated when strategy is blue-green or canary.
	BlueGreenStateFile string `json:"blue_green_state_file,omitempty"`
}

StrategyState records the outcome of the last deploy for a given strategy.

func LoadDeployState

func LoadDeployState(projectRoot string) (StrategyState, error)

LoadDeployState reads the deploy state from .nself/state/deploy.json. Returns a zero-value StrategyState when no state file exists (fresh install).