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

Warning ⚠⚠⚠

At this point a good chunk of ds-host is functional. You can upload app code, create appspaces, migrate, add users, and use the appspace with other users.

However:

• There are going to be security holes. Don’t use app code you don’t trust. Don’t put it up on the public internet unless it’s completely isolated in a VM and don’t put data on there you can’t afford to have stolen.
• Leaks! Memory 📈 goroutines 📈
• Lots of missing or half-baked functionality
• Some of the UI is un-styled, incomplete, or simply missing entirely
• No user docs
• APIs that the apps use are going to change a lot
• Config file schema will change too

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.

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

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 as /etc/systemd/system/dropserver.service.

[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

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.