docs: add tutorial for running podman on macOS startup with launchd#28126
docs: add tutorial for running podman on macOS startup with launchd#28126veeceey wants to merge 2 commits intocontainers:mainfrom
Conversation
Add a new tutorial documenting how to use macOS launchd LaunchAgents to automatically start a Podman machine at login. This includes a working plist example, step-by-step instructions, and troubleshooting guidance (notably warning against using KeepAlive which causes restart loops). Closes containers#28044 Signed-off-by: Varun Chawla <varun_6april@hotmail.com>
veeceey
force-pushed
the
fix/issue-28044-macos-startup-docs
branch
from
8db85e4 to
e5e52ff
Compare
Honny1
left a comment
Honny1
left a comment
There was a problem hiding this comment.
Thanks! I have some comments, but overall it looks good. I haven't tested the tutorial yet, but I'll do that later.
docs/tutorials/macos_autostart.md
Outdated
|
|
||
| ## Prerequisites | ||
|
|
||
| - macOS with Podman installed (e.g., via `brew install podman`) |
There was a problem hiding this comment.
I would also suggest installing it via the installer on the release page. Alternatively, we could just point the reader to https://podman.io/docs/installation.
docs/tutorials/macos_autostart.md
Outdated
| ``` | ||
|
|
||
| If you installed Podman with Homebrew on an Apple Silicon Mac, the path is | ||
| typically `/opt/homebrew/bin/podman`. On Intel Macs, it is usually |
There was a problem hiding this comment.
I would not mention Intel Macs since we don't fully support them due to a lack of hardware. https://github.com/containers/podman/blob/main/SUPPORT.md
docs/tutorials/macos_autostart.md
Outdated
|
|
||
| Create the file `~/Library/LaunchAgents/com.podman.machine.default.plist` | ||
| with the following content. Replace `/opt/homebrew/bin/podman` with the | ||
| path from Step 1 if it differs on your system. Replace `podman-machine-default` |
There was a problem hiding this comment.
I would also point out that the user can run the podman machine start command without specifying a machine, which will automatically start the default machine.
- Link to podman.io installation page instead of just mentioning brew - Remove Intel Mac references (unsupported per SUPPORT.md) - Mention that podman machine start without a name starts the default machine - Note the release page installer path as an alternative
There was a problem hiding this comment.
I conducted a second round of review and tested the tutorial, but it appears not to be working correctly at the moment. I left some suggested fixes for those parts. Also, I think there should be a launchd service that stops the Podman machine when the user restart/shutdown computer. Sending a SIGKILL to the VM seems a little bit rude, in my opinion!
Also, please squash your commits and properly sign them to make the DCO check happy.
If you restart your Mac, you lose your review comments if they're not submitted. But they will be submitted with new ones. XD
| Key considerations for running `podman machine start` under launchd: | ||
|
|
||
| - **Do not use `KeepAlive` or automatic restart.** `podman machine start` is a | ||
| one-shot command that starts the VM and then exits. If launchd restarts it, | ||
| it will find the machine already running and return an error, which can cause | ||
| a restart loop. | ||
| - **Use `RunAtLoad` to start the machine once at login.** | ||
| - **Use the full path to the `podman` binary** to avoid PATH issues. |
There was a problem hiding this comment.
I think this could be explained later when the tutorial mentions it. Stating it right at the beginning feels a bit weird.
|
|
||
| ## Step 1: Find your Podman binary path | ||
|
|
||
| Determine the full path to your `podman` binary: |
There was a problem hiding this comment.
Could you please mention why this needs to be done?
| uses `podman-machine-default`; replace it with the name of your machine if | ||
| you are not using the default. | ||
|
|
||
| ```xml |
There was a problem hiding this comment.
When podman machine start runs, it spawns child processes (vfkit for the Apple Hypervisor VM, gvproxy for networking). These child processes are part of the same launchd process group. When the parent podman machine start exits (it's a one-shot command), launchd kills the entire process group by default, including vfkit and gvproxy. Which immediately destroys the VM.
The fix is to add:
<key>AbandonProcessGroup</key>
<true/>This tells launchd to leave child processes running after the main process exits, which is exactly the behavior needed here.
| Load the agent so it takes effect without logging out and back in: | ||
|
|
||
| ``` | ||
| $ launchctl load ~/Library/LaunchAgents/com.podman.machine.default.plist |
There was a problem hiding this comment.
The launchctl load and launchctl unload are deprecated since macOS 10.10.
|
|
||
| ### Important: do not use KeepAlive | ||
|
|
||
| A common mistake is to add `<key>KeepAlive</key><true/>` to the plist. |
There was a problem hiding this comment.
I think this could just be a note. Writing a separate section about it doesn't seem to add much value for the reader, but it is definitely worth mentioning in relation to AbandonProcessGroup.
| <key>StandardOutPath</key> | ||
| <string>/tmp/podman-machine-start.log</string> | ||
|
|
||
| <key>StandardErrorPath</key> | ||
| <string>/tmp/podman-machine-start.err.log</string> |
There was a problem hiding this comment.
This could go in the Troubleshooting section.
3 participants
Summary
docs/tutorials/macos_autostart.md) documenting how to automatically start a Podman machine at login on macOS usinglaunchdLaunchAgentsKeepAlivemust not be used (causes restart loops sincepodman machine startis a one-shot command), which is the most common pitfall users encounterCloses #28044
Test plan
🤖 Generated with Claude Code