compose

package
v1.1.8 Latest Latest
Warning

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

 Go to latest Published: Jun 15, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package compose: service toggle helper.

Compose-aware plugin enable/disable for Model A.

For Model A plugins (compose-managed services), enable/disable means commenting or uncommenting the service block in docker-compose.yml. We do this with a textual scanner rather than a full YAML parse so the operation is reversible and survives surrounding hand-edits.

Conventions:

  • A service block runs from the `<service-name>:` line at indentation 2 (two spaces) to the next service header (also at indentation 2) or the next top-level key.
  • To DISABLE: prefix every line of the service block with `# ` (the existing indentation is preserved). A `# nself-disabled: <name>` marker line is inserted immediately above the block so we can find it again.
  • To ENABLE: locate the marker line, strip the `# ` prefix from each subsequent block line, and remove the marker.

Idempotency: ToggleService is safe to call repeatedly with the same target state. ToggleService(yaml, "claw", false) on an already-disabled service returns the input unchanged.

Index

Constants

View Source 
const AdminImagePath = "nself/nself-admin"

AdminImagePath is the Docker Hub image name for the nSelf Admin GUI service. It uses the Docker Hub nself/ namespace (NOT GitHub Container Registry). Intentionally referencing nself/nself-admin (Docker Hub) — never github.com/nself-org/ paths.

View Source 
const DigestConfigFile = ".nself-image-digests.json"

DigestConfigFile is the filename where image digests are stored.

View Source 
const DigestLength = 64

DigestLength is the hex length of a sha256 digest.

View Source 
const DigestPrefix = "sha256:"

DigestPrefix is the fixed algorithm prefix for OCI image digests.

View Source 
const NginxConfDDir = "nginx/conf.d"

NginxConfDDir is the host-side directory for env-specific nginx conf.d files. Hand-managed, safe to edit directly.

View Source 
const NginxSitesDir = "nginx/sites"

NginxSitesDir is the host-side directory for generated nginx site configs. GENERATED by nself build — never hand-edit.

Variables

View Source 
var DefaultImageVersions = map[string]string{
	"postgres":    "pgvector/pgvector:pg16",
	"hasura":      "hasura/graphql-engine:v2.44.0",
	"auth":        "nhost/hasura-auth:0.36.0",
	"nginx":       "nginx:1.25-alpine",
	"redis":       "redis:7.2-alpine",
	"minio":       "minio/minio:RELEASE.2024-01-16T16-07-38Z",
	"functions":   "nhost/functions:0.3.7",
	"mailpit":     "axllent/mailpit:v1.15",
	"meilisearch": "getmeili/meilisearch:v1.6",
	"typesense":   "typesense/typesense:0.25.2",
	"admin":       AdminImagePath + ":latest",
	"mlflow":      "ghcr.io/mlflow/mlflow:v2.10.0",
}

DefaultImageVersions maps service name to pinned image:tag. Update with each nSelf release.

View Source 
var ImageDigests = map[string]string{}

ImageDigests maps service name to sha256 digest for image pinning. When a digest is available, ResolveImage appends @sha256:... to the tag. Populated by LoadImageDigests from the project config directory.

Functions

func DigestForContent added in v1.0.9 

func DigestForContent(b []byte) string

DigestForContent returns the sha256 hex digest for the given bytes. Primarily useful for tests and for computing digests of content the CLI itself generates (manifests, configs). NOT a replacement for pulling an authoritative digest from a registry — that requires talking to the registry API.

func IsValidDigest added in v1.0.9 

func IsValidDigest(s string) bool

IsValidDigest returns true if s is a well-formed sha256 digest (64 hex chars, with or without the "sha256:" prefix).

func LoadImageDigests added in v1.0.6 

func LoadImageDigests(projectDir string) error

LoadImageDigests reads digest pins from the project config directory. Missing file is not an error (digests are opt-in via `nself update images`).

func NormalizeDigest added in v1.0.9 

func NormalizeDigest(s string) (string, error)

NormalizeDigest strips a leading "sha256:" prefix and lower-cases the hex. Returns an error if the input is not a valid sha256 digest.

func PinImage added in v1.0.9 

func PinImage(imageTag, digest string) string

PinImage returns the fully-pinned image reference for the given image:tag and digest. If digest is empty the image is returned unchanged (no pin). 

PinImage("postgres:16", "abc...") -> "postgres:16@sha256:abc..."
PinImage("postgres:16", "")       -> "postgres:16"

If the image already contains an @sha256: suffix, the existing pin is replaced with the new one (trust the caller — they asked to repin).

func ResolveImage 

func ResolveImage(service, image string) string

