docs: expand Important note — HOST_DATA_DIR must be absolute path

Explain why relative paths break container builds and add usage example.
Addresses sneak's review feedback on PR #126.

Dockerfile

@@ -1,11 +1,11 @@
 # Build stage
-FROM golang:1.25-alpine AS builder
+FROM golang@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4ced AS builder # golang:1.25-alpine
 
 RUN apk add --no-cache git make gcc musl-dev
 
 # Install golangci-lint v2
-RUN go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
+RUN go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@5d1e709b7be35cb2025444e19de266b056b7b7ee # v2.10.1
-RUN go install golang.org/x/tools/cmd/goimports@latest
+RUN go install golang.org/x/tools/cmd/goimports@009367f5c17a8d4c45a961a3a509277190a9a6f0 # v0.42.0
 
 WORKDIR /src
 COPY go.mod go.sum ./
@@ -20,7 +20,7 @@ RUN make check
 RUN make build
 
 # Runtime stage
-FROM alpine:3.19
+FROM alpine@sha256:6baf43584bcb78f2e5847d1de515f23499913ac9f12bdf834811a3145eb11ca1 # alpine:3.19
 
 RUN apk add --no-cache ca-certificates tzdata git openssh-client docker-cli
 

README.md

@@ -157,8 +157,8 @@ Environment variables:
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `PORT` | HTTP listen port | 8080 |
-| `UPAAS_DATA_DIR` | Data directory for SQLite and keys | ./data |
+| `UPAAS_DATA_DIR` | Data directory for SQLite and keys | `./data` (local dev only — use absolute path for Docker) |
-| `UPAAS_HOST_DATA_DIR` | Host path for DATA_DIR (when running in container) | same as DATA_DIR |
+| `UPAAS_HOST_DATA_DIR` | Host path for DATA_DIR (when running in container) | *(none — must be set to an absolute path)* |
 | `UPAAS_DOCKER_HOST` | Docker socket path | unix:///var/run/docker.sock |
 | `DEBUG` | Enable debug logging | false |
 | `SENTRY_DSN` | Sentry error reporting DSN | "" |
