docs: add reviewer-facing comments for apple-container runtime

Add explanatory comments addressing likely review questions:
- Why strategy-via-conditionals instead of an interface
- Kong startup order change (IP resolution needs running containers)
- Analytics log forwarding architecture (no Docker log driver)
- PGDATA override for Apple container volume mounts
- KongId added to listServicesToRestart (behavioral change)
- Host header in kong.yml for Realtime tenant routing
- Stale container reconciliation rationale
- Apple volume delete lacks force flag

Also add saveResetTestState helper to reduce verbose save/restore
boilerplate in reset_test.go.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jsj

internal/db/reset/reset.go

@@ -110,6 +110,9 @@ func Run(ctx context.Context, version string, last uint, config pgconn.Config, f
 	return nil
 }
 
+// shouldRefreshAPIAfterReset returns true when Kong must be recreated after a
+// database reset.  Apple containers assign dynamic IPs, so Kong's cached
+// upstream addresses become stale when the database container is replaced.
 func shouldRefreshAPIAfterReset() bool {
 	return utils.UsesAppleContainerRuntime() && utils.Config.Api.Enabled
 }
@@ -303,6 +306,10 @@ func restartServices(ctx context.Context) error {
 	return errors.Join(result...)
 }
 
+// listServicesToRestart returns containers that need restarting after a
+// database reset.  Kong is included because it caches upstream addresses that
+// may change when the database container is recreated (especially on Apple
+// containers which use dynamic IPs).
 func listServicesToRestart() []string {
 	return []string{utils.StorageId, utils.GotrueId, utils.RealtimeId, utils.PoolerId, utils.KongId}
 }

internal/db/reset/reset_test.go

@@ -24,10 +24,83 @@ import (
 	"github.com/supabase/cli/internal/testing/apitest"
 	"github.com/supabase/cli/internal/testing/fstest"
 	"github.com/supabase/cli/internal/utils"
+	"github.com/supabase/cli/pkg/config"
 	"github.com/supabase/cli/pkg/pgtest"
 	"github.com/supabase/cli/pkg/storage"
 )
 
