Document Podman Quadlet as an alternative to podman generate systemd

[alberto743]

Summary

• Adds a "Podman Quadlet" section to docs/podman.md, documenting Podman's declarative Quadlet unit files (Podman >= 4.4) as an alternative to the existing podman generate systemd workflow, since Quadlet does not require root access to install the unit file and integrates auto-updating via a dedicated directive.
• Reuses the same bind-mount and authorisation flow already established in the guide (via a throwaway podman run --rm -it container) so the Quadlet unit picks up an already-authorised refresh_token.

Closes #3817

Test plan

• Manually validate the Quadlet unit starts the container and syncs correctly under Podman >= 4.4
• Confirm systemctl --user enable --now podman-auto-update.timer updates the image on schedule

[abraunegg]

@alberto743

Thanks for adding Quadlet documentation. Moving away from podman generate systemd toward Quadlet is the right direction, and the overall intent of this PR is good.

However, I do not think this should be merged as-is. There are several operational issues in the proposed instructions, including commands and compatibility assumptions that would cause the documented workflow to fail or behave differently from the existing Podman deployment model.

1. systemctl --user enable --now onedrive.service is not valid for generated Quadlet services

The PR currently documents:

systemctl --user daemon-reload
systemctl --user enable --now onedrive.service

Podman explicitly documents that services generated from Quadlet files cannot be enabled using systemctl enable.

The [Install] section in the Quadlet file is processed by the Quadlet generator itself:

[Install]
WantedBy=default.target

The service should therefore be started with:

systemctl --user daemon-reload
systemctl --user start onedrive.service

This is an operational issue rather than a documentation preference, because the current command tells users to perform an unsupported action.

2. The documented Podman >= 4.4 minimum is not compatible with this Quadlet example

The proposed prerequisites state:

Podman >= 4.4

but the Quadlet uses:

AutoUpdate=registry

AutoUpdate= was not available as a Quadlet [Container] directive in Podman 4.4. It is available in the Podman 4.6 Quadlet interface.

The example also uses host paths beginning with the %h systemd specifier, and Quadlet handling around systemd specifiers received fixes after the initial 4.4 implementation.

Given the directives being documented here, the minimum supported version for this example should be:

Podman >= 4.6

If Podman 4.6 is the minimum, the Quadlet should also use the native Quadlet directive:

UserNS=keep-id

rather than:

PodmanArgs=--userns=keep-id

PodmanArgs= should generally only be used where Quadlet does not expose a native directive.

3. The proposed Quadlet workflow introduces a different configuration-storage model from the rest of docs/podman.md

This is the largest concern with the current implementation.

The existing Podman guide deliberately creates and uses the named configuration volume:

podman volume create onedrive_conf

and the established authorisation/runtime workflow maps it as:

-v onedrive_conf:/onedrive/conf:U,Z

The new Quadlet section instead changes the configuration storage to:

-v ~/.config/onedrive:/onedrive/conf:U,Z

and:

Volume=%h/.config/onedrive:/onedrive/conf:U,Z

This means the Quadlet section is not simply an alternative to podman generate systemd for the deployment already created by the guide. It creates a second and different storage model.

Immediately after the proposed Quadlet section, the existing documentation then returns to instructions that assume the configuration resides in:

onedrive_conf

including:

podman volume inspect onedrive_conf

A user following the new Quadlet path would therefore be taken into instructions that no longer match their deployment.

There is also potential for confusion or collision with a native host installation, because ~/.config/onedrive is the normal non-containerised client configuration/database location.

I strongly recommend that the Quadlet implementation reuse the existing onedrive_conf volume.

For example:

[Container]
Image=docker.io/driveone/onedrive:edge
ContainerName=onedrive
Volume=onedrive_conf:/onedrive/conf:U,Z
Volume=%h/OneDrive:/onedrive/data:U,Z
UserNS=keep-id
AutoUpdate=registry

This keeps the Quadlet deployment aligned with the configuration and authorisation model already established by this document.

4. Rootless systemctl --user services have different lifecycle semantics from the existing system-level service

The existing podman generate systemd section installs a system-level service.

The new Quadlet section moves to:

systemctl --user ...

That is appropriate for a rootless Quadlet, but it has an important operational difference.

Without lingering enabled, the user's systemd manager is tied to the user's login session. For an always-running OneDrive monitor, users may expect the service to start at boot and continue running after logout.

The documentation should therefore explain the use of:

loginctl enable-linger

for users who expect the rootless OneDrive service and associated Podman auto-update timer to remain active independently of an interactive login.

