Skip to content

Modern Docker Management, Designed for Everyone

feat: docker socket proxy support via environment variable (#616)

Copilotb2e5bc7a0962
diff --git a/.env.example b/.env.example
index 855c7adf4..643b3f982 100644
--- a/.env.example
+++ b/.env.example
@@ -1,4 +1,8 @@
APP_URL="http://localhost:3552"
ENVIRONMENT=production
ENCRYPTION_KEY=f00V7L3pqj+yMtfUkpFAyaRTxoGo+600 #openssl rand -base64 32
-JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
\ No newline at end of file
+JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
+
+# Docker Configuration
+# DOCKER_HOST=unix:///var/run/docker.sock # Default: direct socket access
+# DOCKER_HOST=tcp://docker-socket-proxy:2375 # Example: via socket proxy for enhanced security
\ No newline at end of file
diff --git a/.github/workflows/e2e-tests.yml b/.github/workflows/e2e-tests.yml
index f546b33b3..0e7ad9c4f 100644
--- a/.github/workflows/e2e-tests.yml
+++ b/.github/workflows/e2e-tests.yml
@@ -72,6 +72,9 @@ jobs:
- name: postgres
compose_file: setup/compose-postgres.yaml
port: 3001
+ - name: proxy
+ compose_file: setup/compose-proxy.yaml
+ port: 3002
name: E2E Tests (${{ matrix.database.name }})
steps:
- uses: actions/checkout@v5
diff --git a/backend/internal/bootstrap/services_bootstrap.go b/backend/internal/bootstrap/services_bootstrap.go
index 53a1d3715..755d72322 100644
--- a/backend/internal/bootstrap/services_bootstrap.go
+++ b/backend/internal/bootstrap/services_bootstrap.go
@@ -39,7 +39,7 @@ func initializeServices(ctx context.Context, db *database.DB, cfg *config.Config
if err != nil {
return nil, nil, fmt.Errorf("failed to settings service: %w", err)
}
- dockerClient := services.NewDockerClientService(db)
+ dockerClient := services.NewDockerClientService(db, cfg)
svcs.Docker = dockerClient
svcs.User = services.NewUserService(db)
svcs.ContainerRegistry = services.NewContainerRegistryService(db)
diff --git a/backend/internal/config/config.go b/backend/internal/config/config.go
index 218148ac4..0c524115c 100644
--- a/backend/internal/config/config.go
+++ b/backend/internal/config/config.go
@@ -26,6 +26,7 @@ type Config struct {
OidcAdminClaim string
OidcAdminValue string
+ DockerHost string
LogJson bool
LogLevel string
AgentMode bool
@@ -53,6 +54,7 @@ func Load() *Config {
OidcAdminClaim: getEnvOrDefault("OIDC_ADMIN_CLAIM", ""),
OidcAdminValue: getEnvOrDefault("OIDC_ADMIN_VALUE", ""),
+ DockerHost: getEnvOrDefault("DOCKER_HOST", "unix:///var/run/docker.sock"),
LogJson: getBoolEnvOrDefault("LOG_JSON", false),
LogLevel: strings.ToLower(getEnvOrDefault("LOG_LEVEL", "info")),
AgentMode: getBoolEnvOrDefault("AGENT_MODE", false),
diff --git a/backend/internal/dto/settings_dto.go b/backend/internal/dto/settings_dto.go
index 52bd45d6b..9b1284d8c 100644
--- a/backend/internal/dto/settings_dto.go
+++ b/backend/internal/dto/settings_dto.go
@@ -22,6 +22,7 @@ type UpdateSettingsDto struct {
BaseServerURL *string `json:"baseServerUrl,omitempty"`
EnableGravatar *string `json:"enableGravatar,omitempty"`
DefaultShell *string `json:"defaultShell,omitempty"`
+ DockerHost *string `json:"dockerHost,omitempty"`
// Authentication settings
AuthLocalEnabled *string `json:"authLocalEnabled,omitempty"`
diff --git a/backend/internal/models/settings.go b/backend/internal/models/settings.go
index 65c669791..e05670fc0 100644
--- a/backend/internal/models/settings.go
+++ b/backend/internal/models/settings.go
@@ -53,6 +53,7 @@ type Settings struct {
BaseServerURL SettingVariable `key:"baseServerUrl"`
EnableGravatar SettingVariable `key:"enableGravatar"`
DefaultShell SettingVariable `key:"defaultShell"`
+ DockerHost SettingVariable `key:"dockerHost,public,envOverride"`
// Authentication
AuthLocalEnabled SettingVariable `key:"authLocalEnabled,public"`
diff --git a/backend/internal/services/docker_client_service.go b/backend/internal/services/docker_client_service.go
index 840ffb467..55876cb60 100644
--- a/backend/internal/services/docker_client_service.go
+++ b/backend/internal/services/docker_client_service.go
@@ -10,21 +10,26 @@ import (
"github.com/docker/docker/api/types/network"
"github.com/docker/docker/api/types/volume"
"github.com/docker/docker/client"
+ "github.com/ofkm/arcane-backend/internal/config"
"github.com/ofkm/arcane-backend/internal/database"
"github.com/ofkm/arcane-backend/internal/utils/docker"
)
type DockerClientService struct {
- db *database.DB
+ db *database.DB
+ config *config.Config
}
-func NewDockerClientService(db *database.DB) *DockerClientService {
- return &DockerClientService{db: db}
+func NewDockerClientService(db *database.DB, cfg *config.Config) *DockerClientService {
+ return &DockerClientService{
+ db: db,
+ config: cfg,
+ }
}
func (s *DockerClientService) CreateConnection(ctx context.Context) (*client.Client, error) {
cli, err := client.NewClientWithOpts(
- client.WithHost("unix:///var/run/docker.sock"),
+ client.WithHost(s.config.DockerHost),
client.WithAPIVersionNegotiation(),
)
diff --git a/backend/internal/services/settings_service.go b/backend/internal/services/settings_service.go
index a786bd30a..9c0cbcaad 100644
--- a/backend/internal/services/settings_service.go
+++ b/backend/internal/services/settings_service.go
@@ -85,6 +85,7 @@ func (s *SettingsService) getDefaultSettings() *models.Settings {
BaseServerURL: models.SettingVariable{Value: "http://localhost"},
EnableGravatar: models.SettingVariable{Value: "true"},
DefaultShell: models.SettingVariable{Value: "/bin/sh"},
+ DockerHost: models.SettingVariable{Value: "unix:///var/run/docker.sock"},
AuthLocalEnabled: models.SettingVariable{Value: "true"},
AuthOidcEnabled: models.SettingVariable{Value: "false"},
AuthSessionTimeout: models.SettingVariable{Value: "1440"},
@@ -104,7 +105,6 @@ func (s *SettingsService) getDefaultSettings() *models.Settings {
func (s *SettingsService) loadDatabaseSettingsInternal(ctx context.Context, db *database.DB) (*models.Settings, error) {
if config.Load().UIConfigurationDisabled || config.Load().AgentMode {
- // debug: show why we're using env path
slog.DebugContext(ctx, "loadDatabaseSettingsInternal: using env path", "UIConfigurationDisabled", config.Load().UIConfigurationDisabled, "AgentMode", config.Load().AgentMode, "Environment", config.Load().Environment)
dst, err := s.loadDatabaseConfigFromEnv(ctx, db)
@@ -143,6 +143,9 @@ func (s *SettingsService) loadDatabaseSettingsInternal(ctx context.Context, db *
}
}
+ // Apply environment variable overrides for fields tagged with "envOverride"
+ s.applyEnvOverrides(ctx, dest)
+
return dest, nil
}
@@ -199,6 +202,41 @@ func (s *SettingsService) loadDatabaseConfigFromEnv(ctx context.Context, db *dat
return dest, nil
}
+func (s *SettingsService) applyEnvOverrides(ctx context.Context, dest *models.Settings) {
+ rt := reflect.ValueOf(dest).Elem().Type()
+ rv := reflect.ValueOf(dest).Elem()
+
+ for i := range rt.NumField() {
+ field := rt.Field(i)
+ tagValue := field.Tag.Get("key")
+ if tagValue == "" {
+ continue
+ }
+
+ // Parse tag attributes (e.g., "dockerHost,public,envOverride")
+ parts := strings.Split(tagValue, ",")
+ key := parts[0]
+ hasEnvOverride := false
+ for _, attr := range parts[1:] {
+ if attr == "envOverride" {
+ hasEnvOverride = true
+ break
+ }
+ }
+
+ if !hasEnvOverride {
+ continue
+ }
+
+ // Check if environment variable is set
+ envVarName := utils.CamelCaseToScreamingSnakeCase(key)
+ if val, ok := os.LookupEnv(envVarName); ok && val != "" {
+ slog.DebugContext(ctx, "applyEnvOverrides: applying env override", "key", key, "env", envVarName)
+ rv.Field(i).FieldByName("Value").SetString(val)
+ }
+ }
+}
+
func (s *SettingsService) GetSettings(ctx context.Context) (*models.Settings, error) {
var settingVars []models.SettingVariable
err := s.db.WithContext(ctx).Find(&settingVars).Error
diff --git a/docker-compose.proxy.yml b/docker-compose.proxy.yml
new file mode 100644
index 000000000..07fc1a721
--- /dev/null
+++ b/docker-compose.proxy.yml
@@ -0,0 +1,76 @@
+services:
+ # Docker Socket Proxy - see https://github.com/Tecnativa/docker-socket-proxy for official documentation
+ docker-socket-proxy:
+ image: tecnativa/docker-socket-proxy:latest
+ container_name: arcane-docker-proxy
+ environment:
+ - EVENTS=1
+ - PING=1
+ - VERSION=1
+ # Security critical
+ - AUTH=0
+ - SECRETS=0
+ - POST=1
+ # Not always needed
+ - BUILD=0
+ - COMMIT=0
+ - CONFIGS=0
+ - CONTAINERS=1
+ - DISTRIBUTION=0
+ - EXEC=1
+ - IMAGES=1
+ - INFO=1
+ - NETWORKS=1
+ - NODES=0
+ - PLUGINS=0
+ - SERVICES=0
+ - SESSION=0
+ - SWARM=0
+ - SYSTEM=0
+ - TASKS=0
+ - VOLUMES=1
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock:ro # Read-only access to host socket
+ networks:
+ - arcane-internal
+ restart: unless-stopped
+ security_opt:
+ - no-new-privileges:true
+
+ arcane:
+ image: ghcr.io/ofkm/arcane:latest
+ container_name: arcane
+ ports:
+ - "3552:3552"
+ volumes:
+ - arcane-data:/app/data
+ environment:
+ - PUID=1000
+ - PGID=1000
+ - ENCRYPTION_KEY=xxxxxxxxxxxxxxxxxxxxxx # openssl rand -base64 32
+ - JWT_SECRET=xxxxxxxxxxxxxxxxxxxxxx # openssl rand -base64 32
+ - DOCKER_HOST=tcp://docker-socket-proxy:2375 # Use the proxy instead of direct socket
+ networks:
+ - arcane-internal
+ depends_on:
+ - docker-socket-proxy
+ healthcheck:
+ test:
+ [
+ "CMD-SHELL",
+ "curl -fsS http://localhost:3552/api/health >/dev/null || exit 1",
+ ]
+ interval: 10s
+ timeout: 3s
+ retries: 5
+ start_period: 15s
+ restart: unless-stopped
+
+networks:
+ arcane-internal:
+ driver: bridge
+ name: arcane-internal
+
+volumes:
+ arcane-data:
+ name: arcane-data
diff --git a/frontend/src/lib/components/mobile-nav/mobile-user-card.svelte b/frontend/src/lib/components/mobile-nav/mobile-user-card.svelte
index 3971fa803..3b615ecac 100644
--- a/frontend/src/lib/components/mobile-nav/mobile-user-card.svelte
+++ b/frontend/src/lib/components/mobile-nav/mobile-user-card.svelte
@@ -3,7 +3,7 @@
import * as Select from '$lib/components/ui/select/index.js';
import { cn } from '$lib/utils';
import LogOutIcon from '@lucide/svelte/icons/log-out';
- import GlobeIcon from '@lucide/svelte/icons/globe';
+ import RouterIcon from '@lucide/svelte/icons/router';
import ServerIcon from '@lucide/svelte/icons/server';
import LanguagesIcon from '@lucide/svelte/icons/languages';
import Sun from '@lucide/svelte/icons/sun';
@@ -16,6 +16,7 @@
import type { User } from '$lib/types/user.type';
import LocalePicker from '$lib/components/locale-picker.svelte';
import ChevronDownIcon from '@lucide/svelte/icons/chevron-down';
+ import settingsStore from '$lib/stores/config-store';
type Props = {
user: User;
@@ -66,6 +67,14 @@
return env.name;
}
}
+
+ function getConnectionString(env: Environment): string {
+ if (env.isLocal) {
+ return $settingsStore.dockerHost || 'unix:///var/run/docker.sock';
+ } else {
+ return env.apiUrl;
+ }
+ }
</script>
<div class={`bg-muted/30 border-border/20 overflow-hidden rounded-3xl border ${className}`}>
@@ -116,7 +125,7 @@
{#if currentSelectedEnvironment?.isLocal}
<ServerIcon class="size-4" />
{:else}
- <GlobeIcon class="size-4" />
+ <RouterIcon class="size-4" />
{/if}
</div>
<div class="min-w-0 flex-1">
@@ -126,6 +135,11 @@
<div class="text-foreground text-sm font-medium">
{currentSelectedEnvironment ? getEnvLabel(currentSelectedEnvironment) : m.sidebar_no_environment()}
</div>
+ {#if currentSelectedEnvironment}
+ <div class="text-muted-foreground/60 text-xs">
+ {getConnectionString(currentSelectedEnvironment)}
+ </div>
+ {/if}
</div>
{#if availableEnvironments.length > 1}
<Select.Root type="single" value={selectedValue} onValueChange={handleEnvSelect}>
diff --git a/frontend/src/lib/components/sidebar/sidebar-env-switcher.svelte b/frontend/src/lib/components/sidebar/sidebar-env-switcher.svelte
index 685ca99b7..3bd326531 100644
--- a/frontend/src/lib/components/sidebar/sidebar-env-switcher.svelte
+++ b/frontend/src/lib/components/sidebar/sidebar-env-switcher.svelte
@@ -5,7 +5,7 @@
import { useSidebar } from '$lib/components/ui/sidebar/index.js';
import ChevronsUpDownIcon from '@lucide/svelte/icons/chevrons-up-down';
import PlusIcon from '@lucide/svelte/icons/plus';
- import GlobeIcon from '@lucide/svelte/icons/globe';
+ import RouterIcon from '@lucide/svelte/icons/router';
import ServerIcon from '@lucide/svelte/icons/server';
import { environmentStore } from '$lib/stores/environment.store';
import type { Environment } from '$lib/types/environment.type';
@@ -13,6 +13,7 @@
import { toast } from 'svelte-sonner';
import { m } from '$lib/paraglide/messages';
import { cn } from '$lib/utils';
+ import settingsStore from '$lib/stores/config-store';
type Props = {
isAdmin?: boolean;
@@ -61,6 +62,14 @@
return env.name;
}
}
+
+ function getConnectionString(env: Environment): string {
+ if (env.isLocal) {
+ return $settingsStore.dockerHost || 'unix:///var/run/docker.sock';
+ } else {
+ return env.apiUrl;
+ }
+ }
</script>
<Sidebar.Menu>
@@ -86,7 +95,7 @@
{#if currentSelectedEnvironment.isLocal}
<ServerIcon class="size-4" />
{:else}
- <GlobeIcon class="size-4" />
+ <RouterIcon class="size-4" />
{/if}
</div>
<div class="grid flex-1 text-left text-sm leading-tight">
@@ -94,7 +103,7 @@
{getEnvLabel(currentSelectedEnvironment)}
</span>
<span class="truncate text-xs">
- {currentSelectedEnvironment.isLocal ? m.sidebar_local_docker_socket() : currentSelectedEnvironment.apiUrl}
+ {getConnectionString(currentSelectedEnvironment)}
</span>
</div>
{:else}
@@ -141,21 +150,31 @@
</DropdownMenu.Item>
{:else}
{#each availableEnvironments as env (env.id)}
- <DropdownMenu.Item onSelect={() => handleSelect(env)} class="gap-2 p-2">
- <div class="flex size-6 items-center justify-center rounded-md border">
+ {@const isActive = currentSelectedEnvironment?.id === env.id}
+ <DropdownMenu.Item
+ onSelect={() => !isActive && handleSelect(env)}
+ class={cn(
+ 'gap-2 p-2',
+ isActive && 'bg-sidebar-accent text-sidebar-accent-foreground pointer-events-none font-medium'
+ )}
+ >
+ <div
+ class={cn(
+ 'flex size-6 items-center justify-center rounded-md border',
+ isActive ? 'bg-sidebar-primary border-sidebar-primary' : 'border-border'
+ )}
+ >
{#if env.isLocal}
- <ServerIcon class="size-3.5 shrink-0" />
+ <ServerIcon class={cn('size-3.5 shrink-0', isActive && 'text-sidebar-primary-foreground')} />
{:else}
- <GlobeIcon class="size-3.5 shrink-0" />
+ <RouterIcon class={cn('size-3.5 shrink-0', isActive && 'text-sidebar-primary-foreground')} />
{/if}
</div>
<div class="flex flex-col">
<span>{getEnvLabel(env)}</span>
- {#if env.isLocal}
- <span class="text-muted-foreground text-xs">{m.sidebar_local_docker_socket()}</span>
- {:else}
- <span class="text-muted-foreground max-w-32 truncate text-xs">{env.apiUrl}</span>
- {/if}
+ <span class={cn('text-xs', isActive ? 'text-sidebar-accent-foreground/70' : 'text-muted-foreground')}>
+ {getConnectionString(env)}
+ </span>
</div>
</DropdownMenu.Item>
{/each}
diff --git a/frontend/src/lib/types/settings.type.ts b/frontend/src/lib/types/settings.type.ts
index 74a79f0b2..7ca67c894 100644
--- a/frontend/src/lib/types/settings.type.ts
+++ b/frontend/src/lib/types/settings.type.ts
@@ -18,6 +18,7 @@ export type Settings = {
enableGravatar: boolean;
uiConfigDisabled: boolean;
defaultShell: string;
+ dockerHost: string;
authLocalEnabled: boolean;
authOidcEnabled: boolean;
diff --git a/scripts/docker/entrypoint.sh b/scripts/docker/entrypoint.sh
index a7385b865..df1acec24 100644
--- a/scripts/docker/entrypoint.sh
+++ b/scripts/docker/entrypoint.sh
@@ -46,7 +46,10 @@ else
fi
# Handle Docker socket and group
-if [ -S /var/run/docker.sock ]; then
+# Skip socket configuration if using TCP proxy (DOCKER_HOST with tcp://)
+if [ -n "$DOCKER_HOST" ] && echo "$DOCKER_HOST" | grep -q "^tcp://"; then
+ echo "Entrypoint: Docker proxy mode detected (DOCKER_HOST=${DOCKER_HOST}), skipping socket setup"
+elif [ -S /var/run/docker.sock ]; then
SOCKET_GID=$(stat -c '%g' /var/run/docker.sock)
echo "Entrypoint: Docker socket found with GID ${SOCKET_GID}"
if [ "$SOCKET_GID" = "0" ]; then
diff --git a/tests/setup/compose-proxy.yaml b/tests/setup/compose-proxy.yaml
new file mode 100644
index 000000000..99e2620dc
--- /dev/null
+++ b/tests/setup/compose-proxy.yaml
@@ -0,0 +1,56 @@
+services:
+ docker-socket-proxy:
+ image: tecnativa/docker-socket-proxy:latest
+ container_name: arcane-docker-proxy-test
+ environment:
+ - EVENTS=1
+ - PING=1
+ - VERSION=1
+ - AUTH=0
+ - SECRETS=0
+ - POST=1
+ - BUILD=0
+ - COMMIT=0
+ - CONFIGS=0
+ - CONTAINERS=1
+ - DISTRIBUTION=0
+ - EXEC=1
+ - IMAGES=1
+ - INFO=1
+ - NETWORKS=1
+ - NODES=0
+ - PLUGINS=0
+ - SERVICES=0
+ - SESSION=0
+ - SWARM=0
+ - SYSTEM=0
+ - TASKS=0
+ - VOLUMES=1
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock:ro
+ restart: unless-stopped
+
+ arcane:
+ image: arcane:playwright-tests
+ user: root
+ ports:
+ - '3002:3552'
+ environment:
+ - ENVIRONMENT=testing
+ - APP_ENV=test
+ - ENCRYPTION_KEY=3JDIgolks2tJ9ymm1AdqzlYMWu0DUWyt
+ - JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
+ - DOCKER_HOST=tcp://docker-socket-proxy:2375
+ volumes:
+ - arcane_data:/app/data
+ - ./projects:/app/data/projects
+ depends_on:
+ - docker-socket-proxy
+ build:
+ args:
+ - BUILD_TAGS=playwright
+ context: ../..
+ dockerfile: docker/Dockerfile
+
+volumes:
+ arcane_data: