Public Repository

Last pushed: 9 days ago
Short Description
Self-hosted file storage server -
Full Description

droppy is a self-hosted file storage server with a web interface and capabilites to edit files and view media directly in the browser. It is particularly well-suited to be run on low-end hardware like the Raspberry Pi.

Features (try the demo)

  • Fully responsive HTML5 interface
  • Realtime updates of file system changes
  • Directory upload support
  • Drag & drop support for file operations
  • Side-by-Side mode
  • Shareable public download links
  • Zip download of directories
  • Powerful text editor with themes and broad language support
  • Image and video gallery with full touch support
  • Audio player with seek support
  • Fullscreen support for editor and gallery
  • Supports installing to the homescreen

General Information

Two directories will be used. droppy is a well-behaved app and will not write anywhere else:

  • config: defaults to ~/.droppy/config, override with -c /some/dir
  • files: default ~/.droppy/files override with -f /some/dir

droppy maintains a in-memory representation of the files directory. If you're on slow storage and/or serving 100k+ files, the indexing on startup will take some time.


Local Installation :package:

With Node.js >= 4.0.0 installed, run:

$ sudo npm install -g droppy
$ droppy start -c /srv/droppy/config -f /srv/droppy/files

To update, run

$ sudo npm update -g droppy

Docker installation :whale:

To pull the image and start the container:

$ docker run --name droppy -p silverwind/droppy

This method uses automatic volumes for /config and /files which can be overridden through -v /srv/droppy/config:/config and -v /srv/droppy/files:/files. If you're using existing files, it's advisable to use -e UID=1000 -e GID=1000 to get new files written with correct ownership.

To update a docker installation, run

$ docker pull silverwind/droppy
$ docker stop droppy && docker rm droppy
$ docker run --name droppy -p silverwind/droppy


Alternatively, you can use the example docker-compose.yml:

$ curl -O
$ docker-compose up

This example docker-compose.yml uses the subdirectories config and files of the current working directory for storing data.


By default, the server listens on all IPv4 and IPv6 interfaces on port 8989. On first startup, a prompt to create login data for the first account will appear. Once it's created, login credentials are enforced. Additional accounts can be created in the options interface or the command line. Configuration is done in config/config.json, which is created with these defaults:

  "listeners" : [
      "host": ["", "::"],
      "port": 8989,
      "protocol": "http"
  "public": false,
  "timestamps": true,
  "linkLength": 5,
  "logLevel": 2,
  "maxFileSize": 0,
  "updateInterval": 1000,
  "pollingInterval": 0,
  "keepAlive": 20000,
  "allowFrame": false,
  "readOnly": false


  • listeners Array - Defines on which network interfaces, port and protocols the server will listen. See listener options below. listeners has no effect when droppy is used as a module.
  • public Boolean - When enabled, no user authentication is performed.
  • timestamps Boolean - When enabled, adds timestamps to log output.
  • linkLength Number - The amount of characters in a shared link.
  • logLevel Number - Logging amount. 0 is no logging, 1 is errors, 2 is info (HTTP requests), 3 is debug (Websocket communication).
  • maxFileSize Number - The maximum file size in bytes a user can upload in a single file.
  • updateInterval Number - Interval in milliseconds in which a single client can receive update messages through changes in the file system.
  • pollingInterval Number - Interval in milliseconds in which the file system is polled for changes, which is likely necessary for files on external or network-mapped drives. This is CPU-intensive! Corresponds to chokidar's usePolling option. 0 disables polling.
  • keepAlive Number - Interval in milliseconds in which the server sends keepalive message over the websocket, which may be necessary with proxies. 0 disables keepalive messages.
  • allowFrame Boolean - Allow the page to be loaded into a <frame> or <iframe>.
  • readOnly Boolean - All served files will be treated as being read-only.
  • dev Boolean - Enable developer mode, skipping resource minification and enabling live reload.

Listener Options

listeners defines on which network interfaces, ports and protocol(s) the server will listen. For example:

"listeners": [
    "host"     : [ "", "::" ],
    "port"     : 80,
    "protocol" : "http"
        "host"     : "",
        "port"     : 443,
        "protocol" : "https",
        "key"      : "~/certs/tls.key",
        "cert"     : "~/certs/tls.crt",
        "ca"       : "~/certs/",
        "dhparam"  : "~/certs/tls.dhparam",
        "hsts"     : 31536000

The above configuration will result in:

  • HTTP listening on all IPv4 and IPv6 interfaces, port 80.
  • HTTPS listening on all IPv4 interfaces, port 443, with 1 year of HSTS duration, using the provided TLS files.

A listener object accepts these options:

  • host String/Array - Network interface(s) to listen on. Required.
  • port Number/Array - Network port(s) to listen on. Required.
  • protocol String - Protocol to use, http or https. Required.

For TLS these additional options are available:

  • cert String - Path to PEM-encoded TLS certificate file, which can include additional intermediate certificates concatenated after the main certificate. This path can be relative to the config directory. Required.
  • key String - Path to PEM-encoded TLS private key file. This path can be relative to the config directory. Required.
  • dhparam String - Path to PEM-encoded TLS Diffie-Hellman parameters file. If not provided, new 2048 bit parameters will generated and saved for future use. This path can be relative to the config directory.
  • passphrase String - Passphrase for the TLS private key in case it is encrypted.
  • hsts Number - Length of the HSTS header in seconds. Set to 0 to disable HSTS.


droppy can be used with frameworks like express:

var app    = require("express")();
var droppy = require("droppy")({
  configdir: "~/droppy/config"
  filesdir: "~/droppy/files",
  log: "~/droppy/log",
  logLevel: 0

app.use("/", droppy);
app.listen(process.env.PORT || 8989);

See the express example for a working example.


  • options {object}: Options. Extends config.json. In addition to above listed options, configdir, filesdir and log are present on the API.

Returns function onRequest(req, res). All arguments are optional.

Additional Installation guides

Downloading from the command line

To download shared links with curl and wget to the correct filename:

$ curl -OJ url
$ wget --content-disposition url


To start a live-reloading dev server:

$ git clone && cd droppy
$ npm i
$ node droppy --dev

The Makefile has a few tasks for updating dependencies, pushing docker images, see the comment above for dependencies of those tasks.

© silverwind, distributed under BSD licence.

Docker Pull Command