Run your own Dropserver with ds-host

ds-host is the full Dropserver and is intended to serve your appspaces in use. ds-host serves a user interface for administrators and users, as well as requests destined for appspaces. (see Application Model for a better understanding of this concept.) It can listen on ports 80 and 443 or it can sit behind a reverse proxy (see below). ds-host is Linux-only and must be run on x86 architecture (for now).

Speedrun

• On a Linux host, acquire the latest version of ds-host and Deno. Optionally install Bubblewrap “bwrap” from your package manager.
• Point a domain and its subdomains to your host.
• Create /srv/dropserver and /var/run/dropserver with read/write permissions.
• Create a config.json (see below).
• Run ds-host -config=/path/to/config.json -migrate
• Run ds-host -config=/path/to/config.json
• Look for setup_key_reveal= in the terminal output and use that URL to create an admin user.
• Log in as your admin user and you’re good to go.

Warning ⚠

At this point a good chunk of ds-host is functional. You can install apps, create appspaces, migrate, add users, and use the appspace with other users. From experience it can run for months at a time without issues.

However Dropserver is a big project run by one guy. There may be security holes! For the time being, don’t use app code you don’t trust and don’t put it up on the public internet unless it’s isolated in a VM and don’t put data on there you can’t afford to have stolen.

While we’re setting expectations:

• Some functionality is missing or half-baked
• APIs that the apps use are going to change a few times before they become stable
• The config file schema may change too

And now, let’s dive in.

Install ds-host

Obtain the latest release from the Releases page and unzip. Place in /usr/local/bin or some other directory of your choice.

Install Dependencies

You should have Deno installed and available from wherever you’ll be running ds-host.

Bubblewrap is optional but recommended. It is used to wrap Deno in an additional sandbox based on Linux namespaces. Should a vulnerability be discovered in Deno, Bubblewrap should prevent an exploit from causing any harm. Of course an attacker will try to also find an exploit to get out of the Bubblewrap sandbox too, but two exploits are harder to find than one.

Bubblewrap is available from package managers of most distros. ds-host should work with bwrap version 0.5 or higher.

If you do not wish to use Bubblewrap set sandbox.use-bubblewrap to false in your config file. See below for more details.

Domain Name

Dropserver makes use of subdomains to separate appspaces and the user administration site into different origins. For this reason you need to forward a domain and all its subdomains to your instance.

One way to do this is by setting A and AAAA records for @ and * (wildcard) to your instance IP.

Create Directories

Create an empty data directory, let’s say it is /srv/dropserver.

Create and empty directory for sockets, say /var/run/dropserver.

Make sure the user that will be running ds-host has read, write and execute permissions for these directories.

Configuration File

Create a configuration file such as /etc/dropserver.json and make sure the user running ds-host can read it.

Read below for configuration examples, and consult the configuration variables reference for more details.

With TLS Termination

If you wish expose ds-host directly to the internet this configuration will work:

{
	"data-dir": "/srv/dropserver",
	"server": {
		"tls-port": 443,
		"http-port": 80
	},
	"external-access": {
		"subdomain": "dropid",
		"domain": "example.com"
	},
	"manage-certificates": {
		"enable": true,
		"acme-account-email": "you@example.com"
	},
	"sandbox":{
		"sockets-dir": "/var/run/dropserver",
		"use-bubblewrap": false,
		"use-cgroups": false
	}
}

In this case ds-host will use Let’s Encrypt to generate certificates for each subdomain as needed, starting with dropid.example.com.

Behind Reverse Proxy

If you are running ds-host behind a reverse proxy listening on ports 80 and 443 with SSL termination (recommended) your config might look something like this:

{
	"data-dir": "/srv/dropserver",
	"server": {
		"http-port": 5050,
		"no-tls": true
	},
	"external-access": {
		"subdomain": "dropid",
		"domain": "example.com"
	},
	"sandbox":{
		"sockets-dir": "/var/run/dropserver",
		"use-bubblewrap": false,
		"use-cgroups": false
	}
}

In this case you can not use certificate management on ds-host. In this case it is best to obtain a wildcard certificate for the domain and configure your reverse proxy to use that.

Local Network

If you are experimenting on a local network and you are using non-standard ports, you might try a configuration like this one:

