config

package
v1.9.1 Latest Latest
Warning

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

 Go to latest Published: Aug 9, 2026 License: MIT Imports: 41 Imported by: 5

Documentation

Index

Constants

View Source 
const (
	LocalDevComposeOverrideName = "docker-compose.override.yml"
)
View Source 
const RuntimeComposeOverrideName = "docker-compose.override.yml"

Variables

View Source 
var ErrContextNotFound = errors.New("context not found")
View Source 
var ErrProjectMutationLockLost = errors.New("project mutation lock was lost")

ErrProjectMutationLockLost reports that a remote lock process exited before the holder began releasing it. Callers must stop mutating the project because subsequent operations are no longer fenced from another operator.

Functions

func AppendEnvOverrides added in v0.22.0 

func AppendEnvOverrides(base []string, values map[string]string) []string

func ConfigFilePath 

func ConfigFilePath() (string, error)

func ContextExists 

func ContextExists(name string) (bool, error)

func Current 

func Current() (string, error)

func CurrentForPlugin added in v0.17.0 

func CurrentForPlugin(pluginName string) (string, error)

func CurrentForPluginWithDiagnostics added in v0.17.0 

func CurrentForPluginWithDiagnostics(pluginName string, diagnostics io.Writer) (string, error)

func DetectComposeNetworkName added in v0.10.0 

func DetectComposeNetworkName(projectDir, composeProjectName string) string

func DetectComposeProjectName added in v0.10.0 

func DetectComposeProjectName(projectDir string) string

func DetectComposeServices added in v0.17.0 

func DetectComposeServices(projectDir string) []string

func DetectContextComposeFile added in v1.6.3 

func DetectContextComposeFile(ctx *Context) string

DetectContextComposeFile returns the first canonical Compose project file that exists for a local or remote context.

func DetectContextComposeNetwork added in v0.10.0 

func DetectContextComposeNetwork(ctx *Context) string

func DetectContextComposeProjectName added in v0.35.2 

func DetectContextComposeProjectName(ctx *Context) string

func DockerVisibleLocalPath added in v0.23.2 

func DockerVisibleLocalPath(path string) string

DockerVisibleLocalPath translates a path inside this process into the path the local Docker daemon can see when the workspace is mounted through sshfs.

func ExpandProjectDir added in v0.10.0 

func ExpandProjectDir(value string) (string, error)

func FindComposeProjectRoot added in v0.17.0 

func FindComposeProjectRoot(startDir string) string

func GetDefaultLocalDockerSocket 

func GetDefaultLocalDockerSocket(dockerSocket string) string

for local contexts, try a bunch of common paths grab the docker socket this is mostly needed for Mac OS

func GetInput 

func GetInput(question ...string) (string, error)

func IsDockerSocketAlive added in v0.9.0 

func IsDockerSocketAlive(socket string) bool

func LocalComposeHostNumericIdentity added in v1.9.0 

func LocalComposeHostNumericIdentity() (uid, gid string, available bool, err error)

LocalComposeHostNumericIdentity returns POSIX ownership for a local Compose host. Native Windows hosts report the capability as unavailable because os/user exposes SIDs rather than numeric IDs and Docker bind ownership is not represented by a meaningful local UID/GID there.

func LogDockerComposeCommand added in v1.3.0 

func LogDockerComposeCommand(ctx *Context, command string)

LogDockerComposeCommand records Compose commands at info level so normal sitectl operation also teaches operators the underlying command line.

func LooksLikeComposeProject added in v0.9.0 

func LooksLikeComposeProject(projectDir string) bool

func ProjectMutationLockContextLost added in v1.9.0 

func ProjectMutationLockContextLost(runCtx context.Context) bool

ProjectMutationLockContextLost reports whether the remote lock process for a held mutation-lock context exited unexpectedly. It remains true even when an earlier caller cancellation is already the context's cancellation cause.

func ProjectMutationLockFenceContext added in v1.9.0 

func ProjectMutationLockFenceContext(runCtx context.Context) context.Context

ProjectMutationLockFenceContext preserves lock-context values and ordinary cancellation recovery while cancelling only if the physical remote lock is lost. It is intended for rollback-capable transports that must remain usable after a caller cancels an operation.

func ResolveCurrentContextName added in v0.9.0 

func ResolveCurrentContextName(f *pflag.FlagSet) (string, error)

func ResolveCurrentContextNameForPlugin added in v0.17.0 

func ResolveCurrentContextNameForPlugin(f *pflag.FlagSet, pluginName string) (string, error)

func Save 

func Save(cfg *Config) error

func SaveContext 

func SaveContext(ctx *Context, setDefault bool) error

