projects

package
v2.1.0 Latest Latest
Warning

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

 Go to latest Published: Jun 19, 2026 License: BSD-3-Clause Imports: 47 Imported by: 0

Documentation

Overview

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

Index

Constants

View Source 
const (
	// ArcaneIconLabel is the full reverse-DNS label key for fallback service-level icons.
	ArcaneIconLabel = "com.getarcaneapp.arcane.icon"
	// ArcaneIconLightLabel is the full reverse-DNS label key for light service-level icons.
	ArcaneIconLightLabel = "com.getarcaneapp.arcane.icon-light"
	// ArcaneIconDarkLabel is the full reverse-DNS label key for dark service-level icons.
	ArcaneIconDarkLabel = "com.getarcaneapp.arcane.icon-dark"
)
View Source 
const (
	GlobalEnvFileName    = ".env.global"
	EffectiveEnvFileName = ".env"
	GitSourceEnvFileName = ".env.git"
	OverrideEnvFileName  = "project.env"
)
View Source 
const (
	MaxManagedProjectFileBytes  = 1024 * 1024
	ProjectFileTreeUseScanDepth = -1
)
View Source 
const DefaultComposeFileName = "compose.yaml"

DefaultComposeFileName is the compose filename Arcane writes when a project has no existing compose file.

Variables

View Source 
var (
	ErrProjectFileRevisionConflict        = errors.New("project file tree changed; refresh the project and try again")
	ErrProjectFileOutsideProjectDirectory = errors.New("path is outside project directory")
	ErrProjectFileProtectedPath           = errors.New("protected project file cannot be modified")
	ErrProjectFileSymlinkPath             = errors.New("symlink project paths are not supported")
)
View Source 
var ProjectFileCandidates = []string{
	"compose.yaml",
	"compose.yml",
	"docker-compose.yaml",
	"docker-compose.yml",
	"podman-compose.yaml",
	"podman-compose.yml",
	".env",
}

Functions

func ApplyProjectFileChanges added in v2.1.0 

func ApplyProjectFileChanges(projectPath string, changes []project.ProjectFileChange, opts ProjectFileApplyOptions) error

func ApplyProjectFileDrafts added in v2.1.0 

func ApplyProjectFileDrafts(projectPath string, drafts []project.ProjectFileDraft, opts ProjectFileApplyOptions) error

func BuildAdditiveOverrideEnvContent 

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 BuildArgsFromCompose added in v2.1.0 

func BuildArgsFromCompose(args map[string]*string) map[string]string

BuildArgsFromCompose flattens compose build args into a string map, dropping nil values.

func BuildEffectiveEnvContent 

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 BuildLocalImageTag added in v2.1.0 

func BuildLocalImageTag(projectID, projectName, serviceName string) string

BuildLocalImageTag derives a deterministic local image tag for a built service.

func BuildOverrideEnvContent 

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 BuildPlatformsFromCompose added in v2.1.0 

func BuildPlatformsFromCompose(svc composetypes.ServiceConfig) []string

BuildPlatformsFromCompose returns the build platforms for a service, falling back to the service platform when no build platforms are declared.

func CleanupRemovedFiles 

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 ComposeContentProjectName added in v2.0.3 

func ComposeContentProjectName(composeContent string) string

ComposeContentProjectName returns the normalized top-level `name:` from compose YAML content, or "" when the key is absent or unusable. Interpolated names (containing `${`) are treated as absent so the backend and the frontend name lock behave identically; parse errors are ignored here because the full compose validation reports them with proper context.

func ComposeDown 

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

func ComposeFileCandidates 

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 ComposeRestart 

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

func ComposeStop 

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 

func CopyDirectoryContents(srcDir, destDir string) error

func CreateUniqueDir 

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 

func DefaultSwarmStackEnvTemplate() string

func DefaultSwarmStackTemplate 

func DefaultSwarmStackTemplate() string

func DetectComposeFile 

func DetectComposeFile(dir string) (string, error)

