Dropbox Docker

A Docker container that runs the official Dropbox headless daemon on Linux. Built for homelabs that need reliable, hands-off Dropbox sync — especially large accounts with hundreds of thousands of files.

Docker Hub: https://hub.docker.com/r/islamdiaa/dropbox-docker GitHub: https://github.com/islamdiaa/dropbox-docker

Why I built this

Every Dropbox Docker image I found was either abandoned, crashing on large accounts, or missing basic things like health checks and graceful shutdown. I run a 1M+ file Dropbox account on my Unraid server and needed something that wouldn't fall over. The existing images (otherguy/docker-dropbox, janeczku/dropbox) are unmaintained and crash on large accounts due to a Rust panic in Dropbox's telemetry code. This container fixes that.

Features

• Telemetry crash fix — blocks the analytics endpoint that causes a known Rust panic during indexing of large accounts. No patches, just isolation.

• File ownership auto-fix — files created by root/SSH inside the Dropbox folder are automatically chowned every ~6 minutes so they actually sync.

• Stale file cleanup — removes leftover .dropbox directories from previous installations that cause PermissionDenied errors on startup.

• Process supervision — bounded restarts, signal forwarding, graceful shutdown on docker stop.

• Docker HEALTHCHECK — runs dropbox status every 60s with a 2-minute startup grace period.

• Auto-update — pulls the latest official Dropbox binary on every startup.

• Optional monitoring — Prometheus metrics (port 8000) and JSON status API (port 8001).

• Security hardened — input validation, PII redacted from API, capability dropping, no docker.sock required.

• CI/CD — automated builds, ShellCheck, hadolint, Trivy vulnerability scanning, unit + E2E tests.

Quick Start on Unraid

1. Install from Community Apps (search "Dropbox") or add the template manually

2. Config path: /mnt/user/appdata/dropbox

3. Sync folder: Use a direct disk path like /mnt/disk1/Dropbox — do not use /mnt/user/Dropbox

4. Important: Go to Settings → Shares → Dropbox → set Use cache: No

5. Set DROPBOX_UID=99 and DROPBOX_GID=100 (Unraid's nobody:users)

6. Start the container and check logs for the account linking URL

7. Open the URL in a browser to connect your Dropbox account

Why "Use cache: No" matters

If caching is enabled, files written via /mnt/user/Dropbox/ land on the cache drive first, but the container mounts the disk path directly and won't see those files until the mover runs. Setting cache to No ensures all writes go directly to the disk where the container can detect and sync them immediately.

For large accounts (500K+ files)

• Set --memory 4g or higher

• Set DROPBOX_STARTUP_TIMEOUT=600 (initial indexing takes time)

• Set POLLING_INTERVAL=30 (reduce CPU)

• Keep SKIP_SET_PERMISSIONS=true (the default)

• Bump inotify watchers on the host: echo "fs.inotify.max_user_watches=1048576" >> /etc/sysctl.conf && sysctl -p

Configuration

Variable	Default	Description
DROPBOX_UID	1000	User ID (use 99 for Unraid)
DROPBOX_GID	1000	Group ID (use 100 for Unraid)
TZ	UTC	Timezone
POLLING_INTERVAL	5	Status check frequency (seconds)
DROPBOX_STARTUP_TIMEOUT	300	Startup wait time (seconds)
DROPBOX_MAX_RESTARTS	5	Max crash restarts before giving up
ENABLE_MONITORING	false	Enable Prometheus + status API
SKIP_SET_PERMISSIONS	true	Skip slow recursive chown

Full docs: https://github.com/islamdiaa/dropbox-docker#configuration

Template Repository

https://github.com/islamdiaa/dropbox-docker/blob/main/unraid-template.xml

Stability

Currently running on my own Unraid 7.2.3 server — multi-day uptime, 0 restarts, syncing "Up to date" with a large Dropbox account.

Hey there, thank you for putting this out there.

I have a persistent issue, where my account won't sync, and then after a restart it won't be logged in. Funny enough, checking /root/appdata/dropbox/.dropbox, I can see that it creates new instances after a restart. I have instance1 and instance2 - this will continue after each restart.

Is there something I should try out here? I had the exact same issue with the older image from other-guy.

Thank you.

docker inspect dropbox.txt

I had this issue as well. tl;dr is the container needs the KILL capability. https://github.com/islamdiaa/dropbox-docker/issues/11

In case it matters, I'm running this via docker compose and not the Unraid template and after adding KILL the container and docker client seems to work (my client is still starting in the container, but I think that's normal).

This looks like a really useful option for Unraid, especially for large Dropbox accounts. The health check and graceful restart handling are nice additions compared with some of the older containers.

The direct disk path recommendation is also helpful since the /mnt/user vs. /mnt/disk behavior can easily cause confusing sports games online sync issues. I’ll probably give this a try on my server, and the Prometheus metrics are a nice bonus for monitoring.

Edited August 30Aug 30 by williamcorlin

Seems like this author is not active and will also abandon this in the future 🤷‍♂️

Sorry for the silence, everyone, and thanks for the reports. I went through all of them, reproduced the problems, and version 1.2.0 fixes them. To get it, go to the Docker tab and click apply update on the Dropbox container.

What was wrong

1. Linked ("Welcome …") but nothing syncs. If the sync folder (e.g. /mnt/disk1/Dropbox) didn't exist before the first start, Docker creates it owned by root. Dropbox runs as nobody (99) and couldn't write a single file into it. The container now makes the folder writable at startup. If it still can't write, the log shows an ERROR saying so.

2. Dropbox was force-killed on every stop, restart or update. With the template's polling interval of 30 seconds, the container only reacted to a stop request after its current 30-second wait. Docker gives up after 10 seconds and kills Dropbox hard. Killing Dropbox mid-write can damage its settings. I believe that's why some of you were logged out after a restart and got a new instance1/instance2 folder. Dropbox now shuts down cleanly within a second.

3. Several Dropbox processes, each with a new link URL. With cap_drop: ALL (compose setups), the container's watchdog needed the KILL capability to see that Dropbox was running. Without it, it assumed Dropbox had crashed and kept starting new copies. Thanks @Anticast for the pointer to GitHub issue #11. The KILL capability is no longer needed. If you added it as a workaround, you can keep it or remove it.

4. Crash loop on the very first start with a fresh config volume. Fixed.

After updating, check the container log. It now tells you:

• if your sync folder or config is on /mnt/user/.... Dropbox doesn't support Unraid's FUSE share layer, so use /mnt/diskX/... or /mnt/cache/... instead

• if the sync folder isn't writable

• after linking, which folder your account actually syncs to. Dropbox Business/team accounts can use a different folder name; see the README section "Dropbox Business and team folders".

Still asked to link again after a restart? Set the "Dropbox config" path to a direct path such as /mnt/cache/appdata/dropbox instead of /mnt/user/appdata/dropbox. Then remove the old device at dropbox.com → Settings → Security and link once more.

There's also a new "Ownership repair" setting (advanced view). Leave it on full unless other users own files in your Dropbox share and you don't want the container to change that.

@HHUBS , fair point, I had fallen behind. Every change now goes through the full test suite before an image is published. If the monthly rebuild fails, an issue gets opened automatically, so this shouldn't go unnoticed again.

If anything still doesn't work after updating, please post the container log from the start. Remove the cli_link_nonce link first: anyone who has it can link your account.