func SetCommandFlags 

func SetCommandFlags(flags *pflag.FlagSet)

func ValidateExistingComposeProjectDir added in v0.9.0 

func ValidateExistingComposeProjectDir(projectDir string) error

Types

type Config 

type Config struct {
	CurrentContext string    `yaml:"current-context"`
	Contexts       []Context `yaml:"contexts"`
}

func Load 

func Load() (*Config, error)

type Context 

type Context struct {
	// Name is the unique sitectl identifier selected with --context.
	Name string `yaml:"name"`
	// Site groups multiple environment contexts for the same logical site.
	Site string `yaml:"site"`
	// Plugin identifies the plugin responsible for this stack's lifecycle.
	Plugin string `yaml:"plugin"`
	// DockerHostType selects local execution or SSH-backed remote execution.
	DockerHostType ContextType `mapstructure:"type" yaml:"type"`
	// Environment distinguishes deployments of a site, such as local or prod.
	Environment string `yaml:"environment,omitempty"`
	// DockerSocket is the Unix socket Docker exposes on the target machine.
	DockerSocket string `yaml:"docker-socket"`
	// ComposeProjectName is Docker Compose's runtime project identity.
	ComposeProjectName string `yaml:"compose-project-name,omitempty"`
	// ProjectName is retained for source compatibility with older plugins.
	// Deprecated: use Site for logical identity and ComposeProjectName for the
	// Docker Compose runtime identity. This alias is never persisted.
	ProjectName string `json:"-" yaml:"-"`
	// ComposeNetwork is the primary network used to resolve stack services.
	ComposeNetwork string `yaml:"compose-network,omitempty"`
	// ProjectDir is the compose checkout path on the target machine.
	ProjectDir string `yaml:"project-dir"`
	// DrupalRootfs locates Drupal within ProjectDir for Drupal-aware plugins.
	DrupalRootfs string `yaml:"drupal-rootfs,omitempty"`
	// DrupalContainerRoot is Drupal's corresponding path inside its container.
	DrupalContainerRoot string `yaml:"drupal-container-root,omitempty"`
	// SSHUser, SSHHostname, SSHPort, and SSHKeyPath define remote transport.
	SSHUser     string `yaml:"ssh-user"`
	SSHHostname string `yaml:"ssh-hostname,omitempty"`
	SSHPort     uint   `yaml:"ssh-port,omitempty"`
	SSHKeyPath  string `yaml:"ssh-key,omitempty"`
	// EnvFile and ComposeFile select the ordered inputs passed to Compose.
	EnvFile     []string `yaml:"env-file"`
	ComposeFile []string `yaml:"compose-file,omitempty"`

	// Database fields describe the compose service and secret references used
	// by shared database jobs; they never contain the password itself.
	DatabaseService        string `yaml:"database-service,omitempty"`
	DatabaseUser           string `yaml:"database-user,omitempty"`
	DatabasePasswordSecret string `yaml:"database-password-secret,omitempty"`
	DatabaseName           string `yaml:"database-name,omitempty"`

	// ReadSmallFileFunc is an injectable runtime reader and is never persisted.
	ReadSmallFileFunc func(filename string) (string, error) `yaml:"-"`
	// Ephemeral marks discovered contexts that must not be saved implicitly.
	Ephemeral bool `yaml:"-"`

	// Extra holds plugin-specific configuration.
	// Each plugin uses its own key (e.g., "drupal", "isle", "wordpress").
	Extra map[string]yaml.Node `yaml:"extra,omitempty"`
}

func CurrentContext 

func CurrentContext(f *pflag.FlagSet) (*Context, error)

func DiscoverCurrentContext added in v0.9.0 

func DiscoverCurrentContext() (*Context, error)

func FindLocalContextByProjectDir added in v0.9.0 

func FindLocalContextByProjectDir(projectDir string) (*Context, error)

func FindLocalContextByProjectDirAndPlugin added in v0.17.0 

func FindLocalContextByProjectDirAndPlugin(projectDir, pluginName string) (*Context, error)

func GetContext 

func GetContext(name string) (Context, error)

func GetContextForPlugin added in v0.17.1 

func GetContextForPlugin(name, pluginName string) (Context, error)

func LoadFromFlags 

func LoadFromFlags(f *pflag.FlagSet, context Context) (*Context, error)

func NewLocalProjectContext added in v0.29.0 

func NewLocalProjectContext(projectDir, pluginName string) (*Context, error)

NewLocalProjectContext returns a transient local context for a Compose project directory. The returned context is not persisted to the sitectl config file and mirrors the context shape used for claimed current-directory projects.