func DirectorySyncContentsChanged 

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

func EnsureDefaultTemplates 

func EnsureDefaultTemplates(ctx context.Context, configuredTemplatesDir string) error

func EnsureEnvFile 

func EnsureEnvFile(projectsRoot, dirPath string) error

func EnsureTemplateDir 

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

func GetProjectsDirectory 

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

func GetTemplatesDirectory 

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

func HasComposeRootKeysInFile 

func HasComposeRootKeysInFile(path string) (bool, error)

func ImageRefsFromComposeConfigs 

func ImageRefsFromComposeConfigs(services []composetypes.ServiceConfig) []string

ImageRefsFromComposeConfigs returns unique, non-empty image references from compose service configs while preserving first-seen order.

func ImageRefsFromComposeServices 

func ImageRefsFromComposeServices(services composetypes.Services) []string

ImageRefsFromComposeServices returns unique, non-empty image references from a compose service map in stable service-name order.

func ImageRefsFromRuntimeServices 

func ImageRefsFromRuntimeServices(services []projecttypes.RuntimeService) []string

ImageRefsFromRuntimeServices returns unique, non-empty image references from runtime service DTOs while preserving first-seen order.

func ImportedComposeDescription 

func ImportedComposeDescription(dir string) string

func IsBinaryProjectFileContent 

func IsBinaryProjectFileContent(content []byte) bool

func IsProjectDirectoryEntry 

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 

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 

func IsSafeSubdirectory(baseDir, subdir string) bool

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

func IsWindowsDrivePath 

func IsWindowsDrivePath(path string) bool

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

func LabelsFromCompose added in v2.1.0 

func LabelsFromCompose(labels composetypes.Labels) map[string]string

LabelsFromCompose copies compose labels into a plain map, returning nil when empty.

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 LoadComposeProjectLenient 

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

LoadComposeProjectLenient loads a compose project tolerating undefined variables. Instead of substituting undefined ${VAR} references with an empty string (which produces invalid volume/bind specs like ":/path"), it replaces them with a placeholder value so structural validation can succeed. This is useful during GitSync validation where a .env file may not yet exist.

func MergeBuildTags added in v2.1.0 

func MergeBuildTags(primaryImage string, composeTags []string) []string

MergeBuildTags combines a primary image tag with compose tags, trimming blanks and de-duplicating while preserving order (primary first).

func MirrorDirectoryContents added in v2.0.2 

func MirrorDirectoryContents(srcDir, destDir string) error

MirrorDirectoryContents makes destDir match srcDir while updating files and directories in place, so existing inodes (and therefore container bind mounts into destDir) stay valid. Entries missing from srcDir or whose type differs are removed, then srcDir is copied over the result.

func NormalizeProjectRelativePath added in v2.1.0 

func NormalizeProjectRelativePath(input string) (string, error)

func ParseEnvContent 

func ParseEnvContent(content string) []env.Variable

ParseEnvContent parses environment variables from .env file content

func ProtectedProjectFilePaths added in v2.1.0 

func ProtectedProjectFilePaths(composeFileName string) map[string]bool

func ReadFolderComposeTemplate 

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

func ReadProjectDirectoryFiles 

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

func ReadProjectFileTree added in v2.1.0 

func ReadProjectFileTree(projectPath string, maxDepth int, skipDirectories, composeFileName string) ([]project.ProjectFile, string, error)

func ReadProjectFiles 

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

func RemoveProjectFile 

func RemoveProjectFile(projectsRoot, dirPath, fileName string) error

func RemoveStaleComposeFiles 

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

func ResolveConfiguredContainerDirectory 

func ResolveConfiguredContainerDirectory(configuredPath, defaultPath string) string

func ResolveDirectoryIdentityInternal 

func ResolveDirectoryIdentityInternal(path string) (string, error)

func ResolveHostPath added in v2.1.0 

func ResolveHostPath(mounts []HostMount, containerPath string) (string, bool)

