compose

Documentation

Index

• Constants
• Variables
• func DigestForContent(b []byte) string
• func IsValidDigest(s string) bool
• func LoadImageDigests(projectDir string) error
• func NormalizeDigest(s string) (string, error)
• func PinImage(imageTag, digest string) string
• func ResolveImage(service, image string) string
• func SaveImageDigests(projectDir string, digests map[string]string) error
• func SplitImageRef(ref string) (name, tag, digest string)
• type BuildConfig
• type DepOn
• type DeployConfig
• type DockerCompose
  • func (dc *DockerCompose) AddService(name string, svc ServiceConfig)
  • func (dc *DockerCompose) MarshalYAML() (interface{}, error)
• type Generator
  • func NewGenerator(cfg *config.Config) *Generator
  • func (g *Generator) Generate() ([]byte, error)
• type Healthcheck
• type LoggingConfig
• type NetworkConfig
• type ResourceLimits
• type Resources
• type ServiceConfig
• type ServiceSecurity
  • func DefaultSecurity() ServiceSecurity
  • func MinioSecurity() ServiceSecurity
  • func NginxSecurity() ServiceSecurity
  • func PostgresSecurity() ServiceSecurity
  • func RedisSecurity() ServiceSecurity
• type VolumeConfig

Constants

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

DigestConfigFile is the filename where image digests are stored.

const DigestLength = 64

DigestLength is the hex length of a sha256 digest.

const DigestPrefix = "sha256:"

DigestPrefix is the fixed algorithm prefix for OCI image digests.

const NginxConfDDir = "nginx/conf.d"

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

const NginxSitesDir = "nginx/sites"

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

Variables

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":       "github.com/nself-org/cli/nself-admin:latest",
	"mlflow":      "ghcr.io/mlflow/mlflow:v2.10.0",
}

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

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

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

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

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

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

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

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

SaveImageDigests writes digest pins to the project config directory.

func SplitImageRef

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

	// 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

func MinioSecurity() ServiceSecurity

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

func NginxSecurity

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

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.