projects

package
v1.17.4 Latest Latest
Warning

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

 Go to latest Published: Apr 13, 2026 License: BSD-3-Clause Imports: 31 Imported by: 0

Documentation

Overview

Package projects provides utilities for managing Docker Compose projects and their metadata.

Index

Constants

View Source 
const (
	GlobalEnvFileName    = ".env.global"
	EffectiveEnvFileName = ".env"
	GitSourceEnvFileName = ".env.git"
	OverrideEnvFileName  = "project.env"
)
View Source 
const (
	// ArcaneIconLabel is the full reverse-DNS label key for service-level icons.
	ArcaneIconLabel = "com.getarcaneapp.arcane.icon"
)

Variables

View Source 
var ProjectFileCandidates = []string{
	"compose.yaml",
	"compose.yml",
	"docker-compose.yaml",
	"docker-compose.yml",
	"podman-compose.yaml",
	"podman-compose.yml",
	".env",
}

Functions

func BuildAdditiveOverrideEnvContent added in v1.16.3 

func BuildAdditiveOverrideEnvContent(gitContent, localContent string) (string, error)

BuildAdditiveOverrideEnvContent derives override content from a pre-git local .env file. Like other generated env helpers, the result is normalized and does not preserve comments or original key ordering.

func BuildEffectiveEnvContent added in v1.16.3 

func BuildEffectiveEnvContent(gitContent, overrideContent string) (string, error)

BuildEffectiveEnvContent merges git and override env sources into the effective .env content written to disk. The output is normalized: comments are dropped, keys are sorted, and values are rewritten with Arcane's formatter.

func BuildOverrideEnvContent added in v1.16.3 

func BuildOverrideEnvContent(gitContent, effectiveContent string) (string, error)

BuildOverrideEnvContent derives the editable override file from git-backed and effective env content. The generated output is normalized and does not retain comments or original key ordering.

func CleanupRemovedFiles added in v1.17.0 

func CleanupRemovedFiles(projectsRoot, projectPath string, oldFiles, newFiles []string) error

CleanupRemovedFiles deletes files that were in the old sync but are not in the new sync. It only removes files that were previously synced (tracked in oldFiles). Empty directories are removed after file deletion. This is a best-effort operation - errors are logged but don't cause failure.

func ComposeDown 

func ComposeDown(ctx context.Context, proj *types.Project, removeVolumes bool) error

func ComposeFileCandidates added in v1.17.1 

func ComposeFileCandidates() []string

ComposeFileCandidates returns the supported compose filenames in Arcane's detection order. A copy is returned so callers can't mutate package state.

func ComposeLogs 

func ComposeLogs(ctx context.Context, projectName string, out io.Writer, follow bool, tail string) error

func ComposePs 

func ComposePs(ctx context.Context, proj *types.Project, services []string, all bool) ([]api.ContainerSummary, error)

func ComposePull added in v1.17.0 

func ComposePull(ctx context.Context, proj *types.Project, services []string) error

func ComposeRestart 

func ComposeRestart(ctx context.Context, proj *types.Project, services []string) error

func ComposeStop added in v1.17.0 

func ComposeStop(ctx context.Context, proj *types.Project, services []string) error

func ComposeUp 

func ComposeUp(ctx context.Context, proj *types.Project, services []string, removeOrphans bool, forceRecreate bool) error

func CopyDirectoryContents added in v1.17.2 

func CopyDirectoryContents(srcDir, destDir string) error

func CreateUniqueDir added in v1.17.0 

func CreateUniqueDir(projectsRoot, basePath, name string, perm os.FileMode) (path, folderName string, err error)

CreateUniqueDir creates a unique directory within the allowed projectsRoot. It validates that the created directory is always within projectsRoot.

func DefaultSwarmStackEnvTemplate added in v1.17.0 

func DefaultSwarmStackEnvTemplate() string

func DefaultSwarmStackTemplate added in v1.17.0 

func DefaultSwarmStackTemplate() string

func DetectComposeFile 

