compose

package
v1.0.12 Latest Latest
Warning

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

 Go to latest Published: Apr 25, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

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 pinned image tag for a service, optionally with a sha256 digest suffix when available. Falls back to the image string as-is if not in DefaultImageVersions.

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.

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

NetworkConfig represents a docker-compose network definition.

type ResourceLimits 

type ResourceLimits struct {
	Memory string `yaml:"memory,omitempty"`
	CPUs   string `yaml:"cpus,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"`

	// PidsLimit caps the number of processes/threads inside the container.
	// Default 100 prevents fork-bomb attacks. Per-plugin override via compose.
	PidsLimit int64 `yaml:"pids_limit,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 generates monitoring-stack configuration files for the nSelf CLI.
 Package monitoring generates monitoring-stack configuration files for the nSelf CLI.

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.