Modern Docker Management, Designed for Everyone
Go composecontainer-managementcontainersdockerdocker-composedocker-managementgoself-hostedsveltekittypescriptweb-ui
package projects
import (
"context"
"errors"
"fmt"
"log/slog"
"maps"
"os"
"path/filepath"
"regexp"
"slices"
"strconv"
"strings"
"syscall"
"time"
"github.com/compose-spec/compose-go/v2/consts"
"github.com/compose-spec/compose-go/v2/dotenv"
projecttypes "github.com/getarcaneapp/arcane/types/v2/project"
"github.com/samber/hot"
"go.getarcane.app/acfs"
kit "go.getarcane.app/kit/pkg"
"github.com/getarcaneapp/arcane/backend/v2/internal/common"
)
const (
GlobalEnvFileName = ".env.global"
EffectiveEnvFileName = ".env"
GitSourceEnvFileName = ".env.git"
OverrideEnvFileName = "project.env"
ProjectEnvModeDirect ProjectEnvMode = "direct"
ProjectEnvModeOverride ProjectEnvMode = "override"
// Docker Compose pre-defined variable names that compose-go's consts package
// does not export. See https://docs.docker.com/compose/how-tos/environment-variables/envvars.
composeEnvFilesKey = "COMPOSE_ENV_FILES"
composeRemoveOrphansKey = "COMPOSE_REMOVE_ORPHANS"
composeIgnoreOrphansKey = "COMPOSE_IGNORE_ORPHANS"
composeParallelLimitKey = "COMPOSE_PARALLEL_LIMIT"
defaultComposePathSeparator = ":"
)
type EnvMap = map[string]string
type ProjectEnvMode string
type ProjectEnvState struct {
Mode ProjectEnvMode
EditableFileName string
EditableContent string
EffectiveContent string
DirectContent string
GitContent string
OverrideContent string
HasEffective bool
HasGitSource bool
HasOverride bool
// The *Unreadable fields report a file that exists on disk but could not be
// read because of a permission error (e.g. a chmod 000 or foreign-owned
// file reachable through a bind mount). Such a file is treated as absent
// for merge purposes, and callers persisting env state must not attempt to
// write or remove it — its contents are unknown, so writing could either
// fail (bricking the caller) or silently clobber operator intent.
EffectiveUnreadable bool
GitSourceUnreadable bool
OverrideUnreadable bool
}
type EnvLoader struct {
projectsDir string
workdir string
autoInjectEnv bool
}
type envFileCacheEntry struct {
path string
mtime time.Time
size int64
exists bool
values EnvMap
}
var (
globalEnvFileCache = hot.NewHotCache[string, envFileCacheEntry](hot.LRU, 4096).Build()
projectEnvFileCache = hot.NewHotCache[string, envFileCacheEntry](hot.LRU, 4096).Build()
)
func NewEnvLoader(projectsDir, workdir string, autoInjectEnv bool) *EnvLoader {
return &EnvLoader{
projectsDir: projectsDir,
workdir: workdir,
autoInjectEnv: autoInjectEnv,
}
}
// processEnvAllowlist is the only part of Arcane's own process environment
// that flows into compose interpolation of managed projects: timezone and
// locale, whose container values are safe to share. Everything else is
// excluded so Arcane's variables never leak into ${VAR} references or
// pass-through environment entries — its PORT collides with project port
// mappings, secrets would be readable from any compose file, and vars like
// HOME or PUID carry container-internal values that are wrong for projects.
var processEnvAllowlist = []string{"TZ", "LANG", "LANGUAGE", "LC_ALL"}
func allowedProcessEnvInternal() EnvMap {
envMap := make(EnvMap)
for _, key := range processEnvAllowlist {
if val, ok := os.LookupEnv(key); ok {
envMap[key] = val
}
}
return envMap
}
// LoadEnvironment loads and merges environment variables from all sources:
// 1. Allowlisted process environment (TZ)
// 2. Global .env.global file (from projects directory)
// 3. Project-specific .env file (from workdir)
// The rest of the Arcane process environment is intentionally excluded so its
// own variables never leak into compose interpolation of managed projects.
func (l *EnvLoader) LoadEnvironment(ctx context.Context) (envMap, injectionVars EnvMap, err error) {
envMap = allowedProcessEnvInternal()
injectionVars = make(EnvMap)
if strings.TrimSpace(l.projectsDir) != "" {
globalEnvPath := filepath.Join(l.projectsDir, GlobalEnvFileName)
if loadAndMergeGlobalEnvErr := l.loadAndMergeGlobalEnv(ctx, globalEnvPath, envMap, injectionVars); loadAndMergeGlobalEnvErr != nil && !errors.Is(loadAndMergeGlobalEnvErr, os.ErrNotExist) {
slog.WarnContext(ctx, "Failed to load global env", "path", globalEnvPath, "error", loadAndMergeGlobalEnvErr)
}
}
// COMPOSE_DISABLE_ENV_FILE skips the project .env entirely, as `docker
// compose` does. It is read from the sources merged so far — in practice
// only .env.global, since the process-env allowlist never includes
// COMPOSE_* variables.
if parseComposeBoolInternal(envMap, consts.ComposeDisableDefaultEnvFile) {
slog.DebugContext(ctx, "COMPOSE_DISABLE_ENV_FILE set; skipping project .env", "workdir", l.workdir)
} else {
projectEnvPath := filepath.Join(l.workdir, EffectiveEnvFileName)
if loadAndMergeProjectEnvErr := l.loadAndMergeProjectEnv(ctx, projectEnvPath, envMap, injectionVars); loadAndMergeProjectEnvErr != nil {
switch {
case errors.Is(loadAndMergeProjectEnvErr, os.ErrNotExist):
slog.DebugContext(ctx, "Project .env file does not exist", "path", projectEnvPath)
case errors.Is(loadAndMergeProjectEnvErr, os.ErrPermission):
return envMap,
injectionVars,
common.Classify(common.ErrProjectEnvUnreadable,
fmt.Errorf("%s is not readable by the runtime user (uid %d, gid %d); fix its ownership/read permission or set PUID/PGID to a user that can read it: %w",
projectEnvPath,
os.Geteuid(),
os.Getegid(),
loadAndMergeProjectEnvErr))
default:
slog.WarnContext(ctx, "Failed to load project env", "path", projectEnvPath, "error", loadAndMergeProjectEnvErr)
}
}
}
// COMPOSE_ENV_FILES, when declared, layers additional env files on top of
// the project .env (later entries win). Reuses the mtime-keyed cache.
l.mergeComposeEnvFilesInternal(ctx, envMap, injectionVars)
return envMap, injectionVars, nil
}
func (l *EnvLoader) mergeComposeEnvFilesInternal(ctx context.Context, envMap, injectionVars EnvMap) {
parse := func(path string, contextEnv EnvMap) (EnvMap, error) {
key := strings.Join([]string{path, l.projectsDir, strconv.FormatBool(l.autoInjectEnv), strconv.FormatUint(kit.Fingerprint(contextEnv), 16)}, "\x00")
entry, err := loadCachedEnvFileInternal(ctx, projectEnvFileCache, key, path, contextEnv)
if err != nil {
return nil, err
}
return kit.Ternary(!entry.exists, nil, entry.values), nil
}
onMerged := func(values EnvMap) {
if l.autoInjectEnv {
maps.Copy(injectionVars, values)
}
}
mergeComposeEnvFilesInternal(ctx, l.workdir, envMap, parse, onMerged)
}
func (l *EnvLoader) loadAndMergeGlobalEnv(ctx context.Context, path string, envMap, injectionVars EnvMap) error {
entry, err := loadCachedEnvFileInternal(ctx, globalEnvFileCache, path, path, envMap)
if err != nil {
return err
}
if !entry.exists {
return os.ErrNotExist
}
for k, v := range entry.values {
envMap[k] = v
injectionVars[k] = v
}
slog.DebugContext(ctx, "Merged global env into environment map", "totalEnvCount", len(envMap))
return nil
}
func (l *EnvLoader) loadAndMergeProjectEnv(ctx context.Context, path string, envMap, injectionVars EnvMap) error {
key := strings.Join([]string{path, l.projectsDir, strconv.FormatBool(l.autoInjectEnv), strconv.FormatUint(kit.Fingerprint(envMap), 16)}, "\x00")
entry, err := loadCachedEnvFileInternal(ctx, projectEnvFileCache, key, path, envMap)
if err != nil {
return err
}
if !entry.exists {
return os.ErrNotExist
}
for k, v := range entry.values {
envMap[k] = v
if l.autoInjectEnv {
injectionVars[k] = v
}
}
slog.DebugContext(ctx, "Merged project .env into environment map", "totalEnvCount", len(envMap))
return nil
}
func loadCachedEnvFileInternal(_ context.Context, envCache *hot.HotCache[string, envFileCacheEntry], key, path string, contextEnv EnvMap) (envFileCacheEntry, error) {
if cached, ok := envCache.Peek(key); ok {
if validEnvFileCacheEntryInternal(cached) {
return cached, nil
}
envCache.Delete(key)
}
entry, found, err := envCache.GetWithLoaders(key, func(_ []string) (map[string]envFileCacheEntry, error) {
// Stays on os.*: env files may be symlinks resolving outside any
// confinement root (a supported setup), which acfs cannot follow.
info, err := os.Stat(path)
if err != nil {
if errors.Is(err, os.ErrNotExist) {
return map[string]envFileCacheEntry{key: {path: path}}, nil
}
return nil, err
}
if info.IsDir() {
return nil, fmt.Errorf("path is a directory: %s", path)
}
parsed, err := parseProjectEnvFileExistingInternal(path, contextEnv)
if err != nil {
return nil, fmt.Errorf("parse env file: %w", err)
}
return map[string]envFileCacheEntry{key: {
path: path,
mtime: info.ModTime(),
size: info.Size(),
exists: true,
values: parsed,
}}, nil
})
if err != nil {
return envFileCacheEntry{}, err
}
if !found {
return envFileCacheEntry{}, errors.New("environment file cache loader returned no entry")
}
return entry, nil
}
func validEnvFileCacheEntryInternal(entry envFileCacheEntry) bool {
// os.Stat rather than acfs: env files may be symlinks resolving outside
// any confinement root (a supported setup).
info, err := os.Stat(entry.path)
if err != nil {
return !entry.exists && errors.Is(err, os.ErrNotExist)
}
if info.IsDir() {
return false
}
if !entry.exists || !info.ModTime().Equal(entry.mtime) || info.Size() != entry.size {
return false
}
// A chmod does not bump mtime, so confirm the file is still readable.
file, err := os.Open(entry.path)
if err != nil {
return false
}
return file.Close() == nil
}
func parseProjectEnvFileExistingInternal(path string, contextEnv EnvMap) (EnvMap, error) {
content, err := os.ReadFile(path)
if err != nil {
return nil, fmt.Errorf("read file: %w", err)
}
return ParseProjectEnvContent(string(content), contextEnv)
}
// 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.
//
// Stays on os.*: env files may be symlinks resolving outside any confinement
// root (a supported setup), which acfs cannot follow.
func ParseProjectEnvFile(path string, contextEnv EnvMap) (EnvMap, error) {
info, err := os.Stat(path)
if err != nil || info.IsDir() {
return nil, nil //nolint:nilerr // missing .env is not an error
}
return parseProjectEnvFileExistingInternal(path, contextEnv)
}
// ParseProjectEnvContent parses project .env content from a string using
// compose-go's dotenv parser with variable expansion. Lookups resolve from
// contextEnv (previously loaded vars) only; the Arcane process environment is
// intentionally never consulted so its variables don't leak into project env.
func ParseProjectEnvContent(content string, contextEnv EnvMap) (EnvMap, error) {
lookupFn := func(key string) (string, bool) {
val, ok := contextEnv[key]
return val, ok
}
envMap, err := dotenv.ParseWithLookup(strings.NewReader(content), lookupFn)
if err != nil {
return nil, fmt.Errorf("parse env: %w", err)
}
return envMap, nil
}
// WithTransientValidationEnvFile temporarily writes a project .env file while
// running compose validation, then restores the original file state.
func WithTransientValidationEnvFile(ctx context.Context, projectPath string, effectiveEnvContent *string, run func() error) (err error) {
// Read through os rather than the root-confined API: a project .env is
// allowed to be a symlink whose target lives outside the project directory,
// and that write-through is deliberately preserved (#3556).
originalContent, readErr := os.ReadFile(filepath.Join(projectPath, ".env"))
originalExists := readErr == nil
if readErr != nil && !os.IsNotExist(readErr) {
if !errors.Is(readErr, os.ErrPermission) && !errors.Is(readErr, syscall.EISDIR) {
return fmt.Errorf("prepare env file for compose validation: %w", readErr)
}
// The path exists but is permission-locked (e.g. chmod 000, foreign-owned) or a directory.
// Its contents can't be verified or safely overwritten, so leave it
// untouched and validate against whatever's already on disk instead of
// aborting the whole update.
slog.WarnContext(ctx, "skipping unreadable .env during compose validation; leaving it untouched", "projectPath", projectPath, "error", readErr)
if run == nil {
return nil
}
return run()
}
contentMatches := effectiveEnvContent != nil && originalExists && string(originalContent) == *effectiveEnvContent
shouldWrite := !contentMatches && (effectiveEnvContent != nil || !originalExists)
if shouldWrite {
content := ""
if effectiveEnvContent != nil {
content = *effectiveEnvContent
}
if writeErr := WriteProjectFile(ctx, projectPath, projectPath, ".env", content); writeErr != nil {
return fmt.Errorf("prepare env file for compose validation: %w", writeErr)
}
defer func() {
var restoreErr error
switch {
case originalExists:
restoreErr = WriteProjectFile(ctx, projectPath, projectPath, ".env", string(originalContent))
default:
restoreErr = acfs.Remove(ctx, projectPath, "/.env")
}
if restoreErr != nil && !os.IsNotExist(restoreErr) {
if err == nil {
err = fmt.Errorf("restore env file after compose validation: %w", restoreErr)
}
}
}()
}
if run == nil {
return nil
}
return run()
}
// BuildEffectiveEnvContent merges git and override env sources into the effective
// .env content written to disk. Keys present in both layers are rewritten in place
// on the Git line, preserving ordering and inline comments; override-only keys are
// appended after the Git content. When the in-place rewrite cannot be verified to
// parse identically to plain concatenation (e.g. multiline values), the override
// is appended verbatim instead so duplicate keys resolve to the override value.
func BuildEffectiveEnvContent(gitContent, overrideContent string) (string, error) {
contextEnv := make(EnvMap)
gitEnv, err := ParseProjectEnvContent(gitContent, contextEnv)
if err != nil {
return "", fmt.Errorf("parse git env content: %w", err)
}
maps.Copy(contextEnv, gitEnv)
overrideEnv, err := ParseProjectEnvContent(overrideContent, contextEnv)
if err != nil {
return "", fmt.Errorf("parse override env content: %w", err)
}
switch {
case gitContent == "":
return overrideContent, nil
case overrideContent == "":
return gitContent, nil
}
separated := strings.HasSuffix(gitContent, "\n") || strings.HasPrefix(overrideContent, "\n")
concatenated := kit.Ternary(separated, gitContent+overrideContent, gitContent+"\n"+overrideContent)
candidate, ok := mergeEnvOverridesInPlaceInternal(gitContent, overrideContent, overrideEnv)
if !ok {
return concatenated, nil
}
candidateEnv, candidateErr := ParseProjectEnvContent(candidate, make(EnvMap))
expectedEnv, expectedErr := ParseProjectEnvContent(concatenated, make(EnvMap))
if candidateErr == nil && expectedErr == nil && maps.Equal(candidateEnv, expectedEnv) {
return candidate, nil
}
return concatenated, nil
}
// EnvContentChanged reports whether two env contents differ semantically,
// ignoring ordering and comments. Unparseable content is compared verbatim.
func EnvContentChanged(oldContent, newContent string) bool {
oldEnv, oldErr := ParseProjectEnvContent(oldContent, nil)
newEnv, newErr := ParseProjectEnvContent(newContent, nil)
if oldErr != nil || newErr != nil {
return oldContent != newContent
}
return !maps.Equal(oldEnv, newEnv)
}
var envKeyLineRegexInternal = regexp.MustCompile(`^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_.-]*)(\s*=)(.*)$`)
// mergeEnvOverridesInPlaceInternal rewrites the value of every gitContent line
// whose key has an override — keeping line order and trailing inline comments —
// then appends the override lines whose keys were not rewritten. ok is false when
// no git line matched an override and the caller should fall back to plain
// concatenation.
func mergeEnvOverridesInPlaceInternal(gitContent, overrideContent string, overrideEnv EnvMap) (merged string, ok bool) {
rewritten := make(map[string]struct{})
gitLines := strings.Split(gitContent, "\n")
for i, line := range gitLines {
body, hadCR := strings.CutSuffix(line, "\r")
match := envKeyLineRegexInternal.FindStringSubmatch(body)
if match == nil {
continue
}
overrideValue, exists := overrideEnv[match[2]]
if !exists {
continue
}
value, comment := splitEnvValueCommentInternal(match[4])
separator := value[len(strings.TrimRight(value, " \t")):]
if comment != "" && separator == "" {
separator = " "
}
body = match[1] + match[2] + match[3] + formatEnvValueInternal(overrideValue) + separator + comment
if hadCR {
body += "\r"
}
gitLines[i] = body
rewritten[match[2]] = struct{}{}
}
if len(rewritten) == 0 {
return "", false
}
remainderLines := make([]string, 0)
for line := range strings.SplitSeq(overrideContent, "\n") {
if match := envKeyLineRegexInternal.FindStringSubmatch(strings.TrimSuffix(line, "\r")); match != nil {
if _, drop := rewritten[match[2]]; drop {
continue
}
}
remainderLines = append(remainderLines, line)
}
merged = strings.Join(gitLines, "\n")
remainder := strings.Join(remainderLines, "\n")
switch {
case strings.TrimSpace(remainder) == "":
return merged, true
case strings.HasSuffix(merged, "\n"), strings.HasPrefix(remainder, "\n"):
return merged + remainder, true
default:
return merged + "\n" + remainder, true
}
}
// splitEnvValueCommentInternal splits a raw single-line env value into the value
// part and a trailing inline comment. A comment starts at an unquoted '#' that is
// at the start of the value or preceded by whitespace.
func splitEnvValueCommentInternal(raw string) (value, comment string) {
var quote byte
for i := 0; i < len(raw); i++ {
c := raw[i]
switch {
case quote != 0:
if c == quote {
quote = 0
} else if c == '\\' && quote == '"' {
i++
}
case c == '\'' || c == '"':
quote = c
case c == '#' && (i == 0 || raw[i-1] == ' ' || raw[i-1] == '\t'):
return raw[:i], raw[i:]
}
}
return raw, ""
}
// 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 BuildAdditiveOverrideEnvContent(gitContent, localContent string) (string, error) {
contextEnv := make(EnvMap)
gitEnv, err := ParseProjectEnvContent(gitContent, contextEnv)
if err != nil {
return "", fmt.Errorf("parse git env content: %w", err)
}
maps.Copy(contextEnv, gitEnv)
localEnv, err := ParseProjectEnvContent(localContent, contextEnv)
if err != nil {
return "", fmt.Errorf("parse local env content: %w", err)
}
override := make(EnvMap)
for key, value := range localEnv {
if _, exists := gitEnv[key]; !exists {
override[key] = value
}
}
return formatEnvMapInternal(override), nil
}
// BuildOverrideEnvContent derives the editable override file from git-backed and
// effective env content. Content that already contains only real overrides is
// returned verbatim; derived or cleaned output uses Arcane's canonical format.
func BuildOverrideEnvContent(gitContent, effectiveContent string) (string, error) {
contextEnv := make(EnvMap)
gitEnv, err := ParseProjectEnvContent(gitContent, contextEnv)
if err != nil {
return "", fmt.Errorf("parse git env content: %w", err)
}
maps.Copy(contextEnv, gitEnv)
effectiveEnv, err := ParseProjectEnvContent(effectiveContent, contextEnv)
if err != nil {
return "", fmt.Errorf("parse effective env content: %w", err)
}
override := make(EnvMap)
for key, value := range effectiveEnv {
gitValue, exists := gitEnv[key]
switch {
case !exists:
override[key] = value
case value == "":
// Empty values for Git-backed keys are treated as deleting the local override,
// so the Git value is restored on the next effective merge.
continue
case gitValue != value:
override[key] = value
}
}
if maps.Equal(effectiveEnv, override) {
return effectiveContent, nil
}
return formatEnvMapInternal(override), nil
}
// CheckProjectEnvAccess reports a configuration error when the runtime user
// lacks permission to open dir's .env or traverse its path.
func CheckProjectEnvAccess(ctx context.Context, projectsDir, dir string) *projecttypes.ConfigurationError {
envPath := filepath.Join(dir, EffectiveEnvFileName)
file, err := os.Open(envPath)
if err == nil {
if closeErr := file.Close(); closeErr != nil {
slog.WarnContext(ctx, "failed to close project env access probe", "path", envPath, "error", closeErr)
}
return nil
}
if !errors.Is(err, os.ErrPermission) {
return nil
}
disabled := false
if strings.TrimSpace(projectsDir) != "" {
globalEnv, globalErr := ParseProjectEnvFile(filepath.Join(projectsDir, GlobalEnvFileName), make(EnvMap))
if globalErr != nil {
slog.DebugContext(ctx, "Failed to read global env while checking project env access", "path", projectsDir, "error", globalErr)
} else {
disabled = parseComposeBoolInternal(globalEnv, consts.ComposeDisableDefaultEnvFile)
}
}
return &projecttypes.ConfigurationError{
Code: common.ConfigurationErrorCodeEnvFileUnreadable,
Path: envPath,
UID: os.Geteuid(),
GID: os.Getegid(),
BlocksOperations: !disabled,
}
}
func ReadProjectEnvState(projectPath string) (ProjectEnvState, error) {
effectiveContent, hasEffective, effectiveUnreadable, err := readOptionalProjectFileInternal(projectPath, EffectiveEnvFileName)
if err != nil {
return ProjectEnvState{}, err
}
gitContent, hasGitSource, gitSourceUnreadable, err := readOptionalProjectFileInternal(projectPath, GitSourceEnvFileName)
if err != nil {
return ProjectEnvState{}, err
}
overrideContent, hasOverride, overrideUnreadable, err := readOptionalProjectFileInternal(projectPath, OverrideEnvFileName)
if err != nil {
return ProjectEnvState{}, err
}
if effectiveUnreadable || gitSourceUnreadable || overrideUnreadable {
ctx := context.Background() //nolint:forbidigo // Compose environment parsing is a pure helper without a request context.
slog.WarnContext(ctx, "skipping unreadable project env file(s); leaving them untouched",
"projectPath", projectPath,
"effectiveUnreadable", effectiveUnreadable,
"gitSourceUnreadable", gitSourceUnreadable,
"overrideUnreadable", overrideUnreadable,
)
}
state := ProjectEnvState{
DirectContent: effectiveContent,
EffectiveContent: effectiveContent,
HasEffective: hasEffective,
EffectiveUnreadable: effectiveUnreadable,
GitContent: gitContent,
HasGitSource: hasGitSource,
GitSourceUnreadable: gitSourceUnreadable,
OverrideContent: overrideContent,
HasOverride: hasOverride,
OverrideUnreadable: overrideUnreadable,
}
if hasGitSource || hasOverride {
state.Mode = ProjectEnvModeOverride
state.EditableFileName = OverrideEnvFileName
state.EditableContent = overrideContent
if !hasEffective {
mergedContent, mergeErr := BuildEffectiveEnvContent(gitContent, overrideContent)
if mergeErr != nil {
return ProjectEnvState{}, mergeErr
}
state.EffectiveContent = mergedContent
}
return state, nil
}
state.Mode = ProjectEnvModeDirect
state.EditableFileName = EffectiveEnvFileName
state.EditableContent = effectiveContent
return state, nil
}
// WriteManagedEnvFile writes (or, for project.env, removes) one of the three
// env-merge bookkeeping files — fileName must be EffectiveEnvFileName,
// GitSourceEnvFileName, or OverrideEnvFileName. If the existing path is
// unreadable (permission-locked or a directory), the write is skipped and a
// warning logged instead: its contents can't be verified, and such a path is
// typically unwritable too, so attempting the write would abort the whole caller.
func WriteManagedEnvFile(ctx context.Context, projectsDirectory, projectPath, fileName string, unreadable bool, content string) error {
if unreadable {
slog.WarnContext(ctx, "skipping unreadable project env file; leaving it untouched", "projectPath", projectPath, "file", fileName)
return nil
}
switch fileName {
case EffectiveEnvFileName:
return WriteProjectFile(ctx, projectsDirectory, projectPath, ".env", content)
case GitSourceEnvFileName:
return WriteProjectFile(ctx, projectsDirectory, projectPath, GitSourceEnvFileName, content)
case OverrideEnvFileName:
if strings.TrimSpace(content) == "" {
return RemoveProjectFile(ctx, projectsDirectory, projectPath, OverrideEnvFileName)
}
return WriteProjectFile(ctx, projectsDirectory, projectPath, OverrideEnvFileName, content)
default:
return fmt.Errorf("write managed env file: unsupported file name %q", fileName)
}
}
// readOptionalProjectFileInternal reads fileName from projectPath. A missing
// file is reported via exists=false with no error. A permission error or a
// directory at the path is reported via unreadable=true with no error: its
// contents cannot be verified, so callers must treat it as absent for merge
// purposes and must not attempt to overwrite or remove it. Any other I/O
// error is still returned as a hard failure.
// A project env file may itself be a symlink whose target lives outside the
// project directory, so the read goes through os rather than the root-confined
// API — the same deliberate exception the .env write path makes (#3556).
func readOptionalProjectFileInternal(projectPath, fileName string) (content string, exists, unreadable bool, err error) {
raw, readErr := os.ReadFile(filepath.Join(projectPath, fileName))
if readErr == nil {
return string(raw), true, false, nil
}
if errors.Is(readErr, os.ErrNotExist) {
return "", false, false, nil
}
if errors.Is(readErr, os.ErrPermission) || errors.Is(readErr, syscall.EISDIR) {
return "", false, true, nil
}
return "", false, false, fmt.Errorf("read %s: %w", fileName, readErr)
}
// formatEnvMapInternal serializes env maps into Arcane's canonical generated
// format. This is intentionally lossy: comments are omitted and keys are sorted
// alphabetically to keep persisted merge output stable.
func formatEnvMapInternal(envMap EnvMap) string {
if len(envMap) == 0 {
return ""
}
keys := slices.Sorted(maps.Keys(envMap))
var builder strings.Builder
for _, key := range keys {
builder.WriteString(key)
builder.WriteByte('=')
builder.WriteString(formatEnvValueInternal(envMap[key]))
builder.WriteByte('\n')
}
return builder.String()
}
func formatEnvValueInternal(value string) string {
if value == "" {
return value
}
value = strings.ReplaceAll(value, "$", "$$")
needsQuotes := strings.ContainsAny(value, " \t\r\n#\"'") || strings.TrimSpace(value) != value
if !needsQuotes {
return value
}
escaped := strings.NewReplacer(
"\\", "\\\\",
`"`, `\"`,
"\t", `\t`,
"\n", `\n`,
"\r", `\r`,
).Replace(value)
return `"` + escaped + `"`
}
// ComposeEnvOptions holds the deployment-relevant Docker Compose pre-defined
// environment variables parsed from a project's merged environment.
type ComposeEnvOptions struct {
// ConfigFiles is the resolved, absolute COMPOSE_FILE selection in order (the
// first entry is the base file). Nil when COMPOSE_FILE is unset.
ConfigFiles []string
// Profiles is the COMPOSE_PROFILES selection.
Profiles []string
// ProjectName is COMPOSE_PROJECT_NAME (not normalized).
ProjectName string
// EnvFiles is the resolved, absolute COMPOSE_ENV_FILES selection in order.
EnvFiles []string
// RemoveOrphans is COMPOSE_REMOVE_ORPHANS.
RemoveOrphans bool
// IgnoreOrphans is COMPOSE_IGNORE_ORPHANS.
IgnoreOrphans bool
// ParallelLimit is COMPOSE_PARALLEL_LIMIT; 0 means unset.
ParallelLimit int
}
// ParseComposeEnvOptions extracts the deployment-relevant COMPOSE_* variables
// from an already-merged environment map. Malformed path selections return a
// classified common.ErrComposeFileEnvInvalid; malformed scalars are ignored
// with a debug log, matching `docker compose`'s tolerance.
func ParseComposeEnvOptions(workdir string, env EnvMap) (ComposeEnvOptions, error) {
opts := ComposeEnvOptions{
ProjectName: strings.TrimSpace(env[consts.ComposeProjectName]),
}
files, err := resolveComposeFileSelectionInternal(workdir, env)
if err != nil {
return ComposeEnvOptions{}, err
}
opts.ConfigFiles = files
if raw := strings.TrimSpace(env[consts.ComposeProfiles]); raw != "" {
opts.Profiles = kit.TrimNonEmpty(strings.Split(raw, ","))
}
for _, entry := range ComposeEnvFileEntriesFromEnv(env) {
resolved, resErr := ResolvePathWithinDir(workdir, entry)
if resErr != nil {
return ComposeEnvOptions{}, common.Classify(common.ErrComposeFileEnvInvalid, fmt.Errorf("COMPOSE_ENV_FILES entry %q: %w", entry, resErr))
}
opts.EnvFiles = append(opts.EnvFiles, resolved)
}
opts.RemoveOrphans = parseComposeBoolInternal(env, composeRemoveOrphansKey)
opts.IgnoreOrphans = parseComposeBoolInternal(env, composeIgnoreOrphansKey)
if raw := strings.TrimSpace(env[composeParallelLimitKey]); raw != "" {
if n, convErr := strconv.Atoi(raw); convErr == nil && n > 0 {
opts.ParallelLimit = n
} else {
slog.DebugContext(context.Background(), "ignoring invalid COMPOSE_PARALLEL_LIMIT", "value", raw) //nolint:forbidigo // Compose environment parsing is a pure helper without a request context.
}
}
return opts, nil
}
// ComposeFileEnvSelection resolves the COMPOSE_FILE selection for dir with the
// same layering EnvLoader.LoadEnvironment uses at deployment: .env.global from
// projectsDir first, the project .env on top, then any COMPOSE_ENV_FILES
// entries. Returns nil when the merged environment does not set COMPOSE_FILE.
// COMPOSE_DISABLE_ENV_FILE (declared in .env.global) skips the project .env, as
// `docker compose` does; a global COMPOSE_FILE still applies. An empty
// projectsDir skips the global layer.
func ComposeFileEnvSelection(ctx context.Context, projectsDir, dir string) ([]string, error) {
envMap := make(EnvMap)
if strings.TrimSpace(projectsDir) != "" {
globalEnvPath := filepath.Join(projectsDir, GlobalEnvFileName)
globalEnv, err := loadCachedEnvFileInternal(ctx, globalEnvFileCache, globalEnvPath+"\x00compose-file-selection", globalEnvPath, envMap)
if err != nil {
return nil, err
}
maps.Copy(envMap, globalEnv.values)
}
// COMPOSE_DISABLE_ENV_FILE skips the project .env; it is read only from the
// sources merged so far (.env.global), matching LoadEnvironment.
if !parseComposeBoolInternal(envMap, consts.ComposeDisableDefaultEnvFile) {
projectEnvPath := filepath.Join(dir, EffectiveEnvFileName)
projectEnv, err := ParseProjectEnvFile(projectEnvPath, envMap)
if err != nil {
if errors.Is(err, os.ErrPermission) {
return nil,
common.Classify(common.ErrProjectEnvUnreadable,
fmt.Errorf("%s is not readable by the runtime user (uid %d, gid %d); fix its ownership/read permission or set PUID/PGID to a user that can read it: %w",
projectEnvPath,
os.Geteuid(),
os.Getegid(),
err))
}
return nil, err
}
maps.Copy(envMap, projectEnv)
}
if len(envMap) == 0 {
return nil, nil
}
mergeComposeEnvFilesInternal(ctx, dir, envMap, ParseProjectEnvFile, nil)
return resolveComposeFileSelectionInternal(dir, envMap)
}
// ComposeFileEntriesFromEnv returns the raw COMPOSE_FILE entries declared in env
// (split on COMPOSE_PATH_SEPARATOR, ":" by default), or nil when unset. Entries
// are not resolved, validated, or stat'd.
func ComposeFileEntriesFromEnv(env EnvMap) []string {
raw, ok := env[consts.ComposeFilePath]
if !ok || strings.TrimSpace(raw) == "" {
return nil
}
separator := defaultComposePathSeparator
if custom := strings.TrimSpace(env[consts.ComposePathSeparator]); custom != "" {
separator = custom
}
return kit.TrimNonEmpty(strings.Split(raw, separator))
}
// ComposeEnvFileEntriesFromEnv returns the raw COMPOSE_ENV_FILES entries
// declared in env (comma-separated), or nil when unset. Entries are not
// resolved, validated, or stat'd.
func ComposeEnvFileEntriesFromEnv(env EnvMap) []string {
raw := strings.TrimSpace(env[composeEnvFilesKey])
if raw == "" {
return nil
}
return kit.TrimNonEmpty(strings.Split(raw, ","))
}
// resolveComposeFileSelectionInternal parses COMPOSE_FILE from env into an
// ordered list of absolute compose-file paths, or nil when COMPOSE_FILE is
// unset. Every entry must be a relative path to an existing file within
// workdir; the first entry (the base file) must sit directly in workdir.
func resolveComposeFileSelectionInternal(workdir string, env EnvMap) ([]string, error) {
entries := ComposeFileEntriesFromEnv(env)
if len(entries) == 0 {
return nil, nil
}
absWorkdir, err := filepath.Abs(filepath.Clean(workdir))
if err != nil {
return nil, common.Classify(common.ErrComposeFileEnvInvalid, fmt.Errorf("resolve project directory: %w", err))
}
files := make([]string, 0, len(entries))
for i, entry := range entries {
if filepath.IsAbs(entry) {
return nil, common.Classify(common.ErrComposeFileEnvInvalid, fmt.Errorf("COMPOSE_FILE entry %q must be relative to the project directory", entry))
}
resolved, resErr := ResolvePathWithinDir(absWorkdir, entry)
if resErr != nil {
return nil, common.Classify(common.ErrComposeFileEnvInvalid, fmt.Errorf("COMPOSE_FILE entry %q: %w", entry, resErr))
}
if i == 0 && filepath.Dir(resolved) != absWorkdir {
return nil, common.Classify(common.ErrComposeFileEnvInvalid, fmt.Errorf("the first COMPOSE_FILE entry %q must be in the project directory", entry))
}
// os.Stat rather than acfs: compose files may be symlinks resolving
// outside any confinement root, and workdir can be an imported project
// living outside the projects directory.
info, statErr := os.Stat(resolved)
if statErr != nil {
return nil, common.Classify(common.ErrComposeFileEnvInvalid, fmt.Errorf("COMPOSE_FILE entry %q: %w", entry, statErr))
}
if info.IsDir() {
return nil, common.Classify(common.ErrComposeFileEnvInvalid, fmt.Errorf("COMPOSE_FILE entry %q is a directory", entry))
}
files = append(files, resolved)
}
return files, nil
}
// mergeComposeEnvFilesInternal merges each COMPOSE_ENV_FILES entry (in order,
// later wins) on top of envMap; bad entries are warned and skipped. Unlike
// `docker compose`, the entries are additive on top of the project .env rather
// than a replacement: .env is Arcane's managed effective env file and the place
// COMPOSE_ENV_FILES itself is declared, so replacing it would be self-defeating.
func mergeComposeEnvFilesInternal(ctx context.Context, workdir string, envMap EnvMap, parse func(path string, contextEnv EnvMap) (EnvMap, error), onMerged func(values EnvMap)) {
for _, entry := range ComposeEnvFileEntriesFromEnv(envMap) {
resolved, err := ResolvePathWithinDir(workdir, entry)
if err != nil {
slog.WarnContext(ctx, "skipping COMPOSE_ENV_FILES entry outside project directory", "entry", entry, "error", err)
continue
}
// os.Stat rather than acfs: env files may be symlinks resolving outside
// any confinement root (a supported setup).
if _, statErr := os.Stat(resolved); statErr != nil {
slog.WarnContext(ctx, "COMPOSE_ENV_FILES entry not found", "path", resolved, "error", statErr)
continue
}
values, err := parse(resolved, envMap)
if err != nil {
slog.WarnContext(ctx, "failed to load COMPOSE_ENV_FILES entry", "path", resolved, "error", err)
continue
}
if len(values) == 0 {
continue
}
maps.Copy(envMap, values)
if onMerged != nil {
onMerged(values)
}
}
}
func parseComposeBoolInternal(env EnvMap, key string) bool {
raw := strings.TrimSpace(env[key])
if raw == "" {
return false
}
v, err := strconv.ParseBool(raw)
if err != nil {
slog.DebugContext(context.Background(), "ignoring invalid compose boolean env var", //nolint:forbidigo // Compose environment parsing is a pure helper without a request context.
"key", key, "value", raw)
return false
}
return v
}