{
	"data-dir": "/srv/dropserver",
	"server": {
		"tls-port": 5050,
		"ssl-cert": "/path/to/ssl/example_com.crt",
		"ssl-key": "/path/to/ssl/example_com.key"
	},
	"external-access": {
		"domain": "example.com",
		"subdomain": "dropid",
		"port": 5050
	},
	"sandbox":{
		"sockets-dir": "/var/run/dropserver",
		"use-bubblewrap": false,
		"use-cgroups": false
	}
}

With this configuration the site will be reachable at https://dropid.example.com:5050 (set your local DNS server accordingly). There would be no reverse proxy in this scenario, and ds-host does the SSL termination.

No TLS

You can also skip the whole TLS thing for local experimentation like this:

{
	"data-dir": "/srv/dropserver",
	"server": {
		"http-port": 5050,
		"no-tls": true
	},
	"external-access": {
		"scheme": "http",
		"domain": "example.com",
		"subdomain": "dropid",
		"port": 5050
	},
	"sandbox":{
		"sockets-dir": "/var/run/dropserver",
		"use-bubblewrap": false,
		"use-cgroups": false
	}
}

Bubblewrap

In the examples above we turned Bubblewrap off for the sake of simplicity. If you have Bublewrap (typically easily installed via your package manager) then you need to make a few changes to your config:

{
	...
	"sandbox": {
		"use-bubblewrap": true,
		"bwrap-map-paths": ["..."]
	}
}

The bwrap-map-paths is the tricky bit. These are the paths from the host that must be mapped to the sandbox such that Deno can work. For Ubuntu, the following seems to work:

"bwrap-map-paths": ["/lib", "/usr/lib", "/etc", "/lib64", "/run"]

For Arch, this works (and is the default value):

"bwrap-map-paths": ["/usr/lib", "/etc", "/lib64"]

CGroups

Regardless of the configuration you use from above, you can add cgroup control of sandbox resource usage.

By default ds-host uses cgroups (version 2) to measure and control resources used by appspaces (this is a work in progress).

The default config for cgroups looks like this:

{
	...
	"sandbox": {
		...
		"use-cgroups": true,
		"cgroup-mount": "/sys/fs/cgroup",
		"memory-high-mb": 512
	}
}

• use-cgroups set to false if you can not or do not want to deal with cgroups.
• cgroup-mount: the location of your system’s cgroups.
• memory-high-mb: the memory.high value for the cgroup that contains all the sandbox cgroups, in megabytes.

Initial Run

Once you have a configuration file ready, initialize the DB. The -migrate flag will migrate the DB to the latest schema, creating a DB in the process if needed.

$ ds-host -config=/etc/dropserver.json -migrate

Finally, you can start ds-host directly:

$ ds-host -config=/etc/dropserver.json

Run with Systemd

In practice it’s easier to have systemd run ds-host. This is particularly true if you have configured resource limits of appspace sandboxes using cgroups.

Here is a minimal unit file you can use to get started. Replace values as needed and save it alongside other systemd services (such as /etc/systemd/system/dropserver.service on Arch).

[Unit]
Description=Dropserver service
ConditionPathExists=/path/to/ds-host
After=network.target

[Service]
Type=simple
User=dsuser
Group=dsuser
TimeoutStopSec=15

# This lets ds-host bind to a low port (80, 443) without running as root:
AmbientCapabilities=CAP_NET_BIND_SERVICE

Delegate=true

ExecStart=/path/to/ds-host -config=/etc/dropserver.json

[Install]
WantedBy=multi-user.target

Then you can start the service:

$ sudo systemctl start dropserver 

Check the service is running with:

$ systemctl status dropserver 

Tail the logs using:

$ journalctl -u dropserver.service -f

Create the Admin User

The first time you run ds-host the system will detect that there is no admin user and it will create a secret link where you can register as an admin. The link is printed in the log output.

Look for setup_key_reveal= and use the link to create an account.

Log In

Now that ds-host is running and you created your admin user, some of the first things to do will be:

• Create a dropid for yourself. A dropid is an id that can be a user of an appspace.
• Add an app by uploading it manually. I recommend you go through the app tutorial to understand what goes into making apps.
• Create an Appspace by choosing an app and a subdomain.

Now that you have Dropserver running, have a look at how easy it is to make an app here.