func DetectComposeFile(dir string) (string, error)

func DirectorySyncContentsChanged added in v1.17.2 

func DirectorySyncContentsChanged(projectPath string, syncFiles []SyncFile, oldSyncedFiles []string, composeFileName string) (bool, error)

func EnsureDefaultTemplates added in v1.17.0 

func EnsureDefaultTemplates(ctx context.Context) error

func EnsureEnvFile added in v1.17.0 

func EnsureEnvFile(projectsRoot, dirPath string) error

func EnsureTemplateDir added in v1.17.0 

func EnsureTemplateDir(ctx context.Context, base string) (dir, composePath, envPath string, err error)

func GetProjectsDirectory added in v1.17.0 

func GetProjectsDirectory(ctx context.Context, projectsDir string) (string, error)

func GetTemplatesDirectory added in v1.17.0 

func GetTemplatesDirectory(ctx context.Context) (string, error)

func HasComposeRootKeysInFile added in v1.17.2 

func HasComposeRootKeysInFile(path string) (bool, error)

func ImportedComposeDescription added in v1.17.0 

func ImportedComposeDescription(dir string) string

func IsBinaryProjectFileContent added in v1.17.2 

func IsBinaryProjectFileContent(content []byte) bool

func IsProjectDirectoryEntry added in v1.17.0 

func IsProjectDirectoryEntry(entry os.DirEntry, path string, followSymlinks bool) bool

IsProjectDirectoryEntry reports whether a directory entry should be treated as a project directory. Regular directories are always accepted. Symlinked directories are accepted only when enabled.

func IsProjectDirectoryPath added in v1.17.0 

func IsProjectDirectoryPath(path string, followSymlinks bool) (bool, error)

IsProjectDirectoryPath reports whether an existing path should be treated as a project directory. Regular directories are always accepted. Symlinked directories are accepted only when enabled.

func IsProjectFile 

func IsProjectFile(filename string) bool

IsProjectFile reports whether filename is a known project file or a plausible custom YAML filename worth watching for compose discovery.

func IsSafeSubdirectory added in v1.17.0 

func IsSafeSubdirectory(baseDir, subdir string) bool

IsSafeSubdirectory returns true if subdir is a subdirectory of baseDir (absolute, normalized)

func IsWindowsDrivePath added in v1.17.0 

func IsWindowsDrivePath(path string) bool

IsWindowsDrivePath returns true if the path looks like a Windows drive path (e.g., "C:/path")

func ListGlobalComposeContainers 

func ListGlobalComposeContainers(ctx context.Context) ([]container.Summary, error)

func LoadComposeProject 

func LoadComposeProject(ctx context.Context, composeFile, projectName, projectsDirectory string, autoInjectEnv bool, pathMapper *PathMapper) (*composetypes.Project, error)

func LoadComposeProjectFromDir 

func LoadComposeProjectFromDir(ctx context.Context, dir, projectName, projectsDirectory string, autoInjectEnv bool, pathMapper *PathMapper) (*composetypes.Project, string, error)

func ParseEnvContent added in v1.17.0 

func ParseEnvContent(content string) []env.Variable

ParseEnvContent parses environment variables from .env file content

func ReadFolderComposeTemplate added in v1.17.0 

func ReadFolderComposeTemplate(baseDir, folder string) (string, *string, string, bool, error)

func ReadProjectDirectoryFiles added in v1.17.2 

func ReadProjectDirectoryFiles(projectPath string, shownFiles map[string]bool, maxDepth int, skipDirectories string) ([]project.IncludeFile, error)

func ReadProjectFiles added in v1.17.0 

func ReadProjectFiles(projectPath, composePath string) (composeContent, envContent string, err error)

func RemoveProjectFile added in v1.17.0 

func RemoveProjectFile(projectsRoot, dirPath, fileName string) error

func RemoveStaleComposeFiles added in v1.17.2 

func RemoveStaleComposeFiles(projectPath, composeFileName string, syncedFiles []string) error

func ResolveConfiguredContainerDirectory added in v1.17.0 

