Mount Docker socket and add service port range (#103)

silv-io · web-flow · commit a28f8751ced4 · 2026-03-17T14:04:06.000+01:00
diff --git a/README.md b/README.md
@@ -141,6 +141,7 @@ lstk --non-interactive
 |---|---|
 | `LOCALSTACK_AUTH_TOKEN` | Auth token used for non-interactive runs or to skip browser login |
 | `LOCALSTACK_DISABLE_EVENTS=1` | Disables telemetry event reporting |
+| `DOCKER_HOST` | Override the Docker daemon socket (e.g. `unix:///home/user/.colima/default/docker.sock`). When unset, lstk tries the default socket and then probes common alternatives (Colima, OrbStack). |
 
 ## Usage
 
diff --git a/cmd/logout.go b/cmd/logout.go
@@ -29,7 +29,7 @@ func newLogoutCmd(cfg *env.Env, logger log.Logger) *cobra.Command {
 				return fmt.Errorf("failed to get config: %w", err)
 			}
 			var rt runtime.Runtime
-			if dockerRuntime, err := runtime.NewDockerRuntime(); err == nil {
+			if dockerRuntime, err := runtime.NewDockerRuntime(cfg.DockerHost); err == nil {
 				rt = dockerRuntime
 			}
 
diff --git a/cmd/logs.go b/cmd/logs.go
@@ -6,12 +6,13 @@ import (
 
 	"github.com/localstack/lstk/internal/config"
 	"github.com/localstack/lstk/internal/container"
+	"github.com/localstack/lstk/internal/env"
 	"github.com/localstack/lstk/internal/output"
 	"github.com/localstack/lstk/internal/runtime"
 	"github.com/spf13/cobra"
 )
 
-func newLogsCmd() *cobra.Command {
+func newLogsCmd(cfg *env.Env) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "logs",
 		Short:   "Show emulator logs",
@@ -22,7 +23,7 @@ func newLogsCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
-			rt, err := runtime.NewDockerRuntime()
+			rt, err := runtime.NewDockerRuntime(cfg.DockerHost)
 			if err != nil {
 				return err
 			}
diff --git a/cmd/root.go b/cmd/root.go
@@ -26,7 +26,7 @@ func NewRootCmd(cfg *env.Env, tel *telemetry.Client, logger log.Logger) *cobra.C
 		Long:    "lstk is the command-line interface for LocalStack.",
 		PreRunE: initConfig,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			rt, err := runtime.NewDockerRuntime()
+			rt, err := runtime.NewDockerRuntime(cfg.DockerHost)
 			if err != nil {
 				return err
 			}
@@ -53,7 +53,7 @@ func NewRootCmd(cfg *env.Env, tel *telemetry.Client, logger log.Logger) *cobra.C
 		newLoginCmd(cfg, logger),
 		newLogoutCmd(cfg, logger),
 		newStatusCmd(cfg),
-		newLogsCmd(),
+		newLogsCmd(cfg),
 		newConfigCmd(),
 		newVersionCmd(),
 		newUpdateCmd(cfg),
diff --git a/cmd/start.go b/cmd/start.go
@@ -15,7 +15,7 @@ func newStartCmd(cfg *env.Env, tel *telemetry.Client, logger log.Logger) *cobra.
 		Long:    "Start emulator and services.",
 		PreRunE: initConfig,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			rt, err := runtime.NewDockerRuntime()
+			rt, err := runtime.NewDockerRuntime(cfg.DockerHost)
 			if err != nil {
 				return err
 			}
diff --git a/cmd/status.go b/cmd/status.go
@@ -22,7 +22,7 @@ func newStatusCmd(cfg *env.Env) *cobra.Command {
 		Long:    "Show the status of a running emulator and its deployed resources",
 		PreRunE: initConfig,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			rt, err := runtime.NewDockerRuntime()
+			rt, err := runtime.NewDockerRuntime(cfg.DockerHost)
 			if err != nil {
 				return err
 			}
diff --git a/cmd/stop.go b/cmd/stop.go
@@ -20,7 +20,7 @@ func newStopCmd(cfg *env.Env) *cobra.Command {
 		Long:    "Stop emulator and services",
 		PreRunE: initConfig,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			rt, err := runtime.NewDockerRuntime()
+			rt, err := runtime.NewDockerRuntime(cfg.DockerHost)
 			if err != nil {
 				return err
 			}
diff --git a/internal/container/start.go b/internal/container/start.go
@@ -8,6 +8,7 @@ import (
 	"os"
 	stdruntime "runtime"
 	"slices"
+	"strconv"
 	"strings"
 	"time"
 
@@ -82,16 +83,31 @@ func Start(ctx context.Context, rt runtime.Runtime, sink output.Sink, opts Start
 		if err != nil {
 			return err
 		}
-		env := append(resolvedEnv, "LOCALSTACK_AUTH_TOKEN="+token)
+
+		containerName := c.Name()
+		env := append(resolvedEnv,
+			"LOCALSTACK_AUTH_TOKEN="+token,
+			"GATEWAY_LISTEN=:4566",
+			"MAIN_CONTAINER_NAME="+containerName,
+		)
+
+		var binds []runtime.BindMount
+		if socketPath := rt.SocketPath(); socketPath != "" {
+			binds = append(binds, runtime.BindMount{HostPath: socketPath, ContainerPath: "/var/run/docker.sock"})
+			env = append(env, "DOCKER_HOST=unix:///var/run/docker.sock")
+		}
+
 		containers[i] = runtime.ContainerConfig{
 			Image:         image,
-			Name:          c.Name(),
+			Name:          containerName,
 			Port:          c.Port,
 			ContainerPort: containerPort,
 			HealthPath:    healthPath,
 			Env:           env,
 			Tag:           c.Tag,
 			ProductName:   productName,
+			Binds:         binds,
+			ExtraPorts:    servicePortRange(),
 		}
 	}
 
@@ -341,3 +357,14 @@ func hasDuplicateContainerTypes(containers []config.ContainerConfig) bool {
 	}
 	return false
 }
+
+func servicePortRange() []runtime.PortMapping {
+	const start = 4510
+	const end = 4559
+	var ports []runtime.PortMapping
+	for p := start; p <= end; p++ {
+		ps := strconv.Itoa(p)
+		ports = append(ports, runtime.PortMapping{ContainerPort: ps, HostPort: ps})
+	}
+	return ports
+}
diff --git a/internal/container/start_test.go b/internal/container/start_test.go
@@ -5,6 +5,7 @@ import (
 	"context"
 	"errors"
 	"io"
+	"strconv"
 	"testing"
 
 	"github.com/localstack/lstk/internal/log"
@@ -56,3 +57,19 @@ func TestEmitPostStartPointers_WithoutWebApp(t *testing.T) {
 		out.String(),
 	)
 }
+
+func TestServicePortRange_Returns50Entries(t *testing.T) {
+	ports := servicePortRange()
+
+	require.Len(t, ports, 50)
+	assert.Equal(t, "4510", ports[0].ContainerPort)
+	assert.Equal(t, "4510", ports[0].HostPort)
+	assert.Equal(t, "4559", ports[49].ContainerPort)
+	assert.Equal(t, "4559", ports[49].HostPort)
+
+	for i, p := range ports {
+		expected := strconv.Itoa(4510 + i)
+		assert.Equal(t, expected, p.ContainerPort)
+		assert.Equal(t, expected, p.HostPort)
+	}
+}
diff --git a/internal/env/env.go b/internal/env/env.go
@@ -10,6 +10,7 @@ import (
 type Env struct {
 	AuthToken      string
 	LocalStackHost string
+	DockerHost     string
 	DisableEvents  bool
 
 	APIEndpoint       string
@@ -35,6 +36,7 @@ func Init() *Env {
 	return &Env{
 		AuthToken:         os.Getenv("LOCALSTACK_AUTH_TOKEN"),
 		LocalStackHost:    os.Getenv("LOCALSTACK_HOST"),
+		DockerHost:        os.Getenv("DOCKER_HOST"),
 		DisableEvents:     os.Getenv("LOCALSTACK_DISABLE_EVENTS") == "1",
 		APIEndpoint:       viper.GetString("api_endpoint"),
 		WebAppURL:         viper.GetString("web_app_url"),
diff --git a/internal/runtime/docker.go b/internal/runtime/docker.go
@@ -6,6 +6,8 @@ import (
 	"fmt"
 	"io"
 	"log"
+	"os"
+	"path/filepath"
 	stdruntime "runtime"
 	"strconv"
 	"strings"
@@ -25,14 +27,50 @@ type DockerRuntime struct {
 	client *client.Client
 }
 
-func NewDockerRuntime() (*DockerRuntime, error) {
-	cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
+func NewDockerRuntime(dockerHost string) (*DockerRuntime, error) {
+	opts := []client.Opt{client.FromEnv, client.WithAPIVersionNegotiation()}
+
+	// When DOCKER_HOST is not set, the Docker SDK defaults to /var/run/docker.sock.
+	// If that socket doesn't exist, probe known alternative locations (e.g. Colima).
+	if dockerHost == "" {
+		if sock := findDockerSocket(); sock != "" {
+			opts = append(opts, client.WithHost("unix://"+sock))
+		}
+	}
+
+	cli, err := client.NewClientWithOpts(opts...)
 	if err != nil {
 		return nil, err
 	}
 	return &DockerRuntime{client: cli}, nil
 }
 
+func findDockerSocket() string {
+	home, _ := os.UserHomeDir()
+	return probeSocket(
+		filepath.Join(home, ".colima", "default", "docker.sock"),
+		filepath.Join(home, ".colima", "docker.sock"),
+		filepath.Join(home, ".orbstack", "run", "docker.sock"),
+	)
+}
+
+func probeSocket(candidates ...string) string {
+	for _, sock := range candidates {
+		if _, err := os.Stat(sock); err == nil {
+			return sock
+		}
+	}
+	return ""
+}
+
+func (d *DockerRuntime) SocketPath() string {
+	host := d.client.DaemonHost()
+	if strings.HasPrefix(host, "unix://") {
+		return strings.TrimPrefix(host, "unix://")
+	}
+	return ""
+}
+
 func (d *DockerRuntime) IsHealthy(ctx context.Context) error {
 	_, err := d.client.Ping(ctx)
 	if err != nil {
@@ -113,6 +151,25 @@ func (d *DockerRuntime) Start(ctx context.Context, config ContainerConfig) (stri
 	exposedPorts := nat.PortSet{containerPort: struct{}{}}
 	portBindings := nat.PortMap{containerPort: []nat.PortBinding{{HostPort: config.Port}}}
 
+	for _, ep := range config.ExtraPorts {
+		proto := ep.Protocol
+		if proto == "" {
+			proto = "tcp"
+		}
+		p := nat.Port(ep.ContainerPort + "/" + proto)
+		exposedPorts[p] = struct{}{}
+		portBindings[p] = []nat.PortBinding{{HostPort: ep.HostPort}}
+	}
+
+	var binds []string
+	for _, b := range config.Binds {
+		bind := b.HostPath + ":" + b.ContainerPath
+		if b.ReadOnly {
+			bind += ":ro"
+		}
+		binds = append(binds, bind)
+	}
+
 	resp, err := d.client.ContainerCreate(ctx,
 		&container.Config{
 			Image:        config.Image,
@@ -121,6 +178,7 @@ func (d *DockerRuntime) Start(ctx context.Context, config ContainerConfig) (stri
 		},
 		&container.HostConfig{
 			PortBindings: portBindings,
+			Binds:        binds,
 		},
 		nil, nil, config.Name,
 	)
diff --git a/internal/runtime/docker_test.go b/internal/runtime/docker_test.go
@@ -0,0 +1,56 @@
+package runtime
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/docker/docker/client"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestProbeSocket_ReturnsFirstExisting(t *testing.T) {
+	dir := t.TempDir()
+	sock1 := filepath.Join(dir, "first.sock")
+	sock2 := filepath.Join(dir, "second.sock")
+
+	require.NoError(t, os.WriteFile(sock1, nil, 0o600))
+	require.NoError(t, os.WriteFile(sock2, nil, 0o600))
+
+	assert.Equal(t, sock1, probeSocket(sock1, sock2))
+}
+
+func TestProbeSocket_SkipsMissingAndReturnsExisting(t *testing.T) {
+	dir := t.TempDir()
+	missing := filepath.Join(dir, "missing.sock")
+	existing := filepath.Join(dir, "existing.sock")
+
+	require.NoError(t, os.WriteFile(existing, nil, 0o600))
+
+	assert.Equal(t, existing, probeSocket(missing, existing))
+}
+
+func TestProbeSocket_ReturnsEmptyWhenNoneExist(t *testing.T) {
+	assert.Equal(t, "", probeSocket("/no/such/path.sock", "/also/missing.sock"))
+}
+
+func TestProbeSocket_ReturnsEmptyForNoCandidates(t *testing.T) {
+	assert.Equal(t, "", probeSocket())
+}
+
+func TestSocketPath_ExtractsUnixPath(t *testing.T) {
+	cli, err := client.NewClientWithOpts(client.WithHost("unix:///home/user/.colima/default/docker.sock"))
+	require.NoError(t, err)
+	rt := &DockerRuntime{client: cli}
+
+	assert.Equal(t, "/home/user/.colima/default/docker.sock", rt.SocketPath())
+}
+
+func TestSocketPath_ReturnsEmptyForTCPHost(t *testing.T) {
+	cli, err := client.NewClientWithOpts(client.WithHost("tcp://192.168.1.100:2375"))
+	require.NoError(t, err)
+	rt := &DockerRuntime{client: cli}
+
+	assert.Equal(t, "", rt.SocketPath())
+}
diff --git a/internal/runtime/mock_runtime.go b/internal/runtime/mock_runtime.go
diff --git a/internal/runtime/runtime.go b/internal/runtime/runtime.go
@@ -8,6 +8,20 @@ import (
 	"github.com/localstack/lstk/internal/output"
 )
 
+// BindMount represents a host-to-container bind mount.
+type BindMount struct {
+	HostPath      string
+	ContainerPath string
+	ReadOnly      bool
+}
+
+// PortMapping represents a container-to-host port mapping.
+type PortMapping struct {
+	ContainerPort string
+	HostPort      string
+	Protocol      string // "tcp" (default) or "udp"
+}
+
 type ContainerConfig struct {
 	Image         string
 	Name          string
@@ -17,6 +31,8 @@ type ContainerConfig struct {
 	Env           []string // e.g., ["KEY=value", "FOO=bar"]
 	Tag           string
 	ProductName   string
+	Binds         []BindMount
+	ExtraPorts    []PortMapping
 }
 
 type PullProgress struct {
@@ -39,4 +55,5 @@ type Runtime interface {
 	Logs(ctx context.Context, containerID string, tail int) (string, error)
 	StreamLogs(ctx context.Context, containerID string, out io.Writer, follow bool) error
 	GetImageVersion(ctx context.Context, imageName string) (string, error)
+	SocketPath() string
 }
diff --git a/test/integration/start_test.go b/test/integration/start_test.go

Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,7 @@ func newLogoutCmd(cfg env.Env, logger log.Logger) cobra.Command {`
`29`	`29`	`return fmt.Errorf("failed to get config: %w", err)`
`30`	`30`	`}`
`31`	`31`	`var rt runtime.Runtime`
`32`		`- if dockerRuntime, err := runtime.NewDockerRuntime(); err == nil {`
	`32`	`+ if dockerRuntime, err := runtime.NewDockerRuntime(cfg.DockerHost); err == nil {`
`33`	`33`	`rt = dockerRuntime`
`34`	`34`	`}`
`35`	`35`
Original file line number	Diff line number	Diff line change
`@@ -15,7 +15,7 @@ func newStartCmd(cfg env.Env, tel telemetry.Client, logger log.Logger) *cobra.`
`15`	`15`	`Long: "Start emulator and services.",`
`16`	`16`	`PreRunE: initConfig,`
`17`	`17`	`RunE: func(cmd *cobra.Command, args []string) error {`
`18`		`- rt, err := runtime.NewDockerRuntime()`
	`18`	`+ rt, err := runtime.NewDockerRuntime(cfg.DockerHost)`
`19`	`19`	`if err != nil {`
`20`	`20`	`return err`
`21`	`21`	`}`
Original file line number	Diff line number	Diff line change
`@@ -22,7 +22,7 @@ func newStatusCmd(cfg env.Env) cobra.Command {`
`22`	`22`	`Long: "Show the status of a running emulator and its deployed resources",`
`23`	`23`	`PreRunE: initConfig,`
`24`	`24`	`RunE: func(cmd *cobra.Command, args []string) error {`
`25`		`- rt, err := runtime.NewDockerRuntime()`
	`25`	`+ rt, err := runtime.NewDockerRuntime(cfg.DockerHost)`
`26`	`26`	`if err != nil {`
`27`	`27`	`return err`
`28`	`28`	`}`
Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,7 @@ func newStopCmd(cfg env.Env) cobra.Command {`
`20`	`20`	`Long: "Stop emulator and services",`
`21`	`21`	`PreRunE: initConfig,`
`22`	`22`	`RunE: func(cmd *cobra.Command, args []string) error {`
`23`		`- rt, err := runtime.NewDockerRuntime()`
	`23`	`+ rt, err := runtime.NewDockerRuntime(cfg.DockerHost)`
`24`	`24`	`if err != nil {`
`25`	`25`	`return err`
`26`	`26`	`}`