Skip to content

Modern Docker Management, Designed for Everyone

feat: support for symlink (stow) project directories (#2084)

Kyle Mendell069fe3f3f733
diff --git a/backend/internal/models/settings.go b/backend/internal/models/settings.go
index fb96c370c..ddd2ee421 100644
--- a/backend/internal/models/settings.go
+++ b/backend/internal/models/settings.go
@@ -45,6 +45,7 @@ func (s SettingVariable) AsDurationSeconds() time.Duration {
type Settings struct {
// General category
ProjectsDirectory SettingVariable `key:"projectsDirectory,envOverride" meta:"label=Projects Directory;type=text;keywords=projects,directory,path,folder,location,storage,files,compose,docker-compose;category=internal;description=Configure where project files are stored"`
+ FollowProjectSymlinks SettingVariable `key:"followProjectSymlinks,envOverride" meta:"label=Follow Project Symlinks;type=boolean;keywords=projects,symlink,symlinks,symbolic links,compose,directory,discovery;category=general;description=Treat symlinked child directories inside the projects directory as Docker Compose projects"`
DiskUsagePath SettingVariable `key:"diskUsagePath" meta:"label=Disk Usage Path;type=text;keywords=disk,usage,path,storage,folder,files;category=general;description=Path used for disk usage calculations"`
BaseServerURL SettingVariable `key:"baseServerUrl" meta:"label=Base Server URL;type=text;keywords=base,url,server,domain,host,endpoint,address,link;category=general;description=Set the base URL for the application"`
EnableGravatar SettingVariable `key:"enableGravatar" meta:"label=Enable Gravatar;type=boolean;keywords=gravatar,avatar,profile,picture,image,user,photo;category=general;description=Enable Gravatar profile pictures for users"`
diff --git a/backend/internal/services/project_service.go b/backend/internal/services/project_service.go
index 330b980b6..c3744de7f 100644
--- a/backend/internal/services/project_service.go
+++ b/backend/internal/services/project_service.go
@@ -506,6 +506,7 @@ func (s *ProjectService) enrichWithComposeServiceConfigs(ctx context.Context, pr
func (s *ProjectService) SyncProjectsFromFileSystem(ctx context.Context) error {
projectsDirSetting := s.settingsService.GetStringSetting(ctx, "projectsDirectory", "/app/data/projects")
+ followProjectSymlinks := s.settingsService.GetBoolSetting(ctx, "followProjectSymlinks", false)
projectsDir, err := projects.GetProjectsDirectory(ctx, strings.TrimSpace(projectsDirSetting))
if err != nil {
slog.WarnContext(ctx, "unable to prepare projects directory", "error", err)
@@ -521,11 +522,11 @@ func (s *ProjectService) SyncProjectsFromFileSystem(ctx context.Context) error {
seen := map[string]struct{}{}
for _, e := range entries {
- if !e.IsDir() {
+ dirPath := filepath.Join(projectsDir, e.Name())
+ if !projects.IsProjectDirectoryEntry(e, dirPath, followProjectSymlinks) {
continue
}
dirName := e.Name()
- dirPath := filepath.Join(projectsDir, dirName)
// Only consider folders that contain a compose file
if _, derr := projects.DetectComposeFile(dirPath); derr != nil {
@@ -539,7 +540,7 @@ func (s *ProjectService) SyncProjectsFromFileSystem(ctx context.Context) error {
seen[dirPath] = struct{}{}
}
- if cerr := s.cleanupDBProjects(ctx, seen); cerr != nil {
+ if cerr := s.cleanupDBProjects(ctx, seen, followProjectSymlinks); cerr != nil {
slog.WarnContext(ctx, "error during DB cleanup of projects", "error", cerr)
}
@@ -598,7 +599,7 @@ func (s *ProjectService) upsertProjectForDir(ctx context.Context, dirName, dirPa
return nil
}
-func (s *ProjectService) cleanupDBProjects(ctx context.Context, seen map[string]struct{}) error {
+func (s *ProjectService) cleanupDBProjects(ctx context.Context, seen map[string]struct{}, followProjectSymlinks bool) error {
var all []models.Project
if err := s.db.WithContext(ctx).Find(&all).Error; err != nil {
return fmt.Errorf("list projects for cleanup failed: %w", err)
@@ -610,18 +611,23 @@ func (s *ProjectService) cleanupDBProjects(ctx context.Context, seen map[string]
continue
}
- // Remove if path missing or compose file missing
- if _, err := os.Stat(p.Path); err != nil {
+ validDir, err := projects.IsProjectDirectoryPath(p.Path, followProjectSymlinks)
+ if err != nil {
if os.IsNotExist(err) {
if derr := s.db.WithContext(ctx).Delete(&models.Project{}, "id = ?", p.ID).Error; derr != nil {
slog.WarnContext(ctx, "failed to delete missing-path project", "projectID", p.ID, "error", derr)
}
continue
}
- // On unexpected stat error, skip deletion but warn
slog.WarnContext(ctx, "stat error during cleanup", "path", p.Path, "error", err)
continue
}
+ if !validDir {
+ if derr := s.db.WithContext(ctx).Delete(&models.Project{}, "id = ?", p.ID).Error; derr != nil {
+ slog.WarnContext(ctx, "failed to delete non-project path", "projectID", p.ID, "path", p.Path, "error", derr)
+ }
+ continue
+ }
if _, err := projects.DetectComposeFile(p.Path); err != nil {
if derr := s.db.WithContext(ctx).Delete(&models.Project{}, "id = ?", p.ID).Error; derr != nil {
@@ -666,6 +672,7 @@ func formatDockerPorts(ports []container.PortSummary) []string {
func (s *ProjectService) countProjectFolders(ctx context.Context) (int, error) {
projectsDirSetting := s.settingsService.GetStringSetting(ctx, "projectsDirectory", "/app/data/projects")
+ followProjectSymlinks := s.settingsService.GetBoolSetting(ctx, "followProjectSymlinks", false)
projectsDir, err := projects.GetProjectsDirectory(ctx, strings.TrimSpace(projectsDirSetting))
if err != nil {
return 0, fmt.Errorf("could not determine projects directory: %w", err)
@@ -691,10 +698,10 @@ func (s *ProjectService) countProjectFolders(ctx context.Context) (int, error) {
count := 0
for _, e := range entries {
- if !e.IsDir() {
+ dirPath := filepath.Join(projectsDir, e.Name())
+ if !projects.IsProjectDirectoryEntry(e, dirPath, followProjectSymlinks) {
continue
}
- dirPath := filepath.Join(projectsDir, e.Name())
if _, err := projects.DetectComposeFile(dirPath); err == nil {
count++
}
diff --git a/backend/internal/services/project_service_test.go b/backend/internal/services/project_service_test.go
index 9d0bbe2d2..527c96b54 100644
--- a/backend/internal/services/project_service_test.go
+++ b/backend/internal/services/project_service_test.go
@@ -1421,6 +1421,178 @@ func TestResolveBuildContextInternal_RejectsUnsupportedRemoteContext(t *testing.
assert.Contains(t, err.Error(), "only git repository URLs are supported")
}
+func TestProjectService_SyncProjectsFromFileSystem_IgnoresSymlinkedProjectDirsWhenDisabled(t *testing.T) {
+ db := setupProjectTestDB(t)
+ ctx := context.Background()
+
+ settingsService, err := NewSettingsService(ctx, db)
+ require.NoError(t, err)
+
+ projectsRoot := t.TempDir()
+ targetRoot := t.TempDir()
+ createComposeProjectDir(t, projectsRoot, "regular")
+ linkTarget := createComposeProjectDir(t, targetRoot, "linked-target")
+ require.NoError(t, os.Symlink(linkTarget, filepath.Join(projectsRoot, "linked")))
+
+ require.NoError(t, settingsService.SetStringSetting(ctx, "projectsDirectory", projectsRoot))
+ require.NoError(t, settingsService.SetStringSetting(ctx, "followProjectSymlinks", "false"))
+
+ svc := NewProjectService(db, settingsService, nil, nil, nil, nil)
+ require.NoError(t, svc.SyncProjectsFromFileSystem(ctx))
+
+ items, err := svc.ListAllProjects(ctx)
+ require.NoError(t, err)
+ require.Len(t, items, 1)
+ assert.Equal(t, "regular", items[0].Name)
+ assert.Equal(t, filepath.Join(projectsRoot, "regular"), items[0].Path)
+}
+
+func TestProjectService_SyncProjectsFromFileSystem_DetectsSymlinkedProjectDirsWhenEnabled(t *testing.T) {
+ db := setupProjectTestDB(t)
+ ctx := context.Background()
+
+ settingsService, err := NewSettingsService(ctx, db)
+ require.NoError(t, err)
+
+ projectsRoot := t.TempDir()
+ targetRoot := t.TempDir()
+ linkTarget := createComposeProjectDir(t, targetRoot, "linked-target")
+ linkPath := filepath.Join(projectsRoot, "linked")
+ require.NoError(t, os.Symlink(linkTarget, linkPath))
+
+ require.NoError(t, settingsService.SetStringSetting(ctx, "projectsDirectory", projectsRoot))
+ require.NoError(t, settingsService.SetStringSetting(ctx, "followProjectSymlinks", "true"))
+
+ svc := NewProjectService(db, settingsService, nil, nil, nil, nil)
+ require.NoError(t, svc.SyncProjectsFromFileSystem(ctx))
+
+ items, err := svc.ListAllProjects(ctx)
+ require.NoError(t, err)
+ require.Len(t, items, 1)
+ assert.Equal(t, "linked", items[0].Name)
+ assert.Equal(t, linkPath, items[0].Path)
+}
+
+func TestProjectService_CountProjectFolders_RespectsFollowProjectSymlinks(t *testing.T) {
+ db := setupProjectTestDB(t)
+ ctx := context.Background()
+
+ settingsService, err := NewSettingsService(ctx, db)
+ require.NoError(t, err)
+
+ projectsRoot := t.TempDir()
+ targetRoot := t.TempDir()
+ createComposeProjectDir(t, projectsRoot, "regular")
+ linkTarget := createComposeProjectDir(t, targetRoot, "linked-target")
+ require.NoError(t, os.Symlink(linkTarget, filepath.Join(projectsRoot, "linked")))
+
+ require.NoError(t, settingsService.SetStringSetting(ctx, "projectsDirectory", projectsRoot))
+
+ svc := NewProjectService(db, settingsService, nil, nil, nil, nil)
+
+ require.NoError(t, settingsService.SetStringSetting(ctx, "followProjectSymlinks", "false"))
+ count, err := svc.countProjectFolders(ctx)
+ require.NoError(t, err)
+ assert.Equal(t, 1, count)
+
+ require.NoError(t, settingsService.SetStringSetting(ctx, "followProjectSymlinks", "true"))
+ count, err = svc.countProjectFolders(ctx)
+ require.NoError(t, err)
+ assert.Equal(t, 2, count)
+}
+
+func TestProjectService_SyncProjectsFromFileSystem_RemovesSymlinkedProjectsWhenDisabled(t *testing.T) {
+ db := setupProjectTestDB(t)
+ ctx := context.Background()
+
+ settingsService, err := NewSettingsService(ctx, db)
+ require.NoError(t, err)
+
+ projectsRoot := t.TempDir()
+ targetRoot := t.TempDir()
+ linkTarget := createComposeProjectDir(t, targetRoot, "linked-target")
+ linkPath := filepath.Join(projectsRoot, "linked")
+ require.NoError(t, os.Symlink(linkTarget, linkPath))
+
+ require.NoError(t, settingsService.SetStringSetting(ctx, "projectsDirectory", projectsRoot))
+ require.NoError(t, settingsService.SetStringSetting(ctx, "followProjectSymlinks", "true"))
+
+ svc := NewProjectService(db, settingsService, nil, nil, nil, nil)
+ require.NoError(t, svc.SyncProjectsFromFileSystem(ctx))
+
+ items, err := svc.ListAllProjects(ctx)
+ require.NoError(t, err)
+ require.Len(t, items, 1)
+
+ require.NoError(t, settingsService.SetStringSetting(ctx, "followProjectSymlinks", "false"))
+ require.NoError(t, svc.SyncProjectsFromFileSystem(ctx))
+
+ items, err = svc.ListAllProjects(ctx)
+ require.NoError(t, err)
+ assert.Empty(t, items)
+
+ _, statErr := os.Lstat(linkPath)
+ require.NoError(t, statErr)
+}
+
+func TestProjectService_UpdateProject_WritesThroughSymlinkedProjectPath(t *testing.T) {
+ db := setupProjectTestDB(t)
+ ctx := context.Background()
+
+ settingsService, err := NewSettingsService(ctx, db)
+ require.NoError(t, err)
+
+ projectsRoot := t.TempDir()
+ targetRoot := t.TempDir()
+ targetPath := createComposeProjectDir(t, targetRoot, "demo-target")
+ linkPath := filepath.Join(projectsRoot, "demo")
+ require.NoError(t, os.Symlink(targetPath, linkPath))
+
+ require.NoError(t, settingsService.SetStringSetting(ctx, "projectsDirectory", projectsRoot))
+ require.NoError(t, settingsService.SetStringSetting(ctx, "followProjectSymlinks", "true"))
+
+ eventService := NewEventService(db, nil, nil)
+ svc := NewProjectService(db, settingsService, eventService, nil, nil, nil)
+
+ project := &models.Project{
+ BaseModel: models.BaseModel{ID: "proj-symlink-update"},
+ Name: "demo",
+ DirName: ptr("demo"),
+ Path: linkPath,
+ Status: models.ProjectStatusStopped,
+ }
+ require.NoError(t, db.Create(project).Error)
+
+ updatedCompose := "services:\n app:\n image: nginx:1.27-alpine\n"
+ updatedEnv := "FOO=updated\n"
+
+ updated, err := svc.UpdateProject(ctx, project.ID, nil, ptr(updatedCompose), ptr(updatedEnv), models.User{
+ BaseModel: models.BaseModel{ID: "u1"},
+ Username: "tester",
+ })
+ require.NoError(t, err)
+ require.NotNil(t, updated)
+ assert.Equal(t, linkPath, updated.Path)
+
+ composeBytes, readErr := os.ReadFile(filepath.Join(targetPath, "compose.yaml"))
+ require.NoError(t, readErr)
+ assert.Equal(t, updatedCompose, string(composeBytes))
+
+ envBytes, readErr := os.ReadFile(filepath.Join(targetPath, ".env"))
+ require.NoError(t, readErr)
+ assert.Equal(t, updatedEnv, string(envBytes))
+}
+
+func createComposeProjectDir(t *testing.T, root, name string) string {
+ t.Helper()
+
+ projectPath := filepath.Join(root, name)
+ require.NoError(t, os.MkdirAll(projectPath, 0o755))
+ require.NoError(t, os.WriteFile(filepath.Join(projectPath, "compose.yaml"), []byte("services:\n app:\n image: nginx:alpine\n"), 0o644))
+
+ return projectPath
+}
+
//go:fix inline
func ptr(v string) *string {
return new(v)
diff --git a/backend/internal/services/settings_service.go b/backend/internal/services/settings_service.go
index 64c9a071a..d6d6f03a3 100644
--- a/backend/internal/services/settings_service.go
+++ b/backend/internal/services/settings_service.go
@@ -87,6 +87,7 @@ func (s *SettingsService) LoadDatabaseSettings(ctx context.Context) (err error)
func (s *SettingsService) getDefaultSettings() *models.Settings {
return &models.Settings{
ProjectsDirectory: models.SettingVariable{Value: "/app/data/projects"},
+ FollowProjectSymlinks: models.SettingVariable{Value: "false"},
DiskUsagePath: models.SettingVariable{Value: "/app/data/projects"},
AutoUpdate: models.SettingVariable{Value: "false"},
AutoUpdateInterval: models.SettingVariable{Value: "0 0 0 * * *"},
@@ -510,7 +511,9 @@ func (s *SettingsService) UpdateSettings(ctx context.Context, updates settings.U
if changedAutoHeal && s.OnAutoHealSettingsChanged != nil {
s.OnAutoHealSettingsChanged(ctx)
}
- if slices.ContainsFunc(valuesToUpdate, func(sv models.SettingVariable) bool { return sv.Key == "projectsDirectory" }) && s.OnProjectsDirectoryChanged != nil {
+ if slices.ContainsFunc(valuesToUpdate, func(sv models.SettingVariable) bool {
+ return sv.Key == "projectsDirectory" || sv.Key == "followProjectSymlinks"
+ }) && s.OnProjectsDirectoryChanged != nil {
s.OnProjectsDirectoryChanged(ctx)
}
if len(changedTimeouts) > 0 && s.OnTimeoutSettingsChanged != nil {
diff --git a/backend/internal/services/settings_service_test.go b/backend/internal/services/settings_service_test.go
index da2933b60..252f6f5bc 100644
--- a/backend/internal/services/settings_service_test.go
+++ b/backend/internal/services/settings_service_test.go
@@ -44,12 +44,14 @@ func TestSettingsService_EnsureDefaultSettings_Idempotent(t *testing.T) {
require.Equal(t, count1, count2)
// Spot-check core and automation defaults exist with correct values
- for _, key := range []string{"authLocalEnabled", "projectsDirectory", "autoUpdateExcludedContainers", "vulnerabilityScanEnabled", "vulnerabilityScanInterval", "trivyNetwork", "trivySecurityOpts", "trivyPrivileged", "trivyPreserveCacheOnVolumePrune", "trivyResourceLimitsEnabled", "trivyCpuLimit", "trivyMemoryLimitMb", "trivyConcurrentScanContainers"} {
+ for _, key := range []string{"authLocalEnabled", "projectsDirectory", "followProjectSymlinks", "autoUpdateExcludedContainers", "vulnerabilityScanEnabled", "vulnerabilityScanInterval", "trivyNetwork", "trivySecurityOpts", "trivyPrivileged", "trivyPreserveCacheOnVolumePrune", "trivyResourceLimitsEnabled", "trivyCpuLimit", "trivyMemoryLimitMb", "trivyConcurrentScanContainers"} {
var sv models.SettingVariable
err := svc.db.WithContext(ctx).Where("key = ?", key).First(&sv).Error
require.NoErrorf(t, err, "missing default key %s", key)
switch key {
+ case "followProjectSymlinks":
+ require.Equal(t, "false", sv.Value)
case "autoUpdateExcludedContainers":
require.Equal(t, "", sv.Value)
case "vulnerabilityScanEnabled":
@@ -195,6 +197,24 @@ func TestSettingsService_GetSettings_EnvOverride_TrivyNetwork(t *testing.T) {
require.Equal(t, "arcane-external", settings2.TrivyNetwork.Value)
}
+func TestSettingsService_GetSettings_EnvOverride_FollowProjectSymlinks(t *testing.T) {
+ ctx := context.Background()
+ db := setupSettingsTestDB(t)
+
+ svc, err := NewSettingsService(ctx, db)
+ require.NoError(t, err)
+ require.NoError(t, svc.EnsureDefaultSettings(ctx))
+
+ settings1, err := svc.GetSettings(ctx)
+ require.NoError(t, err)
+ require.False(t, settings1.FollowProjectSymlinks.IsTrue())
+
+ t.Setenv("FOLLOW_PROJECT_SYMLINKS", "true")
+ settings2, err := svc.GetSettings(ctx)
+ require.NoError(t, err)
+ require.True(t, settings2.FollowProjectSymlinks.IsTrue())
+}
+
func TestSettingsService_GetSettings_EnvOverride_TrivyRuntimeSecurity(t *testing.T) {
ctx := context.Background()
db := setupSettingsTestDB(t)
diff --git a/backend/pkg/fswatch/watcher.go b/backend/pkg/fswatch/watcher.go
index 1edf825c1..faa01bcf9 100644
--- a/backend/pkg/fswatch/watcher.go
+++ b/backend/pkg/fswatch/watcher.go
@@ -14,19 +14,21 @@ import (
)
type Watcher struct {
- watcher *fsnotify.Watcher
- watchedPath string
- maxDepth int
- onChange func(ctx context.Context)
- debounce time.Duration
- stopCh chan struct{}
- stoppedCh chan struct{}
+ watcher *fsnotify.Watcher
+ watchedPath string
+ maxDepth int
+ followSymlinks bool
+ onChange func(ctx context.Context)
+ debounce time.Duration
+ stopCh chan struct{}
+ stoppedCh chan struct{}
}
type WatcherOptions struct {
- Debounce time.Duration
- OnChange func(ctx context.Context)
- MaxDepth int
+ Debounce time.Duration
+ OnChange func(ctx context.Context)
+ MaxDepth int
+ FollowSymlinkDirs bool
}
func NewWatcher(watchPath string, opts WatcherOptions) (*Watcher, error) {
@@ -44,13 +46,14 @@ func NewWatcher(watchPath string, opts WatcherOptions) (*Watcher, error) {
}
return &Watcher{
- watcher: watcher,
- watchedPath: filepath.Clean(watchPath),
- maxDepth: opts.MaxDepth,
- onChange: opts.OnChange,
- debounce: opts.Debounce,
- stopCh: make(chan struct{}),
- stoppedCh: make(chan struct{}),
+ watcher: watcher,
+ watchedPath: filepath.Clean(watchPath),
+ maxDepth: opts.MaxDepth,
+ followSymlinks: opts.FollowSymlinkDirs,
+ onChange: opts.OnChange,
+ debounce: opts.Debounce,
+ stopCh: make(chan struct{}),
+ stoppedCh: make(chan struct{}),
}, nil
}
@@ -150,7 +153,7 @@ func (fw *Watcher) fireDebounceInternal(ctx context.Context, debouncePending *bo
func (fw *Watcher) handleEvent(ctx context.Context, event fsnotify.Event) {
if event.Has(fsnotify.Create) {
- if info, err := os.Stat(event.Name); err == nil && info.IsDir() {
+ if fw.isWatchableDirectory(event.Name) {
if fw.shouldWatchDir(event.Name) {
if err := fw.watcher.Add(event.Name); err != nil {
slog.WarnContext(ctx, "Failed to add new directory to watcher",
@@ -171,7 +174,7 @@ func (fw *Watcher) shouldHandleEvent(event fsnotify.Event) bool {
// Watch for new directories, compose files, .env being manipulated.
if event.Has(fsnotify.Write) || event.Has(fsnotify.Create) || event.Has(fsnotify.Rename) || event.Has(fsnotify.Remove) {
- if info, err := os.Stat(event.Name); err == nil && info.IsDir() || projects.IsProjectFile(name) {
+ if fw.isWatchableDirectory(event.Name) || projects.IsProjectFile(name) {
return true
}
}
@@ -180,7 +183,7 @@ func (fw *Watcher) shouldHandleEvent(event fsnotify.Event) bool {
}
func (fw *Watcher) addExistingDirectories(root string) error {
- return filepath.Walk(root, func(path string, info os.FileInfo, err error) error {
+ if err := filepath.Walk(root, func(path string, info os.FileInfo, err error) error {
if err != nil {
slog.Warn("Error walking directory",
"path", path,
@@ -208,7 +211,35 @@ func (fw *Watcher) addExistingDirectories(root string) error {
}
}
return nil
- })
+ }); err != nil {
+ return err
+ }
+
+ if !fw.followSymlinks {
+ return nil
+ }
+
+ entries, err := os.ReadDir(root)
+ if err != nil {
+ return err
+ }
+
+ for _, entry := range entries {
+ path := filepath.Join(root, entry.Name())
+ if !projects.IsProjectDirectoryEntry(entry, path, fw.followSymlinks) || entry.IsDir() {
+ continue
+ }
+ if !fw.shouldWatchDir(path) {
+ continue
+ }
+ if err := fw.watcher.Add(path); err != nil {
+ slog.Warn("Failed to add symlink directory to watcher",
+ "path", path,
+ "error", err)
+ }
+ }
+
+ return nil
}
func (fw *Watcher) dirDepth(path string) int {
@@ -237,3 +268,25 @@ func (fw *Watcher) shouldWatchDir(path string) bool {
depth := fw.dirDepth(path)
return depth > 0 && depth <= fw.maxDepth
}
+
+func (fw *Watcher) isWatchableDirectory(path string) bool {
+ info, err := os.Lstat(path)
+ if err != nil {
+ return false
+ }
+
+ if info.IsDir() {
+ return true
+ }
+
+ if !fw.followSymlinks || info.Mode()&os.ModeSymlink == 0 {
+ return false
+ }
+
+ resolvedInfo, err := os.Stat(path)
+ if err != nil {
+ return false
+ }
+
+ return resolvedInfo.IsDir()
+}
diff --git a/backend/pkg/fswatch/watcher_test.go b/backend/pkg/fswatch/watcher_test.go
new file mode 100644
index 000000000..dd2f8bcfb
--- /dev/null
+++ b/backend/pkg/fswatch/watcher_test.go
@@ -0,0 +1,88 @@
+package fswatch
+
+import (
+ "context"
+ "os"
+ "path/filepath"
+ "testing"
+ "time"
+
+ "github.com/stretchr/testify/require"
+)
+
+func TestWatcher_StartWatchesExistingSymlinkDirectoriesWhenEnabled(t *testing.T) {
+ root := t.TempDir()
+ targetRoot := t.TempDir()
+ targetPath := filepath.Join(targetRoot, "real-project")
+ require.NoError(t, os.MkdirAll(targetPath, 0o755))
+
+ linkPath := filepath.Join(root, "linked-project")
+ require.NoError(t, os.Symlink(targetPath, linkPath))
+
+ changeCh := make(chan struct{}, 1)
+ ctx, cancel := context.WithCancel(context.Background())
+ defer cancel()
+
+ watcher, err := NewWatcher(root, WatcherOptions{
+ Debounce: 25 * time.Millisecond,
+ MaxDepth: 1,
+ FollowSymlinkDirs: true,
+ OnChange: func(context.Context) {
+ select {
+ case changeCh <- struct{}{}:
+ default:
+ }
+ },
+ })
+ require.NoError(t, err)
+ require.NoError(t, watcher.Start(ctx))
+ defer func() {
+ require.NoError(t, watcher.Stop())
+ }()
+
+ require.NoError(t, os.WriteFile(filepath.Join(targetPath, "compose.yaml"), []byte("services: {}\n"), 0o644))
+
+ select {
+ case <-changeCh:
+ case <-time.After(2 * time.Second):
+ t.Fatal("expected symlinked directory change to trigger watcher callback")
+ }
+}
+
+func TestWatcher_StartSkipsExistingSymlinkDirectoriesWhenDisabled(t *testing.T) {
+ root := t.TempDir()
+ targetRoot := t.TempDir()
+ targetPath := filepath.Join(targetRoot, "real-project")
+ require.NoError(t, os.MkdirAll(targetPath, 0o755))
+
+ linkPath := filepath.Join(root, "linked-project")
+ require.NoError(t, os.Symlink(targetPath, linkPath))
+
+ changeCh := make(chan struct{}, 1)
+ ctx, cancel := context.WithCancel(context.Background())
+ defer cancel()
+
+ watcher, err := NewWatcher(root, WatcherOptions{
+ Debounce: 25 * time.Millisecond,
+ MaxDepth: 1,
+ OnChange: func(context.Context) {
+ select {
+ case changeCh <- struct{}{}:
+ default:
+ }
+ },
+ })
+ require.NoError(t, err)
+ require.NoError(t, watcher.Start(ctx))
+ defer func() {
+ require.NoError(t, watcher.Stop())
+ }()
+
+ require.NoError(t, os.WriteFile(filepath.Join(targetPath, "compose.yaml"), []byte("services: {}\n"), 0o644))
+
+ select {
+ case <-changeCh:
+ t.Fatal("did not expect symlinked directory change to trigger watcher callback when disabled")
+ case <-time.After(300 * time.Millisecond):
+ }
+}
diff --git a/backend/pkg/projects/discovery.go b/backend/pkg/projects/discovery.go
new file mode 100644
index 000000000..940c3b88f
--- /dev/null
+++ b/backend/pkg/projects/discovery.go
@@ -0,0 +1,50 @@
+package projects
+
+import "os"
+
+// 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 IsProjectDirectoryEntry(entry os.DirEntry, path string, followSymlinks bool) bool {
+ if entry == nil {
+ return false
+ }
+
+ if entry.IsDir() {
+ return true
+ }
+
+ if !followSymlinks || entry.Type()&os.ModeSymlink == 0 {
+ return false
+ }
+
+ info, err := os.Stat(path)
+ if err != nil {
+ return false
+ }
+
+ return info.IsDir()
+}
+
+// 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 IsProjectDirectoryPath(path string, followSymlinks bool) (bool, error) {
+ info, err := os.Lstat(path)
+ if err != nil {
+ return false, err
+ }
+
+ if info.IsDir() {
+ return true, nil
+ }
+
+ if !followSymlinks || info.Mode()&os.ModeSymlink == 0 {
+ return false, nil
+ }
+
+ resolvedInfo, err := os.Stat(path)
+ if err != nil {
+ return false, err
+ }
+
+ return resolvedInfo.IsDir(), nil
+}
diff --git a/backend/pkg/scheduler/filesystem_watcher_job.go b/backend/pkg/scheduler/filesystem_watcher_job.go
index 8c58c7231..9004af8da 100644
--- a/backend/pkg/scheduler/filesystem_watcher_job.go
+++ b/backend/pkg/scheduler/filesystem_watcher_job.go
@@ -52,11 +52,13 @@ func (j *FilesystemWatcherJob) Start(ctx context.Context) error {
if err != nil {
return err
}
+ followProjectSymlinks := settings.FollowProjectSymlinks.IsTrue()
sw, err := fswatch.NewWatcher(projectsDirectory, fswatch.WatcherOptions{
- Debounce: 3 * time.Second, // Wait 3 seconds after last change before syncing
- OnChange: j.handleFilesystemChange,
- MaxDepth: 1,
+ Debounce: 3 * time.Second, // Wait 3 seconds after last change before syncing
+ OnChange: j.handleFilesystemChange,
+ MaxDepth: 1,
+ FollowSymlinkDirs: followProjectSymlinks,
})
if err != nil {
return err
@@ -172,12 +174,14 @@ func (j *FilesystemWatcherJob) RestartProjectsWatcher(ctx context.Context) error
if err != nil {
return err
}
+ followProjectSymlinks := settings.FollowProjectSymlinks.IsTrue()
// Create a new watcher with the updated path
sw, err := fswatch.NewWatcher(projectsDirectory, fswatch.WatcherOptions{
- Debounce: 3 * time.Second,
- OnChange: j.handleFilesystemChange,
- MaxDepth: 1,
+ Debounce: 3 * time.Second,
+ OnChange: j.handleFilesystemChange,
+ MaxDepth: 1,
+ FollowSymlinkDirs: followProjectSymlinks,
})
if err != nil {
return err
diff --git a/frontend/messages/en.json b/frontend/messages/en.json
index 471d20915..b4db7517b 100644
--- a/frontend/messages/en.json
+++ b/frontend/messages/en.json
@@ -968,6 +968,8 @@
"general_title": "General",
"general_projects_directory_label": "Projects Directory",
"general_projects_directory_help": "Directory where Docker Compose files are stored (this is inside the container). MUST be an absolute path!",
+ "general_follow_project_symlinks_label": "Follow Project Symlinks",
+ "general_follow_project_symlinks_help": "Treat symlinked child directories inside the projects directory as Docker Compose projects.",
"general_base_url_label": "Base Server URL",
"general_base_url_help": "The Base URL for your docker host. Used when opening containers from the service links",
"general_user_avatars_heading": "User Avatars",
diff --git a/frontend/src/lib/types/settings.type.ts b/frontend/src/lib/types/settings.type.ts
index 2959e8a2e..481cd1fa5 100644
--- a/frontend/src/lib/types/settings.type.ts
+++ b/frontend/src/lib/types/settings.type.ts
@@ -2,6 +2,7 @@ import type { TemplateRegistryConfig } from './template.type';
export type Settings = {
projectsDirectory: string;
+ followProjectSymlinks: boolean;
diskUsagePath: string;
autoUpdate: boolean;
autoUpdateInterval: number;
diff --git a/frontend/src/routes/(app)/containers/container-table.actions.ts b/frontend/src/routes/(app)/containers/container-table.actions.ts
index 4b4b5e83a..72d024ead 100644
--- a/frontend/src/routes/(app)/containers/container-table.actions.ts
+++ b/frontend/src/routes/(app)/containers/container-table.actions.ts
@@ -185,8 +185,6 @@ export function createContainerActions({
}
async function handleRedeployContainer(container: ContainerSummaryDto) {
- const containerName = getContainerDisplayName(container);
-
openConfirmDialog({
title: m.container_confirm_redeploy_title(),
message: m.container_confirm_redeploy_message(),
diff --git a/frontend/src/routes/(app)/environments/[id]/+page.svelte b/frontend/src/routes/(app)/environments/[id]/+page.svelte
index 60b967e67..67015fe6f 100644
--- a/frontend/src/routes/(app)/environments/[id]/+page.svelte
+++ b/frontend/src/routes/(app)/environments/[id]/+page.svelte
@@ -149,6 +149,7 @@
pollingEnabled: z.boolean(),
autoUpdate: z.boolean(),
autoInjectEnv: z.boolean(),
+ followProjectSymlinks: z.boolean(),
dockerPruneMode: z.enum(['all', 'dangling']),
defaultDeployPullPolicy: z.enum(['missing', 'always', 'never']),
defaultShell: z.string(),
@@ -187,6 +188,7 @@
pollingEnabled: settings?.pollingEnabled ?? false,
autoUpdate: settings?.autoUpdate ?? false,
autoInjectEnv: settings?.autoInjectEnv ?? false,
+ followProjectSymlinks: settings?.followProjectSymlinks ?? false,
dockerPruneMode: (settings?.dockerPruneMode as 'all' | 'dangling') || 'dangling',
defaultDeployPullPolicy: (settings?.defaultDeployPullPolicy as 'missing' | 'always' | 'never') || 'missing',
defaultShell: settings?.defaultShell || '/bin/sh',
@@ -232,6 +234,7 @@
pollingEnabled: formData.pollingEnabled,
autoUpdate: formData.autoUpdate,
autoInjectEnv: formData.autoInjectEnv,
+ followProjectSymlinks: formData.followProjectSymlinks,
dockerPruneMode: formData.dockerPruneMode,
defaultDeployPullPolicy: formData.defaultDeployPullPolicy,
defaultShell: formData.defaultShell,
diff --git a/frontend/src/routes/(app)/environments/[id]/components/GeneralTab.svelte b/frontend/src/routes/(app)/environments/[id]/components/GeneralTab.svelte
index 1184635ca..f7de6d083 100644
--- a/frontend/src/routes/(app)/environments/[id]/components/GeneralTab.svelte
+++ b/frontend/src/routes/(app)/environments/[id]/components/GeneralTab.svelte
@@ -1,5 +1,7 @@
<script lang="ts">
import * as Card from '$lib/components/ui/card/index.js';
+ import Label from '$lib/components/ui/label/label.svelte';
+ import { Switch } from '$lib/components/ui/switch/index.js';
import TextInputWithLabel from '$lib/components/form/text-input-with-label.svelte';
import { m } from '$lib/paraglide/messages';
import { SettingsIcon } from '$lib/icons';
@@ -55,6 +57,17 @@
helpText={m.docker_max_upload_size_description()}
/>
</div>
+ <div class="space-y-4 rounded-lg border p-4 sm:col-span-2">
+ <div class="flex items-center justify-between gap-4">
+ <div class="space-y-0.5">
+ <Label for="follow-project-symlinks" class="text-sm font-medium">
+ {m.general_follow_project_symlinks_label()}
+ </Label>
+ <div class="text-muted-foreground text-xs">{m.general_follow_project_symlinks_help()}</div>
+ </div>
+ <Switch id="follow-project-symlinks" bind:checked={$formInputs.followProjectSymlinks.value} />
+ </div>
+ </div>
</div>
</Card.Content>
</Card.Root>
diff --git a/tests/spec/environment-settings.spec.ts b/tests/spec/environment-settings.spec.ts
index 1d2df3cad..2209bdb20 100644
--- a/tests/spec/environment-settings.spec.ts
+++ b/tests/spec/environment-settings.spec.ts
@@ -134,6 +134,62 @@ test.describe('Environment Settings UI', () => {
}
});
+ test('should update and save the follow project symlinks setting from General', async ({
+ page
+ }) => {
+ await openLocalEnvironment(page);
+ await page.getByRole('tab', { name: 'General', exact: true }).click();
+
+ const followProjectSymlinksSwitch = page.locator('#follow-project-symlinks');
+ await expect(followProjectSymlinksSwitch).toBeVisible();
+
+ const originalChecked =
+ (await followProjectSymlinksSwitch.getAttribute('aria-checked')) === 'true';
+ const updatedChecked = !originalChecked;
+
+ try {
+ await followProjectSymlinksSwitch.click();
+ await expect(followProjectSymlinksSwitch).toHaveAttribute(
+ 'aria-checked',
+ String(updatedChecked)
+ );
+
+ const saveButton = page.getByRole('button', { name: 'Save', exact: true }).first();
+ await expect(saveButton).toBeEnabled();
+
+ const responsePromise = page.waitForResponse((response) => {
+ const request = response.request();
+ if (request.method() !== 'PUT') return false;
+ const url = new URL(response.url());
+ return url.pathname === `/api/environments/${LOCAL_ENV_ID}/settings`;
+ });
+
+ await saveButton.click();
+ const response = await responsePromise;
+ expect(response.ok()).toBeTruthy();
+
+ const payload = response.request().postDataJSON() as Record<string, string>;
+ expect(payload.followProjectSymlinks).toBe(String(updatedChecked));
+
+ await page.reload();
+ await page.getByRole('tab', { name: 'General', exact: true }).click();
+ await expect(page.locator('#follow-project-symlinks')).toHaveAttribute(
+ 'aria-checked',
+ String(updatedChecked)
+ );
+ } finally {
+ if (!page.isClosed()) {
+ await page.getByRole('tab', { name: 'General', exact: true }).click();
+ const currentChecked =
+ (await page.locator('#follow-project-symlinks').getAttribute('aria-checked')) === 'true';
+ if (currentChecked !== originalChecked) {
+ await page.locator('#follow-project-symlinks').click();
+ await saveAndWaitForPut(page, `/api/environments/${LOCAL_ENV_ID}/settings`);
+ }
+ }
+ }
+ });
+
test('should reset unsaved environment detail changes', async ({ page }) => {
await openLocalEnvironment(page);
diff --git a/types/settings/settings.go b/types/settings/settings.go
index 4338dbd87..cfce09a44 100644
--- a/types/settings/settings.go
+++ b/types/settings/settings.go
@@ -37,6 +37,11 @@ type Update struct {
// Required: false
ProjectsDirectory *string `json:"projectsDirectory,omitempty"`
+ // FollowProjectSymlinks controls whether symlinked child directories in the projects directory are discovered as projects.
+ //
+ // Required: false
+ FollowProjectSymlinks *string `json:"followProjectSymlinks,omitempty"`
+
// DiskUsagePath is the path to monitor for disk usage.
//
// Required: false