fix(docs): use UID-scoped PostgreSQL directories to fix non-root permission errors (#6205)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: thesandlord

servers/self-hosted/scripts/generate.sh

@@ -173,52 +173,55 @@ log "Base path: ${NEXT_PUBLIC_BASE_PATH:-'(none)'}"
 # -----------  Start PostgreSQL  -----------
 log "Starting PostgreSQL for seeding..."
 
-export PGDATA=/tmp/postgresql/data
-export PGHOST=/tmp
-
-rm -rf "$PGDATA" 2>/dev/null || true
+# Use UID-scoped directories to avoid permission conflicts
+# This prevents issues when build runs with different UIDs
+CURRENT_UID=$(id -u)
+export PGBASE="/tmp/postgresql-${CURRENT_UID}"
+export PGDATA="${PGBASE}/data"
+export PGHOST="${PGBASE}"
+
+rm -rf "$PGBASE" 2>/dev/null || true
 mkdir -p "$PGDATA"
 
 # Ensure postgres user owns the data directory (needed when running as root)
-if [ "$(id -u)" = "0" ]; then
-    chown -R postgres:postgres "$PGDATA"
-    chown postgres:postgres /tmp
+if [ "$CURRENT_UID" = "0" ]; then
+    chown -R postgres:postgres "$PGBASE"
 fi
 
-log "Initializing PostgreSQL cluster..."
+log "Initializing PostgreSQL cluster in $PGDATA (UID: $CURRENT_UID)..."
 run_as_postgres "PGDATA=$PGDATA initdb -D $PGDATA --auth-local=trust --auth-host=trust --username=postgres" 2>&1 || {
     log "ERROR: Failed to initialize PostgreSQL"
     exit 1
 }
 
-run_as_postgres "PGDATA=$PGDATA pg_ctl -D $PGDATA -o \"-c listen_addresses='localhost' -c unix_socket_directories='/tmp' -c shared_buffers=128MB -c max_connections=200\" -l $PGDATA/logfile start" 2>&1 || {
+run_as_postgres "PGDATA=$PGDATA pg_ctl -D $PGDATA -o \"-c listen_addresses='localhost' -c unix_socket_directories='$PGBASE' -c shared_buffers=128MB -c max_connections=200\" -l $PGDATA/logfile start" 2>&1 || {
     log "ERROR: Failed to start PostgreSQL"
     exit 1
 }
 
-# Wait for PostgreSQL to be ready
+# Wait for PostgreSQL to be ready (use UID-scoped socket directory)
 for i in {1..30}; do
-    if pg_isready -h /tmp -p 5432 2>/dev/null; then
+    if pg_isready -h "$PGBASE" -p 5432 2>/dev/null; then
         log "PostgreSQL is ready"
         break
     fi
     log "Waiting for PostgreSQL... ($i/30)"
     sleep 1
 done
 
-# Create database
-run_as_postgres "createdb -h /tmp -p 5432 -U postgres fdr" 2>&1 | add_timestamps || log "Database 'fdr' may already exist"
+# Create database (use UID-scoped socket directory)
+run_as_postgres "createdb -h $PGBASE -p 5432 -U postgres fdr" 2>&1 | add_timestamps || log "Database 'fdr' may already exist"
 
 # Restore schema from base image dump or run migrations
 if [ "$USE_BASE_SCHEMA" = "true" ]; then
     log "Restoring database schema from base image dump..."
-    run_as_postgres "pg_restore -h /tmp -p 5432 -U postgres -d fdr --clean --if-exists $BASE_SCHEMA_DUMP" 2>&1 | add_timestamps || {
+    run_as_postgres "pg_restore -h $PGBASE -p 5432 -U postgres -d fdr --clean --if-exists $BASE_SCHEMA_DUMP" 2>&1 | add_timestamps || {
         log "Warning: pg_restore had some errors (this may be normal for clean restore)"
     }
     log "Schema restored from base image dump"
 else
     log "Running Prisma migrations..."
-    DATABASE_URL=postgresql://postgres:postgres@localhost:5432/fdr \
+    DATABASE_URL="postgresql://postgres:postgres@localhost:5432/fdr?host=${PGBASE}" \
         prisma migrate deploy --schema /prisma/schema.prisma 2>&1 | add_timestamps || {
         log "ERROR: Prisma migrations failed"
         exit 1
@@ -247,6 +250,12 @@ done
 # -----------  Start MinIO  -----------
 log "Starting MinIO for seeding..."
 
+# Configure MinIO client (mc) to use a writable config directory
+# When running as an arbitrary UID that doesn't exist in /etc/passwd,
+# $HOME may default to "/" which isn't writable, causing "mc alias set" to fail.
+export MC_CONFIG_DIR="/tmp/mc-config"
+mkdir -p "$MC_CONFIG_DIR" 2>/dev/null || true
+
 # Use /data for MinIO (will be copied to seed dir later)
 minio server /data --console-address ":9001" 2>&1 &
 minio_pid=$!
@@ -357,7 +366,7 @@ log "=========================================="
 
 # Dump PostgreSQL database (full data, not just schema)
 log "Dumping PostgreSQL database..."
-run_as_postgres "pg_dump -h /tmp -p 5432 -U postgres -Fc fdr" > "$SEED_POSTGRES_DUMP" || {
+run_as_postgres "pg_dump -h $PGBASE -p 5432 -U postgres -Fc fdr" > "$SEED_POSTGRES_DUMP" || {
     log "ERROR: Failed to dump PostgreSQL database"
     exit 1
 }

servers/self-hosted/scripts/readiness.sh

@@ -23,7 +23,14 @@ check_http_endpoint() {
 }
 
 check_postgres() {
-    if pg_isready -h /tmp -p 5432 > /dev/null 2>&1; then
+    # Read the PostgreSQL socket directory from the file written by run.sh
+    # This supports UID-scoped directories used for non-root compatibility
+    local pg_socket_dir="/tmp"
+    if [ -f /tmp/postgres-socket-dir ]; then
+        pg_socket_dir=$(cat /tmp/postgres-socket-dir)
+    fi
+    
+    if pg_isready -h "$pg_socket_dir" -p 5432 > /dev/null 2>&1; then
         echo "✓ PostgreSQL is ready"
         return 0
     else

servers/self-hosted/scripts/run.sh

@@ -68,31 +68,42 @@ log "Starting PostgreSQL service..."
 start_postgresql() {
     local CURRENT_UID=$(id -u)
 
-    # Always use /tmp for PostgreSQL to work with any UID
-    export PGDATA=/tmp/postgresql/data
-    export PGHOST=/tmp
-
-    # Clean up any previous attempts
+    # Use UID-scoped directories to avoid permission conflicts when container
+    # is restarted with a different UID (e.g., root -> non-root or vice versa)
+    # This prevents "Permission denied" errors from stale directories owned by other UIDs
+    export PGBASE="/tmp/postgresql-${CURRENT_UID}"
+    export PGDATA="${PGBASE}/data"
+    export PGHOST="${PGBASE}"
+
+    # Clean up any previous attempts for THIS UID
     rm -rf "$PGDATA" 2>/dev/null || true
+    rm -rf "$PGBASE" 2>/dev/null || true
     mkdir -p "$PGDATA"
 
     log "Initializing PostgreSQL cluster in $PGDATA (UID: $CURRENT_UID)..."
 
+    # Verify we have proper access to the directory
+    if [ ! -w "$PGDATA" ] || [ ! -x "$PGDATA" ]; then
+        log "ERROR: Cannot write to or execute in $PGDATA"
+        ls -ld "$PGBASE" "$PGDATA" 2>&1 | add_timestamps || true
+        return 1
+    fi
+
     # Check if running as root - root cannot run initdb directly
     if [ "$CURRENT_UID" -eq 0 ]; then
         log "Running as root, using 'su - postgres' to initialize and run PostgreSQL..."
 
         # Change ownership of the data directory to postgres user
-        chown -R postgres:postgres "$PGDATA"
+        chown -R postgres:postgres "$PGBASE"
 
         # Initialize as postgres user
         if ! su - postgres -c "initdb -D $PGDATA --auth-local=trust --auth-host=trust --username=postgres" 2>&1 | add_timestamps; then
             log "ERROR: Failed to initialize PostgreSQL as postgres user"
             return 1
         fi
 
-        # Start PostgreSQL as postgres user
-        if ! su - postgres -c "pg_ctl -D $PGDATA -o \"-c listen_addresses='localhost' -c unix_socket_directories='/tmp' -c shared_buffers=128MB -c max_connections=200 -c logging_collector=on -c log_line_prefix='%t '\" -l $PGDATA/logfile start" 2>&1 | add_timestamps; then
+        # Start PostgreSQL as postgres user with UID-scoped socket directory
+        if ! su - postgres -c "pg_ctl -D $PGDATA -o \"-c listen_addresses='localhost' -c unix_socket_directories='$PGBASE' -c shared_buffers=128MB -c max_connections=200 -c logging_collector=on -c log_line_prefix='%t '\" -l $PGDATA/logfile start" 2>&1 | add_timestamps; then
             log "ERROR: Failed to start PostgreSQL"
             cat "$PGDATA/logfile" 2>/dev/null | add_timestamps
             return 1
@@ -106,9 +117,9 @@ start_postgresql() {
             return 1
         fi
 
-        # Start PostgreSQL
+        # Start PostgreSQL with UID-scoped socket directory
         if ! pg_ctl -D "$PGDATA" \
-            -o "-c listen_addresses='localhost' -c unix_socket_directories='/tmp' -c shared_buffers=128MB -c max_connections=200 -c logging_collector=on -c log_line_prefix='%t '" \
+            -o "-c listen_addresses='localhost' -c unix_socket_directories='$PGBASE' -c shared_buffers=128MB -c max_connections=200 -c logging_collector=on -c log_line_prefix='%t '" \
             -l "$PGDATA/logfile" \
             start 2>&1 | add_timestamps; then
             log "ERROR: Failed to start PostgreSQL"
@@ -119,27 +130,30 @@ start_postgresql() {
 
     log "PostgreSQL started successfully"
 
-    # Wait for PostgreSQL to be ready
+    # Wait for PostgreSQL to be ready (use UID-scoped socket directory)
     for i in {1..30}; do
-        if pg_isready -h /tmp -p 5432 2>/dev/null; then
+        if pg_isready -h "$PGBASE" -p 5432 2>/dev/null; then
             log "PostgreSQL is ready"
             break
         fi
         log "Waiting for PostgreSQL to start... ($i/30)"
         sleep 1
     done
 
-    # Create the database
+    # Create the database (use UID-scoped socket directory)
     log "Creating database 'fdr'..."
     if [ "$CURRENT_UID" -eq 0 ]; then
-        su - postgres -c "createdb -h /tmp -U postgres fdr" 2>&1 | add_timestamps || true
+        su - postgres -c "createdb -h $PGBASE -U postgres fdr" 2>&1 | add_timestamps || true
     else
-        createdb -h /tmp -U postgres fdr 2>&1 | add_timestamps || true
+        createdb -h "$PGBASE" -U postgres fdr 2>&1 | add_timestamps || true
     fi
 
-    # Update DATABASE_URL for Prisma to use the Unix socket
-    export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/fdr?host=/tmp"
-    log "DATABASE_URL configured for Unix socket in /tmp"
+    # Update DATABASE_URL for Prisma to use the UID-scoped Unix socket
+    export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/fdr?host=${PGBASE}"
+    log "DATABASE_URL configured for Unix socket in $PGBASE"
+
+    # Write PGBASE to a known file so health check scripts can find the socket directory
+    echo "$PGBASE" > /tmp/postgres-socket-dir
 
     return 0
 }
@@ -187,11 +201,11 @@ if [ "$USE_SEEDED_DATA" = "true" ] && [ -f "$SEED_POSTGRES_DUMP" ]; then
     log "Restoring PostgreSQL from seeded dump..."
     CURRENT_UID=$(id -u)
     if [ "$CURRENT_UID" -eq 0 ]; then
-        su - postgres -c "pg_restore -h /tmp -p 5432 -U postgres -d fdr --clean --if-exists '$SEED_POSTGRES_DUMP'" 2>&1 | add_timestamps || {
+        su - postgres -c "pg_restore -h $PGBASE -p 5432 -U postgres -d fdr --clean --if-exists '$SEED_POSTGRES_DUMP'" 2>&1 | add_timestamps || {
             log "Warning: pg_restore had some errors (this may be normal for clean restore)"
         }
     else
-        pg_restore -h /tmp -p 5432 -U postgres -d fdr --clean --if-exists "$SEED_POSTGRES_DUMP" 2>&1 | add_timestamps || {
+        pg_restore -h "$PGBASE" -p 5432 -U postgres -d fdr --clean --if-exists "$SEED_POSTGRES_DUMP" 2>&1 | add_timestamps || {
             log "Warning: pg_restore had some errors (this may be normal for clean restore)"
         }
     fi
@@ -281,6 +295,13 @@ fi
 
 # -----------  Start MINIO setup  -----------
 
+# Configure MinIO client (mc) to use a writable config directory
+# When running as an arbitrary UID (e.g., 65532) that doesn't exist in /etc/passwd,
+# $HOME may default to "/" which isn't writable, causing "mc alias set" to fail.
+# Setting MC_CONFIG_DIR ensures mc can write its config regardless of the UID.
+export MC_CONFIG_DIR="/tmp/mc-config"
+mkdir -p "$MC_CONFIG_DIR" 2>/dev/null || true
+
 # Clean up any existing MinIO system files to avoid overlay filesystem issues
 # MinIO's .minio.sys can cause "rename across devices" errors if it exists from a previous layer
 log "Cleaning up MinIO system files..."

servers/self-hosted/src/__test__/nonRootUser.test.ts

@@ -86,14 +86,18 @@ describe("Self-hosted container with security restrictions", () => {
                 );
                 console.log(relevantLogs.join("\n"));
 
-                // Check for successful PostgreSQL initialization in /tmp
-                expect(logs).toContain("Initializing PostgreSQL cluster in /tmp/postgresql/data");
+                // Check for successful PostgreSQL initialization in UID-scoped /tmp directory
+                // The path is now /tmp/postgresql-{UID}/data to avoid permission conflicts
+                expect(logs).toMatch(/Initializing PostgreSQL cluster in \/tmp\/postgresql-\d+\/data/);
                 expect(logs).toContain("PostgreSQL started successfully");
 
                 // Check if PostgreSQL is actually running
+                // Extract the PGBASE path from logs to use for pg_isready
+                const pgbaseMatch = logs.match(/DATABASE_URL configured for Unix socket in (\/tmp\/postgresql-\d+)/);
+                const pgbase = pgbaseMatch ? pgbaseMatch[1] : "/tmp/postgresql-65532";
                 const { stdout: psOutput } = await execa(
                     "docker",
-                    ["exec", containerId, "pg_isready", "-h", "/tmp", "-p", "5432"],
+                    ["exec", containerId, "pg_isready", "-h", pgbase, "-p", "5432"],
                     {
                         reject: false
                     }
@@ -191,8 +195,9 @@ describe("Self-hosted container with security restrictions", () => {
                 // Check for successful startup indicators
                 console.log("Checking for successful startup indicators...");
 
-                // PostgreSQL should initialize in /tmp
-                expect(logs).toContain("Initializing PostgreSQL cluster in /tmp/postgresql/data");
+                // PostgreSQL should initialize in UID-scoped /tmp directory
+                // The path is now /tmp/postgresql-{UID}/data to avoid permission conflicts
+                expect(logs).toMatch(/Initializing PostgreSQL cluster in \/tmp\/postgresql-\d+\/data/);
                 expect(logs).toContain("PostgreSQL started successfully");
 
                 // Check if key services started

servers/self-hosted/src/__test__/singleNode.test.ts

@@ -33,10 +33,16 @@ describe("Self-hosted docs has a running Postgres instance", () => {
         const containerId = await getSingleNodeContainerId();
         expect(containerId).toBeTruthy();
 
+        // Use TCP connection (-h localhost) instead of Unix socket for robustness
+        // The socket directory is UID-scoped and may vary between runs
         const { stdout: postgresStatus } = await execa("docker", [
             "exec",
             containerId,
             "pg_isready",
+            "-h",
+            "localhost",
+            "-p",
+            "5432",
             "-U",
             "postgres",
             "-d",
@@ -49,12 +55,17 @@ describe("Self-hosted docs has a running Postgres instance", () => {
         const containerId = await getSingleNodeContainerId();
         expect(containerId).toBeTruthy();
 
+        // Use TCP connection (-h localhost) instead of Unix socket for robustness
         const { stdout: dbList } = await execa("docker", [
             "exec",
             "-e",
             "PGPASSWORD=postgres",
             containerId,
             "psql",
+            "-h",
+            "localhost",
+            "-p",
+            "5432",
             "-U",
             "postgres",
             "-d",
@@ -71,6 +82,10 @@ describe("Self-hosted docs has a running Postgres instance", () => {
             "PGPASSWORD=postgres",
             containerId,
             "psql",
+            "-h",
+            "localhost",
+            "-p",
+            "5432",
             "-U",
             "postgres",
             "-d",
@@ -86,7 +101,16 @@ describe("Self-hosted docs has a running Postgres instance", () => {
     it("Minio Bucket has docs", async () => {
         const containerId = await getSingleNodeContainerId();
         expect(containerId).toBeTruthy();
-        const { stdout: minioStatus } = await execa("docker", ["exec", containerId, "mc", "ls", "minio"]);
+        // Pass MC_CONFIG_DIR to docker exec since run.sh configures mc with this custom config directory
+        const { stdout: minioStatus } = await execa("docker", [
+            "exec",
+            "-e",
+            "MC_CONFIG_DIR=/tmp/mc-config",
+            containerId,
+            "mc",
+            "ls",
+            "minio"
+        ]);
         const orgName = "example-org"; // this comes from the fern folder we mount
         expect(minioStatus).toContain(`${orgName}.docs.buildwithfern.com`);
     });