Update index.md

[hangonlyra]

Update Lambda troubleshooting to add workaround for Podman on MacOS

[github-actions]

⚡️ Deploying PR Preview...

[HarshCasper]

Hi – Thanks for adding the patch! However, we have a dedicated Podman page here: https://docs.localstack.cloud/references/podman/

Is the information available on the page not enough to fix the issue? Let us know. In any case, we might need to move this information into the Podman docs to make sure that we have such workarounds documented.

[hangonlyra]

Hi – Thanks for adding the patch! However, we have a dedicated Podman page here: https://docs.localstack.cloud/references/podman/

Is the information available on the page not enough to fix the issue? Let us know. In any case, we might need to move this information into the Podman docs to make sure that we have such workarounds documented.

Hi!

The information on the Podman page does not work on MacOS. My hypothesis is that Podman on MacOS involves running a Linux VM which actually runs the Podman runtime. The Docker/Podman Unix socket lives in that VM and is mapped into the MacOS host. However, when we map the Unix socket using/var/run/docker:/var/run/docker from the MacOS host into the Localstack container, something doesn't translate correctly and the socket doesn't work from inside the Localhost container.

This can be demonstrated by mapping a directory on the MacOS host into the Localstack container. Then on the MacOS side run a Python script like:

import socket
import os

socket_path = 'test.socket'

# Remove the socket file if it exists
if os.path.exists(socket_path):
    os.remove(socket_path)

# Create and bind the Unix socket
server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
server.bind(socket_path)
server.listen(1)

print(f"Listening on {socket_path}...")

while True:
    connection, _ = server.accept()
    print("Connection received")
    while True:
        data = connection.recv(1024)
        if not data:
            break
        print(f"Received: {data.decode('utf-8')}")
    connection.close()

Then from the Localstack container run this Python script:

import socket

socket_path = 'test.socket'

# Create a Unix socket and connect to the server
client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
client.connect(socket_path)

# Send a message
message = "Hello from Python!"
client.sendall(message.encode('utf-8'))

# Close the socket
client.close()

You will get:

Traceback (most recent call last):
  File "/run/podman/test.py", line 7, in <module>
    client.connect(socket_path)
ConnectionRefusedError: [Errno 111] Connection refused

However, if you were to run the listener script from the Localhost container, the call will succeed and it will print out

Connection received
Received: Hello from Python!

I don't know the specific mechanism that's failing and I'm not certain this is specific to Podman (I seem to recall something similar happening with Docker Desktop on MacOS).

I think in general having an Unix socket in a Linux VM getting shared with the MacOS host and then shared again back into a container is going to be problematic.

To get around all of this, we can have Localstack get access to the Docker/Podman socket via TCP instead of Unix socket. Using socat is probably the most straight forward way or create a new remote connection in Podman that is pure TCP in addition to the SSH connection Podman creates by default.

Let me know if I should move the doc changes into the Podman section instead. I think that's a pretty good suggestion.