Otherwise, presenting the Quadlet path purely as an alternative to the existing generated system service hides an important behavioural difference.

5. The Quadlet systemd directory is not created

The PR instructs users to create:

~/.config/containers/systemd/onedrive.container

but the setup only creates:

mkdir -p ~/.config/onedrive ~/OneDrive

A fresh user may not have:

~/.config/containers/systemd

The instructions should explicitly include:

mkdir -p ~/.config/containers/systemd

before creating onedrive.container.

6. The authorisation prerequisite contradicts the authorisation step that follows

The prerequisites state that:

The container has already been authorised at least once

and that a refresh_token exists in:

~/.config/onedrive

The next section then says to:

perform authorisation using a throwaway container

These are two different workflows being presented at the same time.

Additionally, the existing Podman authorisation process does not place the refresh token in ~/.config/onedrive; it stores the application's configuration and runtime state in onedrive_conf.

If the Quadlet is intended to be an alternative to the existing podman generate systemd workflow, I do not think it needs a second authorisation procedure at all.

The cleaner flow would be:

1. Complete the existing Podman configuration and authorisation steps.
2. Stop and remove the manually-created onedrive container while retaining the volumes/data.
3. Create the Quadlet.
4. Start the Quadlet-managed service.

7. The Quadlet example hardcodes %h/OneDrive instead of preserving the configured data directory

Earlier in the existing Podman guide the user explicitly defines:

ONEDRIVE_DATA_DIR

because the OneDrive data directory may not necessarily be:

~/OneDrive

The proposed Quadlet instead hardcodes:

Volume=%h/OneDrive:/onedrive/data:U,Z

A user converting an existing deployment to Quadlet could therefore unintentionally point the container at a different local directory.

The documentation should make it explicit that the host path must match the same data directory previously configured as ONEDRIVE_DATA_DIR.

For example:

Replace `%h/OneDrive` below with the same host path previously configured as `ONEDRIVE_DATA_DIR` if a non-default location is being used.

Suggested direction

I think the safest implementation is to keep Quadlet exactly what this section says it is:

an alternative to podman generate systemd

rather than introducing a parallel Podman installation and authorisation workflow.

I suggest updating the PR so that the Quadlet instructions:

1. Require Podman >= 4.6.
2. Reuse the existing onedrive_conf configuration volume.
3. Reuse the existing OneDrive data directory.
4. Do not introduce a second ~/.config/onedrive authorisation workflow.
5. Use UserNS=keep-id instead of PodmanArgs=--userns=keep-id.
6. Retain [Install] with WantedBy=default.target.
7. Use systemctl --user start onedrive.service, not systemctl --user enable.
8. Explain loginctl enable-linger for always-on/rootless operation.
9. Explicitly create ~/.config/containers/systemd.
10. Explain that the existing manually-created onedrive container must be stopped/removed before starting the Quadlet-managed container with ContainerName=onedrive, while retaining the existing configuration volume and data.

A resulting Quadlet would be closer to:

[Unit]
Description=OneDrive Client for Linux (Podman Quadlet)
After=network-online.target

[Container]
Image=docker.io/driveone/onedrive:edge
ContainerName=onedrive
Volume=onedrive_conf:/onedrive/conf:U,Z
Volume=%h/OneDrive:/onedrive/data:U,Z
UserNS=keep-id
AutoUpdate=registry

[Service]
Restart=on-failure

[Install]
WantedBy=default.target

with the accompanying startup sequence:

mkdir -p ~/.config/containers/systemd

systemctl --user daemon-reload
systemctl --user start onedrive.service

and, where persistent operation outside the user's login session is required:

loginctl enable-linger

Validation

Because this is a documentation-only PR, I do not think the full OneDrive E2E suite is required.

However, I do think the documented procedure should be manually validated before merge because the PR test plan currently includes operational validation of the Quadlet and auto-update behaviour.

At minimum I would validate:

• an already-authorised onedrive_conf volume is successfully reused;
• the Quadlet starts and enters monitor mode;
• stop/start/restart works through systemctl --user;
• the service survives the intended logout/boot lifecycle when lingering is enabled;
• the configured data directory is the expected existing directory;
• podman auto-update --dry-run identifies the Quadlet-managed container with the expected registry update policy;
• the scheduled user podman-auto-update.timer operates as expected.

Please can you look at the changes requested and provide / perform all the testing / validation that this change is implementing and provide evidence in this PR of those changes operating as requried.

Without this, this PR is blocked.