Initial commit: homelab configuration and documentation

docs/guides/portainer_local_unreachable_fix.md

@@ -0,0 +1,33 @@
+# Fixing Portainer Error: "The environment named local is unreachable"
+
+## Problem
+
+After migrating the Docker Swarm to an Ubuntu container, the Portainer UI shows the error "The environment named local is unreachable".
+
+## Cause
+
+This error means the Portainer server container cannot communicate with the Docker daemon it is supposed to manage. This communication happens through the Docker socket file, located at `/var/run/docker.sock`.
+
+In your nested environment (HAOS > Ubuntu Container > Portainer Container), the issue is almost certainly that the user inside the Portainer container does not have the necessary file permissions to access the `/var/run/docker.sock` file that belongs to the Ubuntu container's Docker instance.
+
+## Solution (To be performed in your deployment environment)
+
+You need to ensure the Portainer container runs with a user that has permission to access the Docker socket.
+
+**1. Find the Docker Group ID:**
+
+First, SSH into your Ubuntu container that is running the swarm. Then, run this command to find the group ID (`gid`) that owns the Docker socket:
+
+```bash
+stat -c '%g' /var/run/docker.sock
+```
+
+This will return a number. This is the `DOCKER_GROUP_ID`.
+
+**2. Edit the `portainer-stack.yml`:**
+
+You need to add a `user` directive to the `portainer` service definition in your `portainer-stack.yml` file. This tells the service to run as the `root` user and with the Docker group, granting it the necessary permissions.
+
+I will make this edit for you now, using a placeholder for the group ID. **You will need to replace `DOCKER_GROUP_ID_HERE` with the number you get from the command above before you deploy.**
+
+This is the most common and secure way to resolve this issue without granting full `privileged` access.