Command line WebDAV server with browser support. Serves from file system or S3 compatible object store.
npm install nephele-serveRun Nephele WebDAV server to serve files from either a file system or an S3 compatible object store.
This server is also available as the Nephele Docker image.
WebDAV (Web Distributed Authoring and Versioning) is a protocol that allows users to access and manage files stored on a remote server. It is commonly used for web-based file sharing and collaboration, as it allows users to upload, download, and manage files directly from a web browser or file manager.
WebDAV is a popular protocol for file sharing and collaboration, as it is easy to use and allows users to access their files from any device with an internet connection. It is also secure, with support for encrypted data transfer and authentication to prevent unauthorized access to files.
Quickly install Nephele Serve using npm:
``sh`
sudo npm install -g nephele-serve
Note: By default, Nephele Serve uses a .htpasswd file for user authentication. Create this file in the directory you're serving. Use Apache's htpasswd utility or an online generator like http://aspirine.org/htpasswd_en.html for ease.
To authenticate with system users instead of an htpasswd file, follow these steps to install PAM development libraries and build tools for your OS:
1. Install PAM development libraries:
- For CentOS/RHEL: sudo yum install pam-devel gcc gcc-c++ make
- For Fedora:
- For Debian/Ubuntu:
- Arch and macOS come pre-installed with the necessary tools.
2. Now install Nephele Serve:
`sh`
sudo npm install -g nephele-serve
Note: Files and directories will be created with the proper ownership for the logged in user when using the PAM authenticator.
Serve the current directory.
`sh`
sudo nephele-serve .
Serve the current directory with a specific username and password (not .htpasswd file).
`sh`
sudo nephele-serve --auth-username admin --auth-password "S3cur3P4ssw0rd" .
Serve users' home directories (requires PAM libraries).
`sh`
sudo nephele-serve --home-directories
Serve user directories under the server root. This creates directories with the users' usernames, and serves their own directory to them.
`sh`
sudo nephele-serve --user-directories .
If you want to run it without installing it, you can do that too.
`sh`
sudo npx nephele-serve .
If you want to run it without root, you can do that too, but you must set the port to something higher than 1000, and you'll likely only be able to log in (with PAM) as the user who runs the script.
`sh`
nephele-serve -p 8080 .
Serve an S3 compatible object store bucket.
`sh`
sudo nephele-serve --s3-endpoint "https://mys3endpoint/" --s3-region us-east-1 --s3-access-key "mys3accesskey" --s3-secret-key "mys3secretkeyshhdonttell" --s3-bucket "MyBucket"
Serve a specific path (prefix) within an S3 compatible object store bucket.
`sh`
sudo nephele-serve --s3-endpoint "https://mys3endpoint/" --s3-region us-east-1 --s3-access-key "mys3accesskey" --s3-secret-key "mys3secretkeyshhdonttell" --s3-bucket "MyBucket" path/to/my/storage/
Serve an S3 compatible object store bucket, using file encryption to keep your data private. (Use https://www.uuidgenerator.net/ to generate your own 3 salt values and global encryption password.)
`sh`
sudo nephele-serve --s3-endpoint "https://mys3endpoint/" --s3-region us-east-1 --s3-access-key "mys3accesskey" --s3-secret-key "mys3secretkeyshhdonttell" --s3-bucket "MyBucket" --encryption --encryption-salt mylongsaltvalue --encryption-filename-salt myotherlongsaltvalue --encryption-filename-iv-salt mylastlongsaltvalue --encryption-global-password supersecretglobalpassword
Serve a deduplicating file store with Nymph, backed by a MySQL database. (Use https://www.uuidgenerator.net/ to generate your own JWT secret.)
`sh`
sudo nephele-serve --serve-listings --nymph --nymph-jwt-secret mylongsecretvalue --nymph-db-driver mysql --nymph-mysql-username mymysqluser --nymph-mysql-password mymysqlpassword --nymph-mysql-database mymysqldatabase ./myfileblobstore/
Note: Only regular users (UIDs 500-59999) are allowed to log in with PAM authentication.
Nephele Serve supports clustering for handling high loads. Here's how to set up a cluster of 8 Nephele Serve instances.
`sh`
sudo npm install -g pm2
sudo pm2 start -i 8 -u root --uid 0 \
nephele-serve \
-- \
--home-directories
Then you can save it and have it load at system startup.
`sh`
sudo pm2 save
sudo pm2 startup systemd
For a complete setup example with TLS, directory listings, and cluster mode, see the extended setup instructions at the end of this document.
Nephele Serve will check for updates on launch, but if your server is set to load on system start with PM2, you probably won't ever see the notification that there's an update. Therefore, every once in a while you should install the latest version (of PM2 and Nephele Serve).
`sh`Update nephele-serve and pm2
sudo npm i -g nephele-serve pm2Restart the server
sudo pm2 restart all
`sh`
nephele-serve --help
Here's a copy of the help output:
`
Usage: nephele-serve [options] [directory]
Command line WebDAV server with browser support. Serves from file system or S3 compatible object store.
Arguments:
directory The path of the directory to use as the server root. When using S3, this is the path within the bucket.
Options:
-v, --version Print the current version
-h, --host
-r, --realm
--cert
--key
-p, --port
--redirect-port
-t, --timeout
--keep-alive-timeout
--home-directories Serve users' home directories to them when they log in. (Impies --pam-auth.) (default: false)
--user-directories Serve users their own directory under the server root when they log in. (default: false)
--serve-indexes Serve index.html and index.htm files when the user requests a directory. (default: false)
--serve-listings Serve directory listings with file management forms when the user requests a directory. (default: false)
--no-follow-links Don't follow symlinks.
--file-properties
--file-locks
--no-auth Don't require authentication. (Not compatible with --home-directories or --user-directories.)
--pam-auth Use PAM authentication. (Requires PAM libraries.) (default: false)
--auth-user-filename
--auth-user-file
--auth-username
--auth-password
--encryption Enable filename and file contents encryption. (default: false)
--encryption-salt
--encryption-filename-salt
--encryption-filename-iv-salt
--encryption-filename-encoding
--encryption-global-password
--encryption-exclude
--s3-endpoint
--s3-region
--s3-access-key
--s3-secret-key
--s3-bucket
--nymph Use Nymph adapter for a deduplicated file system. (Not compatible with home/user directories, .htpasswd auth, S3, or encryption.) (default: false)
--nymph-jwt-secret
--nymph-rest-path
--nymph-setup-path
--no-nymph-registration Don't allow new user registration through the Nymph user setup app.
--nymph-export
--nymph-import
--nymph-db-driver
--nymph-mysql-host
--nymph-mysql-port
--nymph-mysql-database
--nymph-mysql-username
--nymph-mysql-password
--nymph-mysql-prefix
--nymph-postgres-host
--nymph-postgres-port
--nymph-postgres-database
--nymph-postgres-username
--nymph-postgres-password
--nymph-postgres-prefix
--nymph-sqlite-cache-size
--nymph-sqlite-prefix
--no-update-check Don't check for updates.
--help display help for command
Environment Variables:
HOST Same as --host.
PORT Same as --port.
REDIRECT_PORT Same as --redirect-port.
TIMEOUT Same as --timeout.
KEEPALIVETIMEOUT Same as --keep-alive-timeout.
REALM Same as --realm.
CERT_FILE Same as --cert.
CERT Text of a cert in PEM format.
KEY_FILE Same as --key.
KEY Text of a key in PEM format.
HOME_DIRECTORIES Same as --home-directories when set to "true", "on" or "1".
USER_DIRECTORIES Same as --user-directories when set to "true", "on" or "1".
SERVE_INDEXES Same as --serve-indexes when set to "true", "on" or "1".
SERVE_LISTINGS Same as --serve-listings when set to "true", "on" or "1".
FOLLOW_LINKS Same as --no-follow-links when set to "false", "off" or "0".
FILE_PROPERTIES Same as --file-properties.
FILE_LOCKS Same as --file-locks.
AUTH Same as --no-auth when set to "false", "off" or "0".
PAM_AUTH Same as --pam-auth when set to "true", "on" or "1".
AUTH_USER_FILENAME Same as --auth-user-filename.
AUTH_USER_FILE Same as --auth-user-file.
AUTH_USERNAME Same as --auth-username.
AUTH_PASSWORD Same as --auth-password.
ENCRYPTION Same as --encryption when set to "true", "on" or "1".
ENCRYPTION_SALT Same as --encryption-salt.
ENCRYPTION_FILENAME_SALT Same as --encryption-filename-salt.
ENCRYPTION_FILENAME_IV_SALT Same as --encryption-filename-iv-salt.
ENCRYPTION_FILENAME_ENCODING Same as --encryption-filename-encoding.
ENCRYPTION_GLOBAL_PASSWORD Same as --encryption-global-password.
ENCRYPTION_EXCLUDE Same as --encryption-exclude.
S3_ENDPOINT Same as --s3-endpoint.
S3_REGION Same as --s3-region.
S3_ACCESS_KEY Same as --s3-access-key.
S3_SECRET_KEY Same as --s3-secret-key.
S3_BUCKET Same as --s3-bucket.
NYMPH Same as --nymph when set to "true", "on" or "1".
NYMPH_JWT_SECRET Same as --nymph-jwt-secret.
NYMPH_REST_PATH Same as --nymph-rest-path.
NYMPH_SETUP_PATH Same as --nymph-setup-path.
NYMPH_REGISTRATION Same as --no-nymph-registration when set to "false", "off" or "0".
NYMPH_EXPORT Same as --nymph-export.
NYMPH_IMPORT Same as --nymph-import.
NYMPH_DB_DRIVER Same as --nymph-db-driver.
NYMPH_MYSQL_HOST Same as --nymph-mysql-host.
NYMPH_MYSQL_PORT Same as --nymph-mysql-port.
NYMPH_MYSQL_DATABASE Same as --nymph-mysql-database.
NYMPH_MYSQL_USERNAME Same as --nymph-mysql-username.
NYMPH_MYSQL_PASSWORD Same as --nymph-mysql-password.
NYMPH_MYSQL_PREFIX Same as --nymph-mysql-prefix.
NYMPH_POSTGRES_HOST Same as --nymph-postgres-host.
NYMPH_POSTGRES_PORT Same as --nymph-postgres-port.
NYMPH_POSTGRES_DATABASE Same as --nymph-postgres-database.
NYMPH_POSTGRES_USERNAME Same as --nymph-postgres-username.
NYMPH_POSTGRES_PASSWORD Same as --nymph-postgres-password.
NYMPH_POSTGRES_PREFIX Same as --nymph-postgres-prefix.
NYMPH_SQLITE_CACHE_SIZE Same as --nymph-sqlite-cache-size.
NYMPH_SQLITE_PREFIX Same as --nymph-sqlite-prefix.
UPDATE_CHECK Same as --no-update-check when set to "false", "off" or "0".
SERVER_ROOT Same as [directory].
Options given on the command line take precedence over options from an environment variable.
Properties and Locks:
When Nephele is loaded with the file system adapter, you can customize how it
handles properties and locks. This can help you keep your file system clean.
FILE_PROPERTIES:
The client can request to add any arbitrary property it wants (the WebDAV spec
calls these "dead properties"), and this controls how that situation is
handled.
- "meta-files": Save these properties in ".nephelemeta" files.
- "disallow": Refuse to save them and return an error to the client.
- "emulate": Don't actually save them, but return a success to the client.
"meta-files" is the default, as the WebDAV spec states that WebDAV servers
"should" support setting these properties. However, if you don't want meta
files cluttering up your file system, you can make a choice:
"disallow" will tell the client that any property it tries to set is
protected. A well written client will understand this and move on.
"emulate" will tell the client that the property was successfully set, even
though it wasn't really. If a client is poorly written and can't handle an
error on property setting, this will allow Nephele to still work with that
client.
This setting does not affect "live properties", like last modified date and
content length.
FILE_LOCKS:
This works the same as "properties", except that "disallow" also causes
Nephele to report to the client that locks are not supported at all.
Again, a poorly written WebDAV client may require "emulate" to work with
Nephele.
Encryption:
Nephele supports file encryption. It uses either a global encryption password
or user passwords to encrypt your files.
To enable encryption, set the encryption option and provide three long,
random, unique strings for the salt, filename salt, and filename IV salt. You
can generate long random strings here: https://www.uuidgenerator.net/
If you use username passwords for encryption, you can't change a user's
password or their files will no longer be accessible.
If you disable auth, you must set a global encryption password to use
encryption. If you then change this global password, your files will no longer
be accessible.
Likewise, if you change any of the salts, your files will no longer be
accessible.
You also have a choice of filename encodings. You can set this to 'ascii85' if
you know your file system supports non UTF-8 filenames. This will allow files
with longer filenames.
You can also exclude files from encryption by providing a comma separated list
of glob patterns.
You can find more information about Nephele's file encryption here:
https://github.com/sciactive/nephele/blob/master/packages/plugin-encryption/README.md
S3 Object Store:
Nephele supports using an S3 object store as its storage backend.
S3 and S3 compatible servers are essentially key-value stores. Nephele can
present this store as a hierarchical file structure by using the file path and
filename as the key. This is a common practice and is often supported by the
native object browser of the store.
By combining an S3 backend with Nephele's encryption feature, you can get the
benefits of cloud storage while maintaining your privacy and security.
An important note is that an S3 key has a maximum length of 1024 bytes using
UTF-8 encoding. This means the entire file path, including the slash
characters that separate directories, can only be 1024 bytes long, so you may
run into problems with deeply nested file structures.
You can find more information about S3 keys here:
https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html
WebDAV properties and locks are stored in the metadata of objects. There is no
support for properties or locks on a directory, since S3 doesn't really have
"real" directories.
S3 does not have the concept of an empty directory, since "directories" are
just common prefixes among keys. As such, Nephele represents an empty
directory in S3 by creating an empty object under the directory with the name
".nepheleempty". It is safe to delete these objects. It is the same as
deleting the empty directory.
You can find more information about Nephele's S3 adapter here:
https://github.com/sciactive/nephele/blob/master/packages/adapter-s3/README.md
Nymph and File Deduplication:
When Nephele is loaded with the Nymph adapter, it will use a deduplicating
file storage method. File metadata is stored in the Nymph database, which can
be a SQLite3, MySQL, or PostgreSQL database, and file contents are stored on
disk using their SHA-384 hash for deduplication.
When using the Nymph adapter, unless auth is disabled, PAM auth is enabled, or
a global username/password is set, the Nymph authenticator will be loaded.
This authenticator uses Tilmeld, which is a user/group manager for Nymph. The
first user you create will be the admin user, then you should turn off
registration.
The SQLite3 driver is easier to set up, because the DB can be stored in a file
alongside the file blobs, but it is considerably slower if you have many files
in your server. It also must be on a local disk, because it uses SQLite's
write ahead log.
The MySQL and PostgreSQL drivers are much faster. If you start with a SQLite
DB and end up outgrowing it, you can export your Nymph DB to a NEX file, then
import it into a new database. The import can take a long time (many hours),
so plan for downtime if you do this.
Because the files are deduplicated, this can be a great option if you store
something like regular backups, where many files have the same contents.
You can find more information about Nephele's Nymph.js adapter here:
https://github.com/sciactive/nephele/blob/master/packages/adapter-nymph/README.md
You can find more information about Nephele's Nymph.js authenticator here:
https://github.com/sciactive/nephele/blob/master/packages/authenticator-nymph/README.md
You can find more information about Nymph.js:
https://nymph.io
Nephele repo: https://github.com/sciactive/nephele
Copyright (C) 2022-2025 SciActive, Inc
https://sciactive.com/
`
This example shows the steps for a setup where you:
- use an Ubuntu or Debian based server
- use a Let's Encrypt certificate for TLS
- want to serve user directories for system users out of a custom folder
- want to serve directory listings for browser support
- want to use a cluster of 8 worker processes
- want to have the server load on startup
You would replace example.com with your domain, and the path at the end with your server root path.
`shFollow these install directions to install Node (the minimum Node version is v18):
https://github.com/nodesource/distributions#installation-instructions
I recommend installing Node from NodeSource instead of apt, because apt tends to have very outdated versions and lots of unnecessary dependencies.
Copyright 2022-2025 SciActive Inc
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.