Serverlets

What is a Serverlet?

You are surely wondering what a Serverlet actually is. We will not keep you waiting: it is the name of our web hosting. Why a Serverlet? We think the generic term “web hosting” does not quite fit our case and does not capture everything it offers. Our Serverlet is a compromise between plain web hosting and a virtualized managed server — a bit of a hybrid.

Technology

The Serverlet itself is an environment we assembled for running your application, and it runs as a Docker container. That makes it virtualization at the operating system level, known as containerization: containers share the kernel of the host system and are separated from each other by namespaces and cgroups. It is not full virtualization with a kernel of its own, the way virtual machines work.

Your Serverlet contains all the software needed to run your application and is completely separated from the Serverlets and applications of other users.

Operating system

Every Serverlet has its own small and, to a certain extent, independent OS. We use Ubuntu both as the host operating system and as the OS inside the Serverlet — currently Ubuntu 22.04 LTS.

Process management

Unlike a standard Ubuntu system, services in our Serverlet are managed by runit. It makes sure all your applications start up correctly after boot and brings them back up if they crash. You can read more about it in the separate Runit chapter.

Runit

All applications in the Serverlet are managed by runit. It ensures that every application starts once the Serverlet boots and brings it back up in case of a crash. All of its configuration lives in the /srv/service directory. Right after the Serverlet is created you will find directories there for the individual services running in the background, along with their startup scripts.

Adding your own application

Adding your own application is very simple. Once added, the application can also be controlled from the administration.

How to add one:

1. First create a directory named after the application inside /srv/service, for example /srv/service/my-application.
2. In that directory create a run file that starts the application, that is /srv/service/my-application/run.
3. Put the command that starts the application into the file. The application must keep its main process in the foreground and must not move into the background. Otherwise it will cause repeated start attempts that consume most of the Serverlet’s resources. For some applications you therefore need to turn off daemon mode.

An example run file for MongoDB:

#!/bin/sh -e
exec 2>&1
exec /usr/bin/mongod --config /srv/config/mongodb/mongod.conf

4. Save the file.
5. The applet user must have all the necessary permissions to the directory for runit to work correctly.
6. Within a minute or so, runit detects and starts the newly added application. It stores the information it needs, such as the process PID, in the supervise subdirectory.
7. Done — the application will start automatically after boot and will be brought back up after a crash. You can control it with the app or sv command.

More useful information is available on the runit project page.

Removing an application

Removing an application is simple. Stop it with app stop {my-application} and then delete its directory in /srv/service.

Control

Controlling the Serverlet

Starting, restarting, and shutting down a Serverlet can only be done from the administration, on that Serverlet’s card.

A restart is equivalent to a forced power-off and power-on. It interrupts applications, which can lead to the loss of unsaved data or to database corruption. Perform it only when necessary; where possible, shut the other applications down properly first. After any of these actions, wait at least 60 seconds before the next one.

A stopped Serverlet is billed the same as a running one, because the resources it needs stay reserved for it.

Managing software

Both pre-installed and custom software on the Serverlet can be controlled in two ways. We do not recommend using them at the same time: the administration does not show changes made over SSH in real time.

Disabled software takes up no resources and does not start at boot. Enabled software starts automatically after boot. After a Serverlet is created, most software is disabled. Once first enabled, software such as MariaDB, PostgreSQL, or MongoDB reserves disk space that stays occupied until it is deleted.

Every additional piece of enabled and running software consumes Serverlet resources. Enable only the software your application actually needs.

Administration

Software control is in the administration on the Software card. It lists all software on the Serverlet managed by runit; you add your own software as described in the Runit chapter.

Icon	Action	Description
	Reload	The application reloads its configuration. This is a restart without downtime for applications that support it.
	Restart	A hard restart with downtime.
	Stop	Stops the application.
	Start	Starts the application.

Terminal

The Serverlet can also be controlled over SSH. The app command is ready for this purpose:

Futrou Serverlet Manager
Usage: app {start|restart|reload|stop|status|disable|enable} {app_name}
Usage: app list

Usage:

app {command} {application-name}

For example, to show the status of the LiteSpeed Web Server:

app status lsws

List the applications with:

app list

Example output:

System apps:
    runit
Registered user apps:
    lsws
    mariadb
    my-application
    mongodb
    redis