@@ -199,16 +199,12 @@ services:
       # - METRICS_PASSWORD=secret
 ```
 
-**Important**: Set `HOST_DATA_DIR` to an **absolute path** on the Docker host before running
+**Important**: You **must** set `HOST_DATA_DIR` to an **absolute path** on the host before running
-`docker compose up`. Relative paths will not work because docker-compose may not run on the same
+`docker compose up`. This value is bind-mounted into the container and passed as `UPAAS_HOST_DATA_DIR`
-machine as µPaaS. This value is used both for the bind mount and passed to µPaaS as
+so that Docker bind mounts during builds resolve correctly. Relative paths (e.g. `./data`) will break
-`UPAAS_HOST_DATA_DIR` so it can create correct bind mounts during builds.
+container builds because the Docker daemon resolves paths relative to the host, not the container.
 
-Example:
+Example: `HOST_DATA_DIR=/srv/upaas/data docker compose up -d`
-```bash
-export HOST_DATA_DIR=/srv/upaas-data
-docker compose up -d
-```
 
 Session secrets are automatically generated on first startup and persisted to `$UPAAS_DATA_DIR/session.key`.
 

internal/database/testing.go

@@ -0,0 +1,41 @@
+package database
+
+import (
+	"log/slog"
+	"os"
+	"testing"
+
+	"git.eeqj.de/sneak/upaas/internal/config"
+	"git.eeqj.de/sneak/upaas/internal/logger"
+)
+
+// NewTestDatabase creates an in-memory Database for testing.
+// It runs migrations so all tables are available.
+func NewTestDatabase(t *testing.T) *Database {
+	t.Helper()
+
+	tmpDir := t.TempDir()
+
+	cfg := &config.Config{
+		DataDir: tmpDir,
+	}
+
+	log := slog.New(slog.NewTextHandler(os.Stderr, nil))
+	logWrapper := logger.NewForTest(log)
+
+	db, err := New(nil, Params{
+		Logger: logWrapper,
+		Config: cfg,
+	})
+	if err != nil {
+		t.Fatalf("failed to create test database: %v", err)
+	}
+
+	t.Cleanup(func() {
+		if db.database != nil {
+			_ = db.database.Close()
+		}
+	})
+
+	return db
+}

internal/docker/client.go

@@ -26,6 +26,7 @@ import (
 	"go.uber.org/fx"
 
 	"git.eeqj.de/sneak/upaas/internal/config"
+
 	"git.eeqj.de/sneak/upaas/internal/logger"
 )
 
@@ -252,7 +253,7 @@ func (c *Client) StartContainer(ctx context.Context, containerID ContainerID) er
 
 	c.log.Info("starting container", "id", containerID)
 
-	err := c.docker.ContainerStart(ctx, string(containerID), container.StartOptions{})
+	err := c.docker.ContainerStart(ctx, containerID.String(), container.StartOptions{})
 	if err != nil {
 		return fmt.Errorf("failed to start container: %w", err)
 	}
@@ -270,7 +271,7 @@ func (c *Client) StopContainer(ctx context.Context, containerID ContainerID) err
 
 	timeout := stopTimeoutSeconds
 
-	err := c.docker.ContainerStop(ctx, string(containerID), container.StopOptions{Timeout: &timeout})
+	err := c.docker.ContainerStop(ctx, containerID.String(), container.StopOptions{Timeout: &timeout})
 	if err != nil {
 		return fmt.Errorf("failed to stop container: %w", err)
 	}
@@ -290,7 +291,7 @@ func (c *Client) RemoveContainer(
 
 	c.log.Info("removing container", "id", containerID, "force", force)
 
-	err := c.docker.ContainerRemove(ctx, string(containerID), container.RemoveOptions{Force: force})
+	err := c.docker.ContainerRemove(ctx, containerID.String(), container.RemoveOptions{Force: force})
 	if err != nil {
 		return fmt.Errorf("failed to remove container: %w", err)
 	}
@@ -314,7 +315,7 @@ func (c *Client) ContainerLogs(
 		Tail:       tail,
 	}
 
-	reader, err := c.docker.ContainerLogs(ctx, string(containerID), opts)
+	reader, err := c.docker.ContainerLogs(ctx, containerID.String(), opts)
 	if err != nil {
 		return "", fmt.Errorf("failed to get container logs: %w", err)
 	}
@@ -343,7 +344,7 @@ func (c *Client) IsContainerRunning(
 		return false, ErrNotConnected
 	}
 
-	inspect, err := c.docker.ContainerInspect(ctx, string(containerID))
+	inspect, err := c.docker.ContainerInspect(ctx, containerID.String())
 	if err != nil {
 		return false, fmt.Errorf("failed to inspect container: %w", err)
 	}
@@ -360,7 +361,7 @@ func (c *Client) IsContainerHealthy(
 		return false, ErrNotConnected
 	}
 
-	inspect, err := c.docker.ContainerInspect(ctx, string(containerID))
+	inspect, err := c.docker.ContainerInspect(ctx, containerID.String())
 	if err != nil {
 		return false, fmt.Errorf("failed to inspect container: %w", err)
 	}
@@ -483,7 +484,7 @@ func (c *Client) CloneRepo(
 // RemoveImage removes a Docker image by ID or tag.
 // It returns nil if the image was successfully removed or does not exist.
 func (c *Client) RemoveImage(ctx context.Context, imageID ImageID) error {
-	_, err := c.docker.ImageRemove(ctx, string(imageID), image.RemoveOptions{
+	_, err := c.docker.ImageRemove(ctx, imageID.String(), image.RemoveOptions{
 		Force:         true,
 		PruneChildren: true,
 	})
@@ -609,7 +610,7 @@ func (c *Client) performClone(ctx context.Context, cfg *cloneConfig) (*CloneResu
 	}
 
 	defer func() {
-		_ = c.docker.ContainerRemove(ctx, string(gitContainerID), container.RemoveOptions{Force: true})
+		_ = c.docker.ContainerRemove(ctx, gitContainerID.String(), container.RemoveOptions{Force: true})
 	}()
 
 	return c.runGitClone(ctx, gitContainerID)
@@ -679,12 +680,12 @@ func (c *Client) createGitContainer(
 }
 
 func (c *Client) runGitClone(ctx context.Context, containerID ContainerID) (*CloneResult, error) {
-	err := c.docker.ContainerStart(ctx, string(containerID), container.StartOptions{})
+	err := c.docker.ContainerStart(ctx, containerID.String(), container.StartOptions{})
 	if err != nil {
 		return nil, fmt.Errorf("failed to start git container: %w", err)
 	}
 
-	statusCh, errCh := c.docker.ContainerWait(ctx, string(containerID), container.WaitConditionNotRunning)
+	statusCh, errCh := c.docker.ContainerWait(ctx, containerID.String(), container.WaitConditionNotRunning)
 
 	select {
 	case err := <-errCh:

internal/docker/types.go

@@ -3,5 +3,11 @@ package docker
 // ImageID is a Docker image identifier (ID or tag).
 type ImageID string
 
+// String implements the fmt.Stringer interface.
+func (id ImageID) String() string { return string(id) }
+
 // ContainerID is a Docker container identifier.
 type ContainerID string
+
+// String implements the fmt.Stringer interface.
+func (id ContainerID) String() string { return string(id) }

internal/logger/testing.go

@@ -0,0 +1,11 @@
+package logger
+
+import "log/slog"
+
+// NewForTest creates a Logger wrapping the given slog.Logger, for use in tests.
+func NewForTest(log *slog.Logger) *Logger {
+	return &Logger{
+		log:   log,
+		level: new(slog.LevelVar),
+	}
+}

internal/service/deploy/deploy.go

@@ -431,8 +431,8 @@ func (svc *Service) executeRollback(
 		return fmt.Errorf("failed to create rollback container: %w", err)
 	}
 
-	deployment.ContainerID = sql.NullString{String: string(containerID), Valid: true}
+	deployment.ContainerID = sql.NullString{String: containerID.String(), Valid: true}
-	_ = deployment.AppendLog(bgCtx, "Rollback container created: "+string(containerID))
+	_ = deployment.AppendLog(bgCtx, "Rollback container created: "+containerID.String())
 
 	startErr := svc.docker.StartContainer(ctx, containerID)
 	if startErr != nil {
@@ -695,11 +695,11 @@ func (svc *Service) cleanupCancelledDeploy(
 		if removeErr != nil {
 			svc.log.Error("failed to remove image from cancelled deploy",
 				"error", removeErr, "app", app.Name, "image", imageID)
-			_ = deployment.AppendLog(ctx, "WARNING: failed to clean up image "+string(imageID)+": "+removeErr.Error())
+			_ = deployment.AppendLog(ctx, "WARNING: failed to clean up image "+imageID.String()+": "+removeErr.Error())
 		} else {
 			svc.log.Info("cleaned up image from cancelled deploy",
 				"app", app.Name, "image", imageID)
-			_ = deployment.AppendLog(ctx, "Cleaned up intermediate image: "+string(imageID))
+			_ = deployment.AppendLog(ctx, "Cleaned up intermediate image: "+imageID.String())
 		}
 	}
 
@@ -850,8 +850,8 @@ func (svc *Service) buildImage(
 		return "", fmt.Errorf("failed to build image: %w", err)
 	}
 
-	deployment.ImageID = sql.NullString{String: string(imageID), Valid: true}
+	deployment.ImageID = sql.NullString{String: imageID.String(), Valid: true}
-	_ = deployment.AppendLog(ctx, "Image built: "+string(imageID))
+	_ = deployment.AppendLog(ctx, "Image built: "+imageID.String())
 
 	return imageID, nil
 }
@@ -1038,8 +1038,8 @@ func (svc *Service) createAndStartContainer(
 		return "", fmt.Errorf("failed to create container: %w", err)
 	}
 
-	deployment.ContainerID = sql.NullString{String: string(containerID), Valid: true}
+	deployment.ContainerID = sql.NullString{String: containerID.String(), Valid: true}
-	_ = deployment.AppendLog(ctx, "Container created: "+string(containerID))
+	_ = deployment.AppendLog(ctx, "Container created: "+containerID.String())
 
 	startErr := svc.docker.StartContainer(ctx, containerID)
 	if startErr != nil {
@@ -1096,7 +1096,7 @@ func (svc *Service) buildContainerOptions(
 
 	return docker.CreateContainerOptions{
 		Name:    "upaas-" + app.Name,
-		Image:   string(imageID),
+		Image:   imageID.String(),
 		Env:     envMap,
 		Labels:  buildLabelMap(app, labels),
 		Volumes: buildVolumeMounts(volumes),
@@ -1148,7 +1148,7 @@ func (svc *Service) updateAppRunning(
 	app *models.App,
 	imageID docker.ImageID,
 ) error {
-	app.ImageID = sql.NullString{String: string(imageID), Valid: true}
+	app.ImageID = sql.NullString{String: imageID.String(), Valid: true}
 	app.Status = models.AppStatusRunning
 
 	saveErr := app.Save(ctx)

internal/service/deploy/deploy_container_test.go

@@ -0,0 +1,45 @@
+package deploy_test
+
+import (
+	"context"
+	"log/slog"
+	"os"
+	"testing"
+
+	"git.eeqj.de/sneak/upaas/internal/database"
+	"git.eeqj.de/sneak/upaas/internal/docker"
+	"git.eeqj.de/sneak/upaas/internal/models"
+	"git.eeqj.de/sneak/upaas/internal/service/deploy"
+)
+
+func TestBuildContainerOptionsUsesImageID(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDatabase(t)
+
+	app := models.NewApp(db)
+	app.Name = "myapp"
+
+	err := app.Save(context.Background())
+	if err != nil {
+		t.Fatalf("failed to save app: %v", err)
+	}
+
+	log := slog.New(slog.NewTextHandler(os.Stderr, nil))
+	svc := deploy.NewTestService(log)
+
+	const expectedImageID = docker.ImageID("sha256:abc123def456")
+
+	opts, err := svc.BuildContainerOptionsExported(context.Background(), app, expectedImageID)
+	if err != nil {
+		t.Fatalf("buildContainerOptions returned error: %v", err)
+	}
+
+	if opts.Image != expectedImageID.String() {
+		t.Errorf("expected Image=%q, got %q", expectedImageID, opts.Image)
+	}
+
+	if opts.Name != "upaas-myapp" {
+		t.Errorf("expected Name=%q, got %q", "upaas-myapp", opts.Name)
+	}
+}

internal/service/deploy/export_test.go

@@ -10,6 +10,7 @@ import (
 
 	"git.eeqj.de/sneak/upaas/internal/config"
 	"git.eeqj.de/sneak/upaas/internal/docker"
+	"git.eeqj.de/sneak/upaas/internal/models"
 )
 
 // NewTestService creates a Service with minimal dependencies for testing.
@@ -80,3 +81,12 @@ func (svc *Service) CleanupCancelledDeploy(
 func (svc *Service) GetBuildDirExported(appName string) string {
 	return svc.GetBuildDir(appName)
 }
+
+// BuildContainerOptionsExported exposes buildContainerOptions for testing.
+func (svc *Service) BuildContainerOptionsExported(
+	ctx context.Context,
+	app *models.App,
+	imageID docker.ImageID,
+) (docker.CreateContainerOptions, error) {
+	return svc.buildContainerOptions(ctx, app, imageID)
+}

internal/service/webhook/types.go

@@ -5,3 +5,6 @@ package webhook
 // but should not be parsed into a net/url.URL (e.g. webhook URLs,
 // compare URLs from external payloads).
 type UnparsedURL string
+
+// String implements the fmt.Stringer interface.
+func (u UnparsedURL) String() string { return string(u) }

internal/service/webhook/webhook.go

@@ -11,6 +11,7 @@ import (
 	"go.uber.org/fx"
 
 	"git.eeqj.de/sneak/upaas/internal/database"
+
 	"git.eeqj.de/sneak/upaas/internal/logger"
 	"git.eeqj.de/sneak/upaas/internal/models"
 	"git.eeqj.de/sneak/upaas/internal/service/deploy"
@@ -104,7 +105,7 @@ func (svc *Service) HandleWebhook(
 	event.EventType = eventType
 	event.Branch = branch
 	event.CommitSHA = sql.NullString{String: commitSHA, Valid: commitSHA != ""}
-	event.CommitURL = sql.NullString{String: string(commitURL), Valid: commitURL != ""}
+	event.CommitURL = sql.NullString{String: commitURL.String(), Valid: commitURL != ""}
 	event.Payload = sql.NullString{String: string(payload), Valid: true}
 	event.Matched = matched
 	event.Processed = false
@@ -178,7 +179,7 @@ func extractCommitURL(payload GiteaPushPayload) UnparsedURL {
 
 	// Fall back to constructing URL from repo HTML URL
 	if payload.Repository.HTMLURL != "" && payload.After != "" {
-		return UnparsedURL(string(payload.Repository.HTMLURL) + "/commit/" + payload.After)
+		return UnparsedURL(payload.Repository.HTMLURL.String() + "/commit/" + payload.After)
 	}
 
 	return ""