>

README.md

@@ -154,6 +154,7 @@ Security choices here:
 - Bun installed
 - Docker available locally
 - A running Docker Mailserver container
+- The API process must be allowed to access Docker
 
 ### Setup
 
@@ -184,6 +185,36 @@ bun run dev:web
 
 6. Open `http://localhost:5173`.
 
+### Production-style local run
+
+If you want the built frontend to be served by the API itself:
+
+```bash
+bun run build
+bun run dev:api
+```
+
+Then open `http://localhost:3001`.
+
+The API serves files from `apps/web/dist` by default, configurable with `WEB_DIST_PATH`.
+
+### Docker permission note
+
+If you see:
+
+```text
+permission denied while trying to connect to the docker API at unix:///var/run/docker.sock
+```
+
+the app itself is fine, but the API process cannot talk to Docker.
+
+Common fixes:
+
+- Run the API with a user that belongs to the `docker` group
+- If the API runs in a container, mount `/var/run/docker.sock:/var/run/docker.sock`
+- Make sure the Docker daemon is actually running
+- Make sure `MAILSERVER_CONTAINER` matches the real Docker Mailserver container name
+
 ## Notes and assumptions
 
 - This panel assumes Docker Mailserver is using the file-based account provisioner and supports the standard `setup email` commands.