dropserver

Github

Run your own Dropserver with ds-host

Applicable Versions:

This page is valid for version 0.9.0 and above.

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

Note:

ds-host is for running a full instance of Dropserver. If you just want to run an app locally for development purposes, use ds-dev.

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:

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.

Note:

Currently ds-host does not serve anything when loading the naked domain (example.com). To log in you will visit dropid.example.com (replacing example.com with your domain naturally).

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

Note:

To use cgroups, ds-host must run in a delegatable cgroup. This is typically accomplished by having systemd run ds-host as a service, and setting Delegate=true in the service config (see below).

The default config for cgroups looks like this:

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

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
Note:

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, which is also echoed to your terminal if you run ds-host as above. Look for setup_key_reveal= and use the link to create an account.

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:

Note:

The user interface in ds-host is unfinished and documentation on how to use it is unwritten. So poke around and ask me questions directly via email or mastodon.

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