func ResolveConfiguredContainerDirectory(configuredPath, defaultPath string) string

func ResolveDirectoryIdentityInternal added in v1.17.0 

func ResolveDirectoryIdentityInternal(path string) (string, error)

func SanitizeProjectName added in v1.17.0 

func SanitizeProjectName(name string) string

func SaveOrUpdateProjectFiles added in v1.17.0 

func SaveOrUpdateProjectFiles(projectsRoot, projectPath, composeContent string, envContent *string) error

func Slugify added in v1.17.0 

func Slugify(in string) string

func ValidateIncludePathForWrite 

func ValidateIncludePathForWrite(projectDir, includePath string) (string, error)

ValidateIncludePathForWrite ensures the include path is safe for write operations Returns the validated absolute path to prevent recomputation after validation Only allows writing within the project directory

func WriteComposeFile added in v1.17.0 

func WriteComposeFile(projectsRoot, dirPath, content string) error

WriteComposeFile writes a compose file to the specified directory. It detects existing compose file names (docker-compose.yml, compose.yaml, etc.) and uses the existing name if found, otherwise defaults to compose.yaml projectsRoot is the allowed root directory to prevent path traversal attacks

func WriteEnvFile added in v1.17.0 

func WriteEnvFile(projectsRoot, dirPath, content string) error

WriteEnvFile writes a .env file to the specified directory projectsRoot is the allowed root directory to prevent path traversal attacks

func WriteFileWithPerm added in v1.17.0 

func WriteFileWithPerm(filePath, content string, perm os.FileMode) error

WriteFileWithPerm is a generic file writer with custom permissions

func WriteIncludeFile 

func WriteIncludeFile(projectDir, includePath, content string) error

WriteIncludeFile writes content to an include file path

func WriteProjectFile added in v1.17.0 

func WriteProjectFile(projectsRoot, dirPath, fileName, content string) error

func WriteProjectFiles added in v1.17.0 

func WriteProjectFiles(projectsRoot, dirPath, composeContent string, envContent *string) error

WriteProjectFiles writes both compose and env files to a project directory. An empty .env file is always created to prevent compose-go from failing when the compose file references env_file: .env projectsRoot is the allowed root directory to prevent path traversal attacks

func WriteSyncedDirectory added in v1.17.0 

func WriteSyncedDirectory(projectsRoot, projectPath string, files []SyncFile) ([]string, error)

WriteSyncedDirectory writes multiple files to a project directory. It validates all paths are within the project directory and creates subdirectories as needed. Returns the list of written file paths.

func WriteTemplateFile added in v1.17.0 

func WriteTemplateFile(filePath, content string) error

WriteTemplateFile writes a template file (like .compose.template or .env.template)

func WriteTemplateFiles added in v1.17.0 

func WriteTemplateFiles(composePath, envPath, composeContent, envContent string) (*string, error)

Types

type ArcaneComposeMetadata 

type ArcaneComposeMetadata struct {
	// ProjectIconURL is the URL to an icon representing the entire project.
	ProjectIconURL string
	// ProjectURLS are additional URLs related to the project (e.g., documentation, homepage).
	ProjectURLS []string
	// ServiceIcons maps service names to their respective icon identifiers or URLs.
	ServiceIcons map[string]string
}

ArcaneComposeMetadata represents Arcane-specific configuration extracted from a Compose file.

func ParseArcaneComposeMetadata 

func ParseArcaneComposeMetadata(ctx context.Context, composeFilePath, projectsDirectory string, autoInjectEnv bool) (ArcaneComposeMetadata, error)

ParseArcaneComposeMetadata reads a Docker Compose file and extracts Arcane-specific metadata. When projectsDirectory is set, Arcane's project env loading is used so .env.global is available.

func ParseArcaneComposeMetadataWithEnv 

func ParseArcaneComposeMetadataWithEnv(ctx context.Context, composeFilePath string, envMap map[string]string) (ArcaneComposeMetadata, error)