+// saveResetTestState captures and restores all package-level vars that the
+// apple-container reset tests override, reducing repetitive save/restore
+// boilerplate in individual test cases.
+func saveResetTestState(t *testing.T) {
+	t.Helper()
+	orig := struct {
+		runtime              string
+		apiEnabled           bool
+		assertRunning        func() error
+		removeContainer      func(context.Context, string, bool, bool) error
+		removeVolume         func(context.Context, string, bool) error
+		startContainer       func(context.Context, container.Config, container.HostConfig, network.NetworkingConfig, string) (string, error)
+		inspectContainer     func(context.Context, string) (utils.ContainerInfo, error)
+		restartContainer     func(context.Context, string) error
+		waitForHealthy       func(context.Context, time.Duration, ...string) error
+		waitForLocalDB       func(context.Context, time.Duration, ...func(*pgx.ConnConfig)) error
+		waitForLocalAPI      func(context.Context, time.Duration) error
+		setupLocalDB         func(context.Context, string, afero.Fs, io.Writer, ...func(*pgx.ConnConfig)) error
+		restartKongFn        func(context.Context, start.KongDependencies) error
+		runBucketSeedFn      func(context.Context, string, bool, afero.Fs) error
+		seedBucketsFn        func(context.Context, afero.Fs) error
+		dbId, storageId      string
+		gotrueId, realtimeId string
+		poolerId, kongId     string
+	}{
+		runtime:          string(utils.Config.Local.Runtime),
+		apiEnabled:       utils.Config.Api.Enabled,
+		assertRunning:    assertSupabaseDbIsRunning,
+		removeContainer:  removeContainer,
+		removeVolume:     removeVolume,
+		startContainer:   startContainer,
+		inspectContainer: inspectContainer,
+		restartContainer: restartContainer,
+		waitForHealthy:   waitForHealthyService,
+		waitForLocalDB:   waitForLocalDatabase,
+		waitForLocalAPI:  waitForLocalAPI,
+		setupLocalDB:     setupLocalDatabase,
+		restartKongFn:    restartKong,
+		runBucketSeedFn:  runBucketSeed,
+		seedBucketsFn:    seedBuckets,
+		dbId:             utils.DbId,
+		storageId:        utils.StorageId,
+		gotrueId:         utils.GotrueId,
+		realtimeId:       utils.RealtimeId,
+		poolerId:         utils.PoolerId,
+		kongId:           utils.KongId,
+	}
+	t.Cleanup(func() {
+		utils.Config.Local.Runtime = config.LocalRuntime(orig.runtime)
+		utils.Config.Api.Enabled = orig.apiEnabled
+		assertSupabaseDbIsRunning = orig.assertRunning
+		removeContainer = orig.removeContainer
+		removeVolume = orig.removeVolume
+		startContainer = orig.startContainer
+		inspectContainer = orig.inspectContainer
+		restartContainer = orig.restartContainer
+		waitForHealthyService = orig.waitForHealthy
+		waitForLocalDatabase = orig.waitForLocalDB
+		waitForLocalAPI = orig.waitForLocalAPI
+		setupLocalDatabase = orig.setupLocalDB
+		restartKong = orig.restartKongFn
+		runBucketSeed = orig.runBucketSeedFn
+		seedBuckets = orig.seedBucketsFn
+		utils.DbId = orig.dbId
+		utils.StorageId = orig.storageId
+		utils.GotrueId = orig.gotrueId
+		utils.RealtimeId = orig.realtimeId
+		utils.PoolerId = orig.poolerId
+		utils.KongId = orig.kongId
+	})
+}
+
 func TestResetCommand(t *testing.T) {
 	utils.Config.Hostname = "127.0.0.1"
 	utils.Config.Db.Port = 5432
@@ -170,49 +243,7 @@ func TestResetCommand(t *testing.T) {
 	})
 
 	t.Run("uses runtime helpers on apple container runtime", func(t *testing.T) {
-		originalRuntime := utils.Config.Local.Runtime
-		originalAPIEnabled := utils.Config.Api.Enabled
-		originalAssertRunning := assertSupabaseDbIsRunning
-		originalRemoveContainer := removeContainer
-		originalRemoveVolume := removeVolume
-		originalStartContainer := startContainer
-		originalInspectContainer := inspectContainer
-		originalRestartContainer := restartContainer
-		originalWaitForHealthyService := waitForHealthyService
-		originalWaitForLocalDatabase := waitForLocalDatabase
-		originalWaitForLocalAPI := waitForLocalAPI
-		originalSetupLocalDatabase := setupLocalDatabase
-		originalRestartKong := restartKong
-		originalRunBucketSeed := runBucketSeed
-		originalDbID := utils.DbId
-		originalStorageID := utils.StorageId
-		originalGotrueID := utils.GotrueId
-		originalRealtimeID := utils.RealtimeId
-		originalPoolerID := utils.PoolerId
-		originalKongID := utils.KongId
-
-		t.Cleanup(func() {
-			utils.Config.Local.Runtime = originalRuntime
-			utils.Config.Api.Enabled = originalAPIEnabled
-			assertSupabaseDbIsRunning = originalAssertRunning
-			removeContainer = originalRemoveContainer
-			removeVolume = originalRemoveVolume
-			startContainer = originalStartContainer
-			inspectContainer = originalInspectContainer
-			restartContainer = originalRestartContainer
-			waitForHealthyService = originalWaitForHealthyService
-			waitForLocalDatabase = originalWaitForLocalDatabase
-			waitForLocalAPI = originalWaitForLocalAPI
-			setupLocalDatabase = originalSetupLocalDatabase
-			restartKong = originalRestartKong
-			runBucketSeed = originalRunBucketSeed
-			utils.DbId = originalDbID
-			utils.StorageId = originalStorageID
-			utils.GotrueId = originalGotrueID
-			utils.RealtimeId = originalRealtimeID
-			utils.PoolerId = originalPoolerID
-			utils.KongId = originalKongID
-		})
+		saveResetTestState(t)
 
 		utils.Config.Local.Runtime = "apple-container"
 		utils.Config.Db.MajorVersion = 15

internal/db/start/start.go

@@ -40,6 +40,9 @@ var (
 	resolveContainerIP = utils.GetContainerIP
 )
 
+// runtimePostgresConfig returns the postgresql.conf snippet, adding a custom
+// data_directory on Apple containers to match the PGDATA env var override
+// (see NewContainerConfig).
 func runtimePostgresConfig() string {
 	settings := utils.Config.Db.Settings.ToPostgresConfig()
 	if utils.UsesAppleContainerRuntime() {
@@ -86,6 +89,9 @@ func NewContainerConfig(args ...string) container.Config {
 	} else if i := strings.IndexByte(utils.Config.Db.Image, ':'); config.VersionCompare(utils.Config.Db.Image[i+1:], "15.8.1.005") < 0 {
 		env = append(env, "POSTGRES_INITDB_ARGS=--lc-collate=C.UTF-8")
 	}
+	// Apple containers mount volumes at the top-level target directory, which
+	// conflicts with the default PGDATA location.  Using a subdirectory avoids
+	// the "initdb: directory is not empty" error on first start.
 	if utils.UsesAppleContainerRuntime() {
 		env = append(env, "PGDATA=/var/lib/postgresql/data/pgdata")
 	}

internal/start/start.go

@@ -178,6 +178,18 @@ var (
 	stopAppleAnalyticsForwarders  = utils.StopAppleAnalyticsForwarders
 )
 
+// Analytics log forwarding for Apple containers
+//
+// Apple containers do not expose a Docker-compatible log driver, so the
+// Vector `docker_logs` source cannot be used.  Instead we:
+//  1. Spawn a per-container "forwarder" process (`apple-log-forwarder`
+//     hidden CLI command) that tails `container logs --follow` and writes
+//     JSONL to a host directory.
+//  2. Mount that directory into the Vector container.
+//  3. Configure Vector with a `file` source that reads the JSONL files.
+//
+// The forwarder PIDs are tracked in a temp directory so `supabase stop`
+// can clean them up.
 const (
 	vectorSourceDockerLogs = "docker_logs"
 	vectorSourceFile       = "file"
@@ -205,6 +217,10 @@ func isPermanentError(err error) bool {
 	return true
 }
 
+// reconcileStaleProjectContainers removes stopped containers left over from a
+// previous run.  This prevents name collisions when starting new containers,
+// which is especially important on Apple containers where stopped containers
+// are not automatically cleaned up.
 func reconcileStaleProjectContainers(ctx context.Context, projectId string) error {
 	containers, err := listProjectContainers(ctx, projectId, true)
 	if err != nil {
@@ -221,6 +237,10 @@ func reconcileStaleProjectContainers(ctx context.Context, projectId string) erro
 	return nil
 }
 
+// runtimeContainerHost returns the hostname that other containers should use
+// to reach the given container.  Docker networks provide built-in DNS so the
+// container name works as a hostname.  Apple containers do not have DNS within
+// their networks, so we must resolve the container's IP address instead.
 func runtimeContainerHost(ctx context.Context, containerId string, resolve bool) (string, error) {
 	if !utils.UsesAppleContainerRuntime() || !resolve {
 		return containerId, nil
@@ -1427,7 +1447,10 @@ EOF
 		started = append(started, utils.PoolerId)
 	}
 
-	// Start Kong after its Apple-runtime upstreams exist.
+	// Start Kong after its upstream services are running.  Apple containers
+	// require IP resolution (no built-in DNS), so upstream containers must be
+	// alive before we can build Kong's declarative config.  This ordering is
+	// harmless for Docker where DNS aliases resolve regardless of start order.
 	if isKongEnabled {
 		if err := startKong(ctx, KongDependencies{
 			Gotrue:   isAuthEnabled,

internal/start/templates/kong.yml

@@ -112,6 +112,9 @@ services:
         config:
           add:
             headers:
+              # Apple containers resolve upstreams by IP, so the original Host
+              # header is an IP address.  Realtime requires the tenant ID as the
+              # Host to route requests correctly.
               - "Host: {{ .RealtimeTenantId }}"
           replace:
             querystring:

internal/utils/apple_container.go

@@ -127,6 +127,7 @@ func appleRemoveVolume(ctx context.Context, volumeName string, force bool) error
 
 func appleRemoveVolumeWithRun(ctx context.Context, volumeName string, force bool, run func(context.Context, ...string) (string, error)) error {
 	args := []string{"volume", "delete"}
+	// Apple container CLI does not support force-delete for volumes.
 	_ = force
 	args = append(args, volumeName)
 	if _, err := run(ctx, args...); err != nil {

internal/utils/runtime.go

@@ -16,6 +16,9 @@ import (
 	"github.com/go-errors/errors"
 )
 
+// healthcheckLabel stores the container's health-check command as a
+// base64-encoded JSON array inside a label.  Apple containers do not support
+// native health-checks, so the CLI runs the check itself via `container exec`.
 const healthcheckLabel = "com.supabase.cli.healthcheck"
 
 type ContainerMount struct {
@@ -100,6 +103,14 @@ func decodeHealthcheck(encoded string) ([]string, error) {
 	return test, nil
 }
 
+// The runtime dispatcher functions below use a simple if/else pattern rather
+// than an interface because:
+//   - There are only two runtimes (Docker, Apple Container).
+//   - Each Apple implementation is a thin wrapper around the `container` CLI,
+//     keeping the logic co-located and easy to follow.
+//   - An interface would require threading a runtime instance through many
+//     call sites that currently use package-level helpers.
+
 func DockerStart(ctx context.Context, config container.Config, hostConfig container.HostConfig, networkingConfig network.NetworkingConfig, containerName string) (string, error) {
 	if UsesAppleContainerRuntime() {
 		return appleStart(ctx, config, hostConfig, networkingConfig, containerName)