ResolveHostPath returns the host-side path for containerPath by selecting the longest-prefix mount whose Destination contains it and appending the trailing relative segment to that mount's Source. ok is false when no mount contains the path.

func ResolveRelativeProjectPaths 

func ResolveRelativeProjectPaths(project *composetypes.Project, workdir string)

func SanitizeImageComponent added in v2.1.0 

func SanitizeImageComponent(value string) string

SanitizeImageComponent lowercases a value and replaces characters that are invalid in an image reference component with '-'.

func SanitizeProjectName 

func SanitizeProjectName(name string) string

func SaveOrUpdateProjectFiles 

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

func Slugify 

func Slugify(in string) string

func UlimitsFromCompose added in v2.1.0 

func UlimitsFromCompose(ulimits map[string]*composetypes.UlimitsConfig) map[string]string

UlimitsFromCompose renders compose ulimits as Docker-style "soft:hard" (or single) strings.

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 ValidateProjectFileName added in v2.1.0 

func ValidateProjectFileName(name string) (string, error)

func WriteComposeFile 

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 

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 

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 

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

func WriteProjectFiles 

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 

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 

func WriteTemplateFile(filePath, content string) error

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

func WriteTemplateFiles 

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

Types

type ArcaneComposeMetadata 

type ArcaneComposeMetadata struct {
	// ProjectIcon contains fallback, light, and dark icon values for the project.
	ProjectIcon IconSet
	// ProjectURLS are additional URLs related to the project (e.g., documentation, homepage).
	ProjectURLS []string
	// ServiceIconSets maps service names to their fallback, light, and dark icon values.
	ServiceIconSets map[string]IconSet
}

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 

type DiscoveredProjectDir struct {
	DirName string
	Path    string
}

func DiscoverProjectDirectories 

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 

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

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

func ParseProjectEnvFile 

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 HostMount added in v2.1.0 

type HostMount struct {
	Destination string // container-side mount path, e.g. "/app/data/projects/homeassistant"
	Source      string // host-side path, e.g. "/home/user/homeassistant"
}

HostMount is one container→host mount (bind or named volume) from Arcane's own container. It is used for longest-prefix host-path resolution in Docker-in-Docker setups, where independently bind-mounted project directories each map to their own host path rather than a single projects-root prefix.

type IconSet 

type IconSet = iconcatalog.IconSet

func FindArcaneIconSet 

func FindArcaneIconSet(labels any) IconSet

FindArcaneIconSet attempts to locate Arcane icon labels within service labels. It supports both map[string]string and []string label formats.

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.

func ParseIncludesFromContent 

func ParseIncludesFromContent(composeFilePath string, content []byte, envMap EnvMap, includeContent bool) ([]IncludeFile, error)

ParseIncludesFromContent extracts include directives from compose content using composeFilePath as the base path.

type PathMapper 

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

PathMapper handles translation between container and host paths

func NewPathMapper 

func NewPathMapper(containerDir, hostDir string) *PathMapper

NewPathMapper creates a new path mapper

func NewPathMapperFromMounts added in v2.1.0 

func NewPathMapperFromMounts(mounts []HostMount) *PathMapper

NewPathMapperFromMounts creates a path mapper that resolves each source against the given container mount table by longest-prefix match, instead of a single container→host prefix. This is used for Docker-in-Docker auto-discovery so that an independently bind-mounted project directory maps to its real host path.

func (*PathMapper) ContainerToHost 

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

ContainerToHost translates a container path to host path

func (*PathMapper) IsNonMatchingMount 

func (pm *PathMapper) IsNonMatchingMount() bool

func (*PathMapper) TranslateVolumeSources 

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 

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

type ProjectEnvState 

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 

func ReadProjectEnvState(projectPath string) (ProjectEnvState, error)

type ProjectFileApplyOptions added in v2.1.0 

type ProjectFileApplyOptions struct {
	ExpectedRevision string
	MaxDepth         int
	SkipDirectories  string
	ComposeFileName  string
}

type SyncFile 

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.