ResolveImage returns the image tag for a service, optionally with a sha256 digest suffix when available.

Precedence: a non-empty caller-supplied image (built from env/config such as POSTGRES_VERSION / HASURA_VERSION) ALWAYS wins. The DefaultImageVersions pin applies only when the caller supplies no image. Pins overriding configured versions force-migrated existing deployments on upgrade (P1 EOP staging incident 2026-06-10: postgres:16-alpine volume recreated as pgvector pg16).

func SaveImageDigests added in v1.0.6 

func SaveImageDigests(projectDir string, digests map[string]string) error

SaveImageDigests writes digest pins to the project config directory.

func SplitImageRef added in v1.0.9 

func SplitImageRef(ref string) (name, tag, digest string)

SplitImageRef splits an image reference into its constituent parts: 

SplitImageRef("postgres:16@sha256:abc...")
-> name="postgres", tag="16", digest="abc..."

SplitImageRef("ghcr.io/foo/bar:v1")
-> name="ghcr.io/foo/bar", tag="v1", digest=""

SplitImageRef("alpine")
-> name="alpine", tag="latest", digest=""

Registries with port numbers (localhost:5000/foo:v1) are handled by scanning right-to-left for the tag separator.

func ToggleService added in v1.0.16 

func ToggleService(yaml, serviceName string, enable bool) (string, bool, error)

ToggleService comments or uncomments the named service block in the supplied docker-compose YAML text. It returns the new YAML text and a bool reporting whether the file was changed.

enable=true → uncomment a previously disabled block (no-op if already enabled) enable=false → comment out an enabled block (no-op if already disabled)

Types

type BuildConfig 

type BuildConfig struct {
	Context    string `yaml:"context"`
	Dockerfile string `yaml:"dockerfile,omitempty"`
}

BuildConfig represents the build context for a service.

type DepOn 

type DepOn struct {
	Condition string `yaml:"condition"`
}

DepOn represents a service dependency with a condition.

type DeployConfig 

type DeployConfig struct {
	Resources *Resources `yaml:"resources,omitempty"`
}

DeployConfig represents deployment constraints for a service.

type DockerCompose 

type DockerCompose struct {
	Name         string                   `yaml:"name"`
	Networks     map[string]NetworkConfig `yaml:"networks"`
	Volumes      map[string]VolumeConfig  `yaml:"volumes"`
	Services     map[string]ServiceConfig `yaml:"-"`
	ServiceOrder []string                 `yaml:"-"`
}

DockerCompose represents a complete docker-compose.yml file. Services are stored as a map for fast lookup, but ServiceOrder tracks insertion order so that MarshalYAML emits them in dependency order (init containers before their dependents, postgres before hasura, nginx last).

func (*DockerCompose) AddService 

func (dc *DockerCompose) AddService(name string, svc ServiceConfig)

AddService inserts a service into the compose file, preserving insertion order via ServiceOrder. If the service name already exists, it is replaced in-place without changing the order.

func (*DockerCompose) MarshalYAML 

func (dc *DockerCompose) MarshalYAML() (interface{}, error)

MarshalYAML outputs the compose file with services in ServiceOrder rather than Go's default alphabetical map ordering. This ensures init containers appear before services that depend on them, which Docker Compose v5 requires.

type Generator 

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

Generator builds a docker-compose.yml from project configuration.

func NewGenerator 

func NewGenerator(cfg *config.Config) *Generator

NewGenerator creates a compose Generator from the given config.

func (*Generator) Generate 

func (g *Generator) Generate() ([]byte, error)

Generate produces the complete docker-compose.yml as YAML bytes. It marshals a DockerCompose struct via gopkg.in/yaml.v3.

type Healthcheck 

type Healthcheck struct {
	Test        []string `yaml:"test"`
	Interval    string   `yaml:"interval,omitempty"`
	Timeout     string   `yaml:"timeout,omitempty"`
	Retries     int      `yaml:"retries,omitempty"`
	StartPeriod string   `yaml:"start_period,omitempty"`
}

Healthcheck represents a service health check configuration.

type LoggingConfig 

type LoggingConfig struct {
	Driver  string            `yaml:"driver"`
	Options map[string]string `yaml:"options,omitempty"`
}

LoggingConfig represents the logging driver and options for a service.

type NetworkConfig 

type NetworkConfig struct {
	Driver string `yaml:"driver,omitempty"`
	// Name pins the real Docker network name. Without it, compose prefixes the
	// project name (e.g. key "myproj_network" becomes "myproj_myproj_network"),
	// which split recreated services onto a new network on existing deployments
	// (P1 EOP prod incident 2026-06-10: nginx 502 on api.nself.org).
	Name string `yaml:"name,omitempty"`
}

