Update docker.md

[AleixMT]

No description provided.

[abraunegg]

Firstly, thank you very much for taking the time to open this pull request.

That said, I’d like to clarify why the change proposed in this PR isn’t technically correct within the context of how the Docker image is designed to operate.

Understanding how the Docker image works

When you run the OneDrive Client under Docker, the container always executes via the entrypoint.sh script, which explicitly sets:

--confdir /onedrive/conf --syncdir /onedrive/data

This design ensures that:

• The configuration files persist in the /onedrive/conf volume.
• The synchronised data persists in the /onedrive/data volume.
• The container environment is consistent and portable across host systems and architectures.

Because these two arguments are always supplied by the entrypoint, any sync_dir or confdir values defined inside the configuration file are overridden at runtime by design. This avoids confusion and ensures predictable behaviour between upgrades or different Docker hosts. These very specific paths are the bind-mount points between the Docker container and your local filesystem they should never be changed.

The correct ways to customise runtime behaviour

There are two supported methods for customising how the client runs inside Docker:

1. Using the supported Docker environment variables
   The full list is available here:
   👉 https://github.com/abraunegg/onedrive/blob/master/docs/docker.md#supported-docker-environment-variables

   For example:

   -e ONEDRIVE_DOWNLOADONLY=1
   -e ONEDRIVE_SYNC_ONCE=1
   -e ONEDRIVE_VERBOSE=1

   These map directly to supported client options in a controlled and reproducible way.

2. Using a configuration file inside /onedrive/conf
   You can create or edit your own config file following:
   👉 https://github.com/abraunegg/onedrive/blob/master/docs/docker.md#editing-the-running-configuration-and-using-a-config-file

   This method is ideal for setting advanced or permanent options that are not covered by environment variables.

Why manually adding --syncdir or --confdir at runtime is problematic

Manually adding --syncdir or --confdir arguments when you override the container command (docker run … driveone/onedrive:edge --monitor …) bypasses the logic in entrypoint.sh. This removes the automatic UID/GID mapping, user privilege management, and environment variable translation that make the container safe and consistent.

In short:

• The entrypoint handles security, permissions, and consistent operation.
• Overriding it reintroduces user errors and misaligned paths between host and container.
• The container is already correctly configured to map host volumes to /onedrive/data and /onedrive/conf.

So while your PR aims to help clarify usage, the proposed documentation change would inadvertently encourage unsupported usage patterns that can lead to data syncing to the wrong location or incorrect file ownership inside the container.

Suggested alternative to alleviate your issue

Rather than modifying the documentation to recommend adding --syncdir or --confdir at runtime, we can enhance the Docker documentation to make this design clearer — for example, by adding a short “Common Misconceptions” section explaining that:

“Users should not pass --syncdir or --confdir manually when running the container — these paths are already handled internally by the entrypoint script. Instead, use environment variables or a custom config file inside /onedrive/conf to adjust runtime behaviour.”

I’d be happy to accept an updated PR that improves the explanation along those lines.

In summary

The proposed changes would encourage a workflow that bypasses the supported and validated container mechanisms. The correct approach is to either use the Docker environment variables or edit the config within /onedrive/conf.

[AleixMT]

Thank you so much for your explanations @abraunegg I can see now that what I wrote is not exactly correct.

I’d be happy to accept an updated PR that improves the explanation along those lines.

I'll work on it during this weeks. Give me a few days (~7 days) and I'll get back to you with the changes.

[AleixMT]

Meanwhile, you can assign the PR to me.

[AleixMT]

Implemented your suggestions with nice formatting and structured text.

[AleixMT]

If it is possible, assign the PR to me since I'm using GH projects on my side and I'd like to see this issue as assigned to me (it is because I work in a team and we enforce this rule).

[abraunegg]

If it is possible, assign the PR to me since I'm using GH projects on my side and I'd like to see this issue as assigned to me (it is because I work in a team and we enforce this rule).

This is now done

[abraunegg]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.