project

Documentation

Overview

Package project loads Docker Compose files and configures client resources.

This package is not a passive loader. It actively drives resource creation by calling into the client package. The typical flow is:

1. CLI creates a client.Client
2. project.Load() parses the compose file
3. project.ToStack() configures resources on the client and builds a Stack
4. CLI runs the Stack to execute operations on Incus

Index

• func LoadModel(ctx context.Context, opts ...LoadOption) (map[string]any, error)
• func ServiceGraph(serviceConfigs types.Services, reverse bool) ([]string, error)
• type LoadOption
  • func LoadEnvFiles(files []string) LoadOption
  • func LoadFiles(files []string) LoadOption
  • func LoadName(name string) LoadOption
  • func LoadOsEnv() LoadOption
  • func LoadProfiles(profiles []string) LoadOption
  • func LoadWorkingDir(dir string) LoadOption
• type LoadOptions
  • func NewLoadOptions(opts ...LoadOption) LoadOptions
• type Project
  • func New() *Project
  • func (p *Project) HealthdConfig() (incusURL, network string)
  • func (p *Project) InstanceNames() []string
  • func (p *Project) Load(ctx context.Context, opts ...LoadOption) (*Project, error)
  • func (p *Project) ProjectConfig() map[string]string
  • func (p *Project) Resources(c *client.Client, opts ...ResourcesOption) (map[string][]client.Resource, error)
  • func (p *Project) ServiceOrder(reverse bool) ([]string, error)
• type ResourcesOption
  • func ResourcesFull() ResourcesOption
  • func ResourcesScale(scale map[string]int) ResourcesOption
• type ResourcesOptions

Functions

func LoadModel

func LoadModel(ctx context.Context, opts ...LoadOption) (map[string]any, error)

LoadModel loads the raw compose model without interpolation. Useful for extracting variable definitions before resolution.

func ServiceGraph

func ServiceGraph(serviceConfigs types.Services, reverse bool) ([]string, error)

ServiceGraph returns services in dependency order using topological sort. If reverse is true, returns reverse order (useful for shutdown).

Types

type LoadOption

type LoadOption func(*LoadOptions)

LoadOption is a functional option for LoadProject.

func LoadEnvFiles

func LoadEnvFiles(files []string) LoadOption

LoadEnvFiles sets alternative environment files.

func LoadFiles

func LoadFiles(files []string) LoadOption

LoadFiles sets the compose configuration file paths.

func LoadName

func LoadName(name string) LoadOption

LoadName sets the project name.

func LoadOsEnv

func LoadOsEnv() LoadOption

LoadOsEnv includes OS environment variables in the project environment. Without this, only .env files and compose file env vars are used (more portable).

func LoadProfiles

func LoadProfiles(profiles []string) LoadOption

LoadProfiles sets the profiles to enable.

func LoadWorkingDir

func LoadWorkingDir(dir string) LoadOption

LoadWorkingDir sets the working directory.

type LoadOptions

type LoadOptions struct {
	// Project name
	Name string

	// Compose configuration file paths
	Files []string

	// Working directory (if empty, uses current directory or path of first file)
	WorkingDir string

	// Alternative environment files
	EnvFiles []string

	// Profiles to enable
	Profiles []string

	// OsEnv includes OS environment variables in project env (default: false for portability)
	OsEnv bool
}

LoadOptions holds configuration for Load and LoadModel.

func NewLoadOptions

func NewLoadOptions(opts ...LoadOption) LoadOptions

NewLoadOptions creates LoadOptions with the given options applied.

type Project

type Project struct {
	*types.Project
	// contains filtered or unexported fields
}

Project wraps a Docker Compose project with Incus client integration.

func New

func New() *Project

New creates a new Project.

func (*Project) HealthdConfig

func (p *Project) HealthdConfig() (incusURL, network string)

HealthdConfig reads the top-level x-incus-compose.healthd extension. Returns empty strings when the key is absent.

func (*Project) InstanceNames

func (p *Project) InstanceNames() []string

InstanceNames returns the Incus instance names for all services.

func (*Project) Load

func (p *Project) Load(ctx context.Context, opts ...LoadOption) (*Project, error)

Load loads a compose project with full interpolation and validation.

func (*Project) ProjectConfig

func (p *Project) ProjectConfig() map[string]string

ProjectConfig reads `x-incus` extensions from the project and returns that.

func (*Project) Resources

func (p *Project) Resources(c *client.Client, opts ...ResourcesOption) (map[string][]client.Resource, error)

Resources converts the compose project services to client resources.

func (*Project) ServiceOrder

func (p *Project) ServiceOrder(reverse bool) ([]string, error)

ServiceOrder returns the services in dependency order.

type ResourcesOption

type ResourcesOption func(o *ResourcesOptions)

ResourcesOption is a functional option for ToStack.

func ResourcesFull

func ResourcesFull() ResourcesOption

ResourcesFull fetches complete instance state including image alias and full instance details.

func ResourcesScale

func ResourcesScale(scale map[string]int) ResourcesOption

ResourcesScale sets replica count overrides for services.

type ResourcesOptions

type ResourcesOptions struct {
	Full  bool
	Scale map[string]int // service name -> replica count override
}

ResourcesOptions configures how services are converted to stack operations.