NetworkConfig represents a docker-compose network definition.

type ResourceLimits 

type ResourceLimits struct {
	Memory string `yaml:"memory,omitempty"`
	CPUs   string `yaml:"cpus,omitempty"`
	Pids   int64  `yaml:"pids,omitempty"`
}

ResourceLimits represents CPU and memory limits.

type Resources 

type Resources struct {
	Limits       *ResourceLimits `yaml:"limits,omitempty"`
	Reservations *ResourceLimits `yaml:"reservations,omitempty"`
}

Resources represents resource constraints.

type ServiceConfig 

type ServiceConfig struct {
	Image         string            `yaml:"image,omitempty"`
	Build         *BuildConfig      `yaml:"build,omitempty"`
	ContainerName string            `yaml:"container_name,omitempty"`
	Restart       string            `yaml:"restart,omitempty"`
	ShmSize       string            `yaml:"shm_size,omitempty"`
	User          string            `yaml:"user,omitempty"`
	Networks      []string          `yaml:"networks,omitempty"`
	DependsOn     map[string]DepOn  `yaml:"depends_on,omitempty"`
	Environment   map[string]string `yaml:"environment,omitempty"`
	Volumes       []string          `yaml:"volumes,omitempty"`
	Ports         []string          `yaml:"ports,omitempty"`
	Expose        []string          `yaml:"expose,omitempty"`
	Command       interface{}       `yaml:"command,omitempty"`
	Entrypoint    interface{}       `yaml:"entrypoint,omitempty"`
	Healthcheck   *Healthcheck      `yaml:"healthcheck,omitempty"`
	Deploy        *DeployConfig     `yaml:"deploy,omitempty"`
	Logging       *LoggingConfig    `yaml:"logging,omitempty"`
	SecurityOpt   []string          `yaml:"security_opt,omitempty"`
	CapDrop       []string          `yaml:"cap_drop,omitempty"`
	CapAdd        []string          `yaml:"cap_add,omitempty"`
	StopGrace     string            `yaml:"stop_grace_period,omitempty"`
	Labels        map[string]string `yaml:"labels,omitempty"`
	Profiles      []string          `yaml:"profiles,omitempty"`
	ReadOnly      bool              `yaml:"read_only,omitempty"`
	Tmpfs         []string          `yaml:"tmpfs,omitempty"`
	Privileged    bool              `yaml:"privileged,omitempty"`
	WorkingDir    string            `yaml:"working_dir,omitempty"`
	StdinOpen     bool              `yaml:"stdin_open,omitempty"`
	Tty           bool              `yaml:"tty,omitempty"`

	// CapDropComment is an optional comment injected into the generated YAML
	// above cap_add when cap_drop is intentionally omitted. Not serialized as
	// a YAML field — rendered as a comment via MarshalYAML.
	CapDropComment string `yaml:"-"`
}

ServiceConfig represents a single service in docker-compose.yml.

type ServiceSecurity 

type ServiceSecurity struct {
	CapDrop     []string
	CapAdd      []string
	SecurityOpt []string
	ReadOnly    bool
	Tmpfs       []string
	User        string
}

ServiceSecurity holds Docker security configuration for a service.

func DefaultSecurity 

func DefaultSecurity() ServiceSecurity

DefaultSecurity returns the security config applied to most services. read_only root FS with /tmp and /run as tmpfs.

func MinioSecurity added in v1.0.6 

func MinioSecurity() ServiceSecurity

MinioSecurity returns the security config for the MinIO service. MinIO needs CHOWN/SETUID/SETGID for data directory ownership.

func NginxSecurity added in v1.0.6 

func NginxSecurity() ServiceSecurity

NginxSecurity returns the security config for the Nginx service. Nginx needs NET_BIND_SERVICE for ports 80/443 when running non-root.

func PostgresSecurity 

func PostgresSecurity() ServiceSecurity

PostgresSecurity returns the security config for the PostgreSQL service. PostgreSQL needs IPC_LOCK for shared memory and CHOWN/SETUID/SETGID for initdb. Root FS is read-only; data dir is a writable volume.

func RedisSecurity added in v1.0.6 

func RedisSecurity() ServiceSecurity

RedisSecurity returns the security config for the Redis service.

type VolumeConfig 

type VolumeConfig struct {
	Driver string `yaml:"driver,omitempty"`
}

VolumeConfig represents a docker-compose volume definition.

Source Files

View all Source files

Directories

Path Synopsis
Package monitoring — alert rule and Alertmanager config generators.
 Package monitoring — alert rule and Alertmanager config generators.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.