func PromptAndSaveLocalContext added in v0.5.0 

func PromptAndSaveLocalContext(opts LocalContextCreateOptions) (*Context, error)

func (*Context) AcquireProjectMutationLock added in v1.9.0 

func (c *Context) AcquireProjectMutationLock(runCtx context.Context) (*ProjectMutationLock, error)

AcquireProjectMutationLock waits for the project-scoped operator lock. Local contexts derive the lock name from the opened directory's filesystem identity so path aliases converge, then use the platform advisory file-lock API. Remote contexts hold flock through a direct `flock ... cat` process; no inline program is evaluated. The acquisition context bounds waiting, but a successful lock remains held until Release so cancellation recovery can finish while still serialized.

func (Context) ComposePublicScheme added in v0.23.0 

func (c Context) ComposePublicScheme(defaultScheme string) string

func (Context) ComposePublishedHostPort added in v0.23.0 

func (c Context) ComposePublishedHostPort(target int) (int, bool)

func (Context) ComposeTLSProvider added in v0.23.1 

func (c Context) ComposeTLSProvider(defaultProvider string) string

func (*Context) DialSSH 

func (c *Context) DialSSH() (*ssh.Client, error)

func (Context) DockerComposeArgv added in v1.9.0 

func (c Context) DockerComposeArgv(argv []string) ([]string, bool)

DockerComposeArgv returns an argv-style Docker Compose command adjusted for the context's project directory, Compose files, environment files, and local daemon path mapping. Non-Compose argv is copied unchanged. The boolean result reports whether the resulting command is `docker compose up`.

func (Context) DockerComposeGlobalArgs added in v0.23.2 

func (c Context) DockerComposeGlobalArgs() []string

DockerComposeGlobalArgs returns docker compose options that must be inserted after "docker compose" and before the compose subcommand.

func (Context) DockerComposeGlobalArgsForCommand added in v0.23.2 

func (c Context) DockerComposeGlobalArgsForCommand(command string) []string

func (Context) DockerComposeShellCommand added in v0.23.2 

func (c Context) DockerComposeShellCommand(command string) string

DockerComposeShellCommand rewrites executable "docker compose ..." commands in a shell list so they honor the context's Compose and environment files. It also supplies daemon-visible project paths for local sshfs workspaces.

func (Context) DockerComposeSubcommandArgs added in v0.23.2 

func (c Context) DockerComposeSubcommandArgs(args []string) []string

DockerComposeSubcommandArgs returns compose subcommand arguments adjusted for the local Docker daemon path mapping.

func (Context) EffectiveComposeNetwork added in v0.10.0 

func (c Context) EffectiveComposeNetwork() string

func (Context) EffectiveComposeProjectName added in v0.10.0 

func (c Context) EffectiveComposeProjectName() string

func (*Context) EffectiveDrupalContainerRoot added in v0.13.0 

func (c *Context) EffectiveDrupalContainerRoot() string

func (*Context) EffectiveDrupalRootfs added in v0.13.0 

func (c *Context) EffectiveDrupalRootfs() string
func (c Context) EnsureTrackedComposeOverrideSymlink() error

func (*Context) FileExists added in v0.9.0 

func (c *Context) FileExists(path string) (bool, error)

func (*Context) GetSshUri added in v0.2.0 

func (c *Context) GetSshUri() string

GetSshUri returns an SSH connection URI

func (*Context) HasComposeProject added in v0.9.0 

func (c *Context) HasComposeProject() (bool, error)

func (Context) IsLocalDevelopment added in v0.22.0 

func (c Context) IsLocalDevelopment() bool

func (*Context) ListFiles added in v0.5.0 

func (c *Context) ListFiles(root string) ([]string, error)

ListFiles lists files under a directory relative to the directory root.

func (Context) MarshalYAML added in v1.3.0 

func (c Context) MarshalYAML() (any, error)

MarshalYAML writes only canonical context keys while normalizing values from callers that still populate the deprecated ProjectName field.

func (*Context) NewFileAccessor added in v0.12.0 

func (c *Context) NewFileAccessor() (*FileAccessor, error)

func (Context) OverrideEnvironment added in v0.9.0 

func (c Context) OverrideEnvironment() string

func (Context) PrepareComposeUpPortOverride added in v0.23.0 

func (c Context) PrepareComposeUpPortOverride() (map[string]string, []string, error)

func (*Context) ProjectDirExists 

func (c *Context) ProjectDirExists() (bool, error)

func (*Context) ReadFile added in v0.5.0 

func (c *Context) ReadFile(filename string) ([]byte, error)

ReadFile reads a file from the context, supporting local and remote paths.