ParseArcaneComposeMetadataWithEnv reads a Docker Compose file and extracts Arcane-specific metadata using a provided environment.

type Client 

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

func NewClient 

func NewClient(ctx context.Context) (*Client, error)

func (*Client) Close 

func (c *Client) Close() error

type DiscoveredProjectDir added in v1.17.0 

type DiscoveredProjectDir struct {
	DirName string
	Path    string
}

func DiscoverProjectDirectories added in v1.17.0 

func DiscoverProjectDirectories(root string, followSymlinks bool, maxDepth int) ([]DiscoveredProjectDir, error)

type EnvLoader 

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

func NewEnvLoader 

func NewEnvLoader(projectsDir, workdir string, autoInjectEnv bool) *EnvLoader

func (*EnvLoader) LoadEnvironment 

func (l *EnvLoader) LoadEnvironment(ctx context.Context) (envMap EnvMap, injectionVars EnvMap, err error)

LoadEnvironment loads and merges environment variables from all sources: 1. Process environment 2. Global .env.global file (from projects directory) 3. Project-specific .env file (from workdir)

type EnvMap 

type EnvMap = map[string]string

func ParseProjectEnvContent added in v1.16.1 

func ParseProjectEnvContent(content string, contextEnv EnvMap) (EnvMap, error)

ParseProjectEnvContent parses project .env content from a string with variable expansion.

func ParseProjectEnvFile added in v1.16.1 

func ParseProjectEnvFile(path string, contextEnv EnvMap) (EnvMap, error)

ParseProjectEnvFile parses a project .env file with variable expansion using the provided context map (e.g. process env). Returns nil without error when the file does not exist. Only the specified file is read — global env files are intentionally not loaded here.

type IncludeFile 

type IncludeFile struct {
	Path         string `json:"path"`
	RelativePath string `json:"relative_path"`
	Content      string `json:"content"`
}

func ParseIncludes 

func ParseIncludes(composeFilePath string, envMap EnvMap, includeContent bool) ([]IncludeFile, error)

ParseIncludes reads a compose file and extracts all include directives. envMap is used to expand variables (e.g., ${VAR}) in include paths.

type PathMapper added in v1.17.0 

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

PathMapper handles translation between container and host paths

func NewPathMapper added in v1.17.0 

func NewPathMapper(containerDir, hostDir string) *PathMapper

NewPathMapper creates a new path mapper

func (*PathMapper) ContainerToHost added in v1.17.0 

func (pm *PathMapper) ContainerToHost(containerPath string) (string, error)

ContainerToHost translates a container path to host path

func (*PathMapper) IsNonMatchingMount added in v1.17.0 

func (pm *PathMapper) IsNonMatchingMount() bool

func (*PathMapper) TranslateVolumeSources added in v1.17.0 

func (pm *PathMapper) TranslateVolumeSources(project *composetypes.Project) error

TranslateVolumeSources translates all bind mount sources in a compose project

type ProgressWriterKey 

type ProgressWriterKey struct{}

ProgressWriterKey can be set on a context to enable JSON-line progress updates. The value must be an io.Writer (typically the HTTP response writer).

type ProjectEnvMode added in v1.16.3 

type ProjectEnvMode string
const (
	ProjectEnvModeDirect   ProjectEnvMode = "direct"
	ProjectEnvModeOverride ProjectEnvMode = "override"
)

type ProjectEnvState added in v1.16.3 

type ProjectEnvState struct {
	Mode             ProjectEnvMode
	EditableFileName string
	EditableContent  string
	EffectiveContent string
	DirectContent    string
	HasEffective     bool
	GitContent       string
	HasGitSource     bool
	OverrideContent  string
	HasOverride      bool
}

func ReadProjectEnvState added in v1.16.3 

func ReadProjectEnvState(projectPath string) (ProjectEnvState, error)

type SyncFile added in v1.17.0 

type SyncFile struct {
	RelativePath string // Path relative to the project directory
	Content      []byte
}

SyncFile represents a file to be written during directory sync

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.