feat: Add Podman rootless support alongside Docker #1608
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
url and port to support rootless feat: support podman socket docs: add container runtime details
Contributor
Summary by CodeRabbit
WalkthroughReconfigures frontend to listen on 8080 and Traefik to expose HTTP on 8081, updates environment samples to reference the new frontend origin, replaces fixed Docker socket mounts with an environment-driven Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Compose as docker-compose / podman-compose
participant SocketDetector as DOCKER_SOCKET logic
participant Traefik as Traefik reverse-proxy
participant Frontend as Frontend (NGINX)
Note over Compose,SocketDetector #D6EAF8: Startup / env evaluation
Compose->>SocketDetector: Read DOCKER_SOCKET or default /var/run/docker.sock
alt Podman socket present
SocketDetector-->>Compose: Use Podman socket path
else Default Docker socket
SocketDetector-->>Compose: Use /var/run/docker.sock
end
Note over Traefik,Frontend #F9E79F: Service binding & port mapping
Compose->>Traefik: Mount socket, set port mapping (8081 -> 80) and service label (frontend -> 8080)
Compose->>Frontend: Start container exposing 8080
Traefik->>Frontend: Route requests to port 8080
Frontend->>Frontend: NGINX listens on 8080
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Pre-merge checks and finishing touches✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to Reviews > Disable Cache setting
Knowledge base: Disabled due to Reviews -> Disable Knowledge Base setting
📒 Files selected for processing (9)
.gitignore(1 hunks)backend/sample.env(2 hunks)docker/CONTAINER_RUNTIME.md(1 hunks)docker/README.md(1 hunks)docker/docker-compose-dev-essentials.yaml(2 hunks)docker/docker-compose.yaml(5 hunks)docker/dockerfiles/frontend.Dockerfile(1 hunks)frontend/nginx.conf(1 hunks)frontend/sample.env(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: build
🔇 Additional comments (11)
.gitignore (1)
716-718: LGTM!The addition of
.serenato the ignore list for MCP servers is appropriate housekeeping.backend/sample.env (2)
14-14: Verify the Django backend URL hostname.Similar to the frontend configuration,
DJANGO_APP_BACKEND_URLpoints tofrontend.unstract.localhost:8081. This hostname seems inconsistent with a backend URL. Please verify the Traefik routing configuration.
43-43: LGTM!The
WEB_APP_ORIGIN_URLcorrectly points to the frontend service via port 8081.docker/dockerfiles/frontend.Dockerfile (1)
57-57: LGTM!Exposing port 8080 instead of 80 correctly supports rootless Podman by avoiding privileged ports (<1024). This aligns with the nginx configuration change.
frontend/nginx.conf (1)
41-41: LGTM!Changing nginx to listen on port 8080 correctly supports rootless Podman and aligns with the Dockerfile exposure.
docker/README.md (1)
3-9: LGTM!The addition of container runtime support documentation with quick start guidance for both Docker and Podman is helpful. The explicit mention of enabling
podman.socketfor Podman users is important for success.docker/docker-compose-dev-essentials.yaml (2)
80-81: LGTM!The port mapping change to 8081:80 correctly supports rootless Podman by avoiding privileged ports, and the comment clearly explains the rationale.
147-148: LGTM!The reformatted RabbitMQ port comments improve readability without changing functionality.
frontend/sample.env (1)
1-1: No changes needed—backend URL configuration is correct.The environment variable is properly configured. Traefik routes requests to
frontend.unstract.localhostwith path-based differentiation:/api/v1and/deploymentrequests go to the backend service, while other requests go to the frontend service. The port mapping8081:80(host to container) is intentional for rootless Podman compatibility. The hostname is not inconsistent with the variable name—it reflects Traefik's unified routing design.docker/docker-compose.yaml (2)
234-237: Verify the socket fallback chain fully implements the stated priority.The socket mount uses
${DOCKER_SOCKET:-${XDG_RUNTIME_DIR:-/run/user/1000}/podman/podman.sock}, which covers priorities 1–3, but the PR objectives specify a 4th priority level for Docker's default socket. Currently, if all environment variables are unset, it falls back to the Podman socket path. Per the stated priority ($DOCKER_SOCKET → $XDG_RUNTIME_DIR/podman/podman.sock → /run/user/1000/podman/podman.sock → Docker default), the final fallback should be/var/run/docker.sock.Consider whether this is intentional (Podman-first policy) or requires an additional fallback layer.
154-156: Frontend port mapping and Traefik configuration updates align with breaking change.The port mapping change from
3000:80to3000:8080and the corresponding Traefik server port override (line 176) correctly implement the Traefik HTTP port migration from 80 to 8081 for rootless Podman compatibility.
Contributor
Author
|
@chandrasekharan-zipstack Since there are breaking changes involved, we will need to add a release note to Anywhere else to update? |
Simplified container runtime socket configuration based on code review
feedback. Docker is now the default with Podman as an explicit opt-in.
Changes:
- Simplified socket mount from complex nested fallback to simple default
- Before: ${DOCKER_SOCKET:-${XDG_RUNTIME_DIR:-/run/user/1000}/podman/podman.sock}
- After: ${DOCKER_SOCKET:-/var/run/docker.sock}
- Docker works out of the box with no environment variables needed
- Podman users set: export DOCKER_SOCKET=${XDG_RUNTIME_DIR}/podman/podman.sock
- Updated CONTAINER_RUNTIME.md to reflect simplified approach
- Fixed worker-file-processing-v2 command structure to match other workers
(entrypoint + command pattern instead of array with binary)
Benefits:
- Cleaner default configuration for majority Docker users
- Explicit opt-in for Podman users
- Addresses CodeRabbit review concerns about socket fallback logic
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <[email protected]>
Contributor
That's the only place to update. Once its up we could update the public documentation and link this README.md or maintain it there alone |
hari-kuriakose
requested review from
chandrasekharan-zipstack,
jaseemjaskp and
ritwik-g
ritwik-g
reviewed
Nov 3, 2025
ritwik-g
reviewed
Nov 3, 2025
| labels: | ||
| - traefik.enable=true | ||
| - traefik.http.routers.frontend.rule=Host(`frontend.unstract.localhost`) && !PathPrefix(`/api/v1`, `/deployment`) | ||
| - traefik.http.services.frontend.loadbalancer.server.port=8080 |
Contributor
There was a problem hiding this comment.
@hari-kuriakose is this config necessary? looking at our existing backend configuration I can't see such a configuration
ritwik-g
reviewed
Nov 3, 2025
| # The HTTP port | ||
| - "80:80" | ||
| # The HTTP port (changed to 8081 for rootless Podman compatibility) | ||
| - "8081:80" |
Contributor
There was a problem hiding this comment.
@hari-kuriakose why do we need to make this change exactly?
|
Contributor
Test ResultsSummary
Runner Tests - Full Report
SDK1 Tests - Full Report
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What
Added comprehensive support for Podman (both rootless and rootful) alongside existing Docker support, enabling the Unstract platform to run with either container runtime without configuration changes for Docker users.
Key changes:
80to8081for rootless Podman compatibility8080internally (nginx listens on 8080)worker-file-processing-v2command structure to match other workersdocker/CONTAINER_RUNTIME.mdWhy
How
Socket Configuration:
/var/run/docker.sock(Docker)export DOCKER_SOCKET=${XDG_RUNTIME_DIR}/podman/podman.sock${DOCKER_SOCKET:-/var/run/docker.sock}Port Configuration:
80→8081(rootless compatibility)80818080internallyDocumentation:
docker/CONTAINER_RUNTIME.mdwith runtime support guidedocker/README.mdwith quick start for both runtimesEnvironment Files:
backend/sample.env:DJANGO_APP_BACKEND_URLandWEB_APP_ORIGIN_URLto port 8081frontend/sample.env:REACT_APP_BACKEND_URLto port 8081Code Quality:
worker-file-processing-v2to useentrypoint+commandpattern (consistency with other workers).serenato.gitignoreCan this PR break any existing features. If yes, please list possible items. If no, please explain why.
YES - Breaking Change:
Impact:
http://frontend.unstract.localhost(port 80) will need to update tohttp://frontend.unstract.localhost:8081.envfiles need updatingMitigation:
Why This Won't Break Other Features:
/var/run/docker.sock)Database Migrations
N/A - No database schema changes
Env Config
Required Updates:
backend/.env:
frontend/.env:
Optional (Podman users only):
Relevant Docs
docker/CONTAINER_RUNTIME.md- New comprehensive runtime support guidedocker/README.md- Updated with quick start instructionsbackend/sample.env- Updated backend URLsfrontend/sample.env- Updated frontend backend URLRelated Issues or PRs
N/A
Dependencies Versions
Notes on Testing
Docker Testing (Default):
Podman Testing (Opt-In):
Verification Checklist:
DOCKER_SOCKETenvironment variableworker-file-processing-v2uses correct command structureScreenshots
N/A - Infrastructure change, no UI modifications
Checklist
I have read and understood the Contribution Guidelines.
🤖 Generated with Claude Code
Co-Authored-By: Claude [email protected]