From 2797c19832688878f792f9c43b17f5978ab8f9c5 Mon Sep 17 00:00:00 2001
From: esmaeelE <esmaeelEE@protonmail.com>
Date: Sat, 3 Oct 2026 11:21:02 +0330
Subject: [PATCH 1/2] feat(docker): make container socket path configurable for
 Podman

`docker-compose.yml` bind-mounted a hardcoded /var/run/docker.sock into the
`floci` and `floci-gcp` services. That path only exists when a Docker daemon is
running, so on a host with only rootless Podman, `podman-compose up` fails:

  Error: statfs /var/run/docker.sock: no such file or directory
  Error: "floci-ui_floci_1" is not a valid container, cannot be used as a
  dependency

Podman refuses to create a container whose mount source is missing, so `floci`
never gets created and `floci-api` then fails its depends_on check. Docker
instead silently creates an empty directory, which is why this went unnoticed.

Read the path from FLOCI_CONTAINER_SOCKET, defaulting to /var/run/docker.sock so
Docker users are unaffected, and document the Podman override in the README and
.env.example.
---
 .env.example       |  3 +++
 README.md          | 16 ++++++++++++++++
 docker-compose.yml | 12 ++++++++----
 3 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/.env.example b/.env.example
index 1f539f33..6ae70f20 100644
--- a/.env.example
+++ b/.env.example
@@ -6,6 +6,9 @@ FLOCI_AZURE_SUBSCRIPTION_ID=00000000-0000-0000-0000-000000000000
 FLOCI_AZURE_RESOURCE_GROUP=floci-local
 FLOCI_OCI_ENDPOINT=http://localhost:4599
 VITE_MOCK_MODE=false
+# Rootless Podman only: uncomment to point docker-compose.yml at Podman's
+# Docker-compatible socket instead of the absent /var/run/docker.sock.
+# FLOCI_CONTAINER_SOCKET=/run/user/1000/podman/podman.sock
 AWS_REGION=us-east-1
 AWS_ACCESS_KEY_ID=test
 AWS_SECRET_ACCESS_KEY=test
diff --git a/README.md b/README.md
index b6590c1c..f54428e3 100644
--- a/README.md
+++ b/README.md
@@ -462,6 +462,22 @@ Start AWS + Azure + GCP + OCI:
 docker compose --profile multicloud up
 ```
 
+#### Podman
+
+The stack runs under Podman with no Docker daemon, but `floci` mounts the host
+container socket so it can start throwaway Lambda/Postgres containers. With
+rootless Podman there is no `/var/run/docker.sock`, so `podman-compose up` fails
+with `Error: statfs /var/run/docker.sock: no such file or directory`. Point the
+socket at Podman's Docker-compatible API in a `.env` file:
+
+```bash
+echo "FLOCI_CONTAINER_SOCKET=$XDG_RUNTIME_DIR/podman/podman.sock" >> .env
+podman-compose up
+```
+
+Without it the emulator still starts, but invoking a Lambda function fails with
+"Failed to start Lambda container".
+
 Convenience targets:
 
 ```bash
diff --git a/docker-compose.yml b/docker-compose.yml
index fb148b81..7c4e3f85 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -48,10 +48,14 @@ services:
       - "4566:4566"
     volumes:
       # Floci runs Lambda functions in throwaway containers, so it needs the host
-      # Docker daemon. Without this, invoke fails with "Failed to start Lambda
-      # container". This grants the emulator control of host Docker — acceptable
+      # container daemon. Without this, invoke fails with "Failed to start Lambda
+      # container". This grants the emulator control of the host daemon — acceptable
       # for a local dev stack, and the same mount the README's docker run uses.
-      - /var/run/docker.sock:/var/run/docker.sock
+      #
+      # Default is the Docker socket. Podman users, who have no Docker daemon and so
+      # no /var/run/docker.sock, override it in .env:
+      #   FLOCI_CONTAINER_SOCKET=$XDG_RUNTIME_DIR/podman/podman.sock
+      - ${FLOCI_CONTAINER_SOCKET:-/var/run/docker.sock}:/var/run/docker.sock
       - ./data:/app/data
       - ./init/ready.d:/etc/floci/init/ready.d:ro
       - ./init/files:/etc/floci/init/files:ro
@@ -79,7 +83,7 @@ services:
       - "4588:4588"
     volumes:
       # Cloud SQL instances are real Postgres containers; see the note on `floci`.
-      - /var/run/docker.sock:/var/run/docker.sock
+      - ${FLOCI_CONTAINER_SOCKET:-/var/run/docker.sock}:/var/run/docker.sock
     networks:
       - floci_default
 

From b2543eee0ea08d660d8026d88ed3c048c885c6b5 Mon Sep 17 00:00:00 2001
From: esmaeelE <esmaeelEE@protonmail.com>
Date: Tue, 6 Oct 2026 15:30:28 +0330
Subject: [PATCH 2/2] docs(docker): fix Podman section contradicting itself

The closing sentence claimed the emulator still started without the socket
override, which contradicted the paragraph above it describing the
`podman-compose up` failure. Reword it to describe the actual container-create
error instead.
---
 README.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index f54428e3..33e59506 100644
--- a/README.md
+++ b/README.md
@@ -475,8 +475,10 @@ echo "FLOCI_CONTAINER_SOCKET=$XDG_RUNTIME_DIR/podman/podman.sock" >> .env
 podman-compose up
 ```
 
-Without it the emulator still starts, but invoking a Lambda function fails with
-"Failed to start Lambda container".
+Without the override, Podman never creates the `floci` container at all: the
+mount source is missing, so `up` aborts with the `statfs` error above and
+`floci-api` then fails its `depends_on` check. No service starts, so there is no
+emulator to invoke against.
 
 Convenience targets: