Run your own Dropserver with ds-host on Linux

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).

Speedrun

• Download the latest version of ds-host.
• Install Deno.
• Point a domain and its subdomains to your host or your reverse proxy.
• 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 built by one guy. There may be security holes! Please be mindful of potential risks, particularly if you expose ds-host to the internet.

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.

ds-host is available for x86-64 (Intel / AMD) and arm64 processors such as the Raspberry Pi.

Install Deno

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

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
	}
}

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.

Extra Sandboxing with Bubblewrap

If you would like an additional layer of security you may want to try using Bubblewrap.

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.