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