Run your own Dropserver with ds-host
Applicable Versions:
This page is valid for version 0.9.x.
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:
- 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
.
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
}
}
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
: thememory.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
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:
- 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.
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.