func (*Context) ReadSmallFile 

func (c *Context) ReadSmallFile(filename string) (string, error)

func (*Context) RemoveFile added in v0.5.0 

func (c *Context) RemoveFile(filename string) error

RemoveFile removes a file from the context.

func (*Context) ResolveProjectPath added in v0.9.0 

func (c *Context) ResolveProjectPath(value string) string

func (*Context) RunCommand 

func (c *Context) RunCommand(cmd *exec.Cmd) (string, error)

func (*Context) RunCommandContext added in v0.12.0 

func (c *Context) RunCommandContext(ctx context.Context, cmd *exec.Cmd) (string, error)

func (*Context) RunQuietCommand added in v0.9.0 

func (c *Context) RunQuietCommand(cmd *exec.Cmd) (string, error)

func (*Context) RunQuietCommandContext added in v0.12.0 

func (c *Context) RunQuietCommandContext(ctx context.Context, cmd *exec.Cmd) (string, error)

func (Context) RuntimeComposeOverridePath added in v0.9.0 

func (c Context) RuntimeComposeOverridePath() string

func (Context) String 

func (context Context) String() (string, error)

func (*Context) SyncGitCheckout added in v1.9.0 

func (c *Context) SyncGitCheckout(runCtx context.Context, stdout io.Writer, branchOverride string) error

SyncGitCheckout fast-forwards the checkout from its configured upstream branch. An explicit branch is fetched from the checkout's selected remote before it is checked out. Non-Git directories and branches without an upstream are skipped only when no explicit branch was requested.

func (*Context) SyncGitRefCheckout added in v1.9.0 

func (c *Context) SyncGitRefCheckout(runCtx context.Context, stdout io.Writer, ref string) error

SyncGitRefCheckout fetches an exact remote ref (including refs/pull/* or an advertised commit) into a dedicated local ref, verifies that it resolves to a commit, and checks it out detached. It deliberately does not rewrite a configured branch or its upstream.

func (Context) TrackedComposeOverrideName added in v0.9.0 

func (c Context) TrackedComposeOverrideName() string

func (Context) TrackedComposeOverridePath added in v0.9.0 

func (c Context) TrackedComposeOverridePath() string

func (*Context) UnmarshalYAML added in v1.3.0 

func (c *Context) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML accepts the retired project-name key so existing configs keep working. Site owns logical identity and ComposeProjectName owns Compose's runtime identity, so newly saved contexts contain no duplicate project name.

func (*Context) UploadFile 

func (c *Context) UploadFile(source, destination string) error

func (*Context) ValidateComposeAccess added in v0.9.0 

func (c *Context) ValidateComposeAccess() error

func (*Context) ValidateProjectFileWrite added in v1.9.0 

func (c *Context) ValidateProjectFileWrite(projectDir, filename string) error

ValidateProjectFileWrite requires filename to remain beneath projectDir, with no existing symlink or non-directory parent and no existing symlink or non-regular target. Missing parents are allowed because WriteFile creates them, but every existing ancestor is resolved beneath the real project root.

func (*Context) ValidateProjectRegularFile added in v1.9.0 

func (c *Context) ValidateProjectRegularFile(projectDir, filename string) error

ValidateProjectRegularFile requires filename to be a regular file reached without traversing symlinks beneath the project's real root. This keeps lifecycle interpreter programs inside the checked-out project on both local and remote contexts. 

func (c Context) ValidateTrackedComposeOverrideSymlink() error

func (*Context) VerifyRemoteInput 

func (cc *Context) VerifyRemoteInput(existingSite bool) error

func (*Context) WriteFile added in v0.5.0 

func (c *Context) WriteFile(filename string, data []byte) error

WriteFile writes a file to the context, creating parent directories as needed.

func (*Context) WriteProjectFile added in v1.9.0 

func (c *Context) WriteProjectFile(projectDir, filename string, data []byte) error

WriteProjectFile validates and writes a project-owned file through the same local or remote accessor. Callers should use this instead of a lexical join followed by WriteFile when the checkout controls any parent component.

type ContextType 

type ContextType string
const (
	ContextLocal  ContextType = "local"
	ContextRemote ContextType = "remote"
)

type CurrentContextDiscovery added in v0.17.0 

type CurrentContextDiscovery struct {
	CWD               string
	ComposeProjectDir string
	Claim             *ProjectClaim
	Context           *Context
}

func DiscoverCurrentContextForPlugin added in v0.17.0 

func DiscoverCurrentContextForPlugin(requestedPlugin string) (CurrentContextDiscovery, error)

type FileAccessor added in v0.12.0 

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

func NewFileAccessor added in v0.12.0 

func NewFileAccessor(ctx *Context) (*FileAccessor, error)

func NewFileAccessorWithSSH added in v0.12.0 

func NewFileAccessorWithSSH(ctx *Context, sshClient *ssh.Client, ownsSSH bool) (*FileAccessor, error)

func (*FileAccessor) Close added in v0.12.0 

func (a *FileAccessor) Close() error

func (*FileAccessor) FileExists added in v0.12.0 

func (a *FileAccessor) FileExists(path string) (bool, error)

func (*FileAccessor) ListFiles added in v0.12.0 

func (a *FileAccessor) ListFiles(root string) ([]string, error)

func (*FileAccessor) Lstat added in v1.9.0 

func (a *FileAccessor) Lstat(path string) (fs.FileInfo, error)

func (*FileAccessor) MkdirAll added in v0.13.0 

func (a *FileAccessor) MkdirAll(path string) error

func (*FileAccessor) ReadFile added in v0.12.0 

func (a *FileAccessor) ReadFile(filename string) ([]byte, error)

func (*FileAccessor) ReadFileContext added in v0.12.0 

func (a *FileAccessor) ReadFileContext(ctx context.Context, filename string) ([]byte, error)

func (*FileAccessor) ReadFiles added in v0.12.0 

func (a *FileAccessor) ReadFiles(paths []string) (map[string][]byte, error)

func (*FileAccessor) ReadFilesContext added in v0.12.0 

func (a *FileAccessor) ReadFilesContext(ctx context.Context, paths []string) (map[string][]byte, error)

func (*FileAccessor) RealPath added in v1.9.0 

func (a *FileAccessor) RealPath(path string) (string, error)

func (*FileAccessor) RemoveAll added in v0.13.0 

func (a *FileAccessor) RemoveAll(path string) error

func (*FileAccessor) RemoveFile added in v0.12.0 

func (a *FileAccessor) RemoveFile(filename string) error

func (*FileAccessor) Stat added in v0.12.0 

func (a *FileAccessor) Stat(path string) (fs.FileInfo, error)

func (*FileAccessor) StatVFS added in v0.13.1 

func (a *FileAccessor) StatVFS(path string) (*sftp.StatVFS, error)

func (*FileAccessor) UploadFile added in v0.12.0 

func (a *FileAccessor) UploadFile(source, destination string) error

func (*FileAccessor) WriteFile added in v0.12.0 

func (a *FileAccessor) WriteFile(filename string, data []byte) error

type FileReader 

type FileReader interface {
	ReadSmallFile(path string) (string, error)
}

FileReader defines the behavior needed to read small files.

type InputFunc added in v0.5.0 

type InputFunc func(question ...string) (string, error)

type LocalContextCreateOptions added in v0.5.0 

type LocalContextCreateOptions struct {
	Name              string
	DefaultName       string
	Site              string
	DefaultSite       string
	Plugin            string
	DefaultPlugin     string
	ProjectDir        string
	DefaultProjectDir string
	// ProjectName is retained for source compatibility with older plugins.
	// Deprecated: use ComposeProjectName.
	ProjectName         string
	DefaultProjectName  string
	ComposeProjectName  string
	ComposeNetwork      string
	Environment         string
	DockerSocket        string
	DatabaseService     string
	DatabaseUser        string
	DatabaseSecret      string
	DatabaseName        string
	DrupalRootfs        string
	DrupalContainerRoot string
	SetDefault          bool
	ConfirmOverwrite    bool
	Input               InputFunc
	ProjectDirValidator func(string) error
	ContextNamePrompt   []string
	ProjectDirPrompt    []string
	OverwritePrompt     []string
}

type ProjectClaim added in v0.17.0 

type ProjectClaim struct {
	Plugin     string `yaml:"plugin"`
	ProjectDir string `yaml:"project-dir"`
	Reason     string `yaml:"reason,omitempty"`
}

type ProjectClaimDetector added in v0.17.0 

type ProjectClaimDetector func(projectDir, requestedPlugin string) (*ProjectClaim, error)

func SetProjectClaimDetector added in v0.17.0 

func SetProjectClaimDetector(detector ProjectClaimDetector) ProjectClaimDetector

type ProjectMutationLock added in v1.9.0 

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

ProjectMutationLock serializes a complete mutating operation for one Compose project. Its Context marks nested sitectl calls as already protected.

func (*ProjectMutationLock) Context added in v1.9.0 

func (l *ProjectMutationLock) Context() context.Context

func (*ProjectMutationLock) Release added in v1.9.0 

func (l *ProjectMutationLock) Release() error

Source Files

View all Source files

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.