Server Setup and Administration

Setup Server Directory

A TomatenHTTP server is contained in a server folder rather than being installed globally.

To easily generate a server folder you can create an empty directory and install TomatenHTTP using TomatenPack with the command tpack install tomatenhttp.

Config Directory

Here, you can configure basic properties that affect the server as a whole.

Most interesting (and most probable to require changes) is the server.toml file. Among other things, the ports to be opened by the server are configured here.

The default port, 80, is the correct default if this is your user-facing webserver and it has the necessary permissions to bind that port, but otherwise it will need to be changed to whatever suits your setup.

There is also a preset to open the default HTTPS port 443. For it to really work, you will have to configure the certificate(s) to use. For usage with Certbot, see Using Certbot with TomatenHTTP.

Lib Directory

This folder contains JAR files with all the web app implementations, along with libraries and TomatenHTTP itself.

TomatenPack usually manages this folder, but you can also manually add JAR files with app implementations for testing. For production environments, I recommend proper package management, e.g. TomatenPack.

See Implement Custom Apps on how to implement your own app.

Apps Directory

The apps directory contains the app definitions, each file representing one app.

These files should be named <name>.<type>.<format>, where json and toml are supported formats.

The <name> identifies the app instance, <type> is the app type name as specified in its implementation anywhere in the lib folder.

The content of these files is the app configuration which the app implementation can access.

There are some basic predefined app types, so for example, an app defined by file mypublicfiles.file.toml with content

file = "mypublicfolder"
location = "/public/*"

would expose all files in the folder mypublicfolder under <server-address>/public/.

An app defined by file "tomaten.redirect.toml" with content

srclocation = "/tomaten",
destlocation = "https://tomaten.dev/"

would redirect <server-address>/tomaten to https://tomaten.dev/.

App Management

All apps start as defined in the app directory when the server starts, but they do not automatically start/stop when the app definitions are changed while the server is running.

For this, the app command in the server console can be used.

Use app list to list all apps, that includes running and only defined apps. Further use app start/stop/restart <name> to start/stop/restart an app.

These operations can also start/stop/restart multiple apps at once by naming them all, e.g. app start <name1> <name2>. With this, the server can attempt to better respect app dependencies and to abort the operation as a whole if failure is forseeable.

Only if you add the -r/--recursive flag, dependant apps will automatically be considered in the operation, that means starting depended apps or stopping depending apps. Without this flag, the operation will only affect the explicitly named apps and will abort if that is insufficient.

Reloading

The reload command in the server console can reload things, like most configurations, without restarting the server.

For example, changes to the configured ports in the config/server.toml are applied and certificates are reloaded immediately.

Apps are provided with updated configurations. It is up to the app implementations to handle reloading. Reloads are generally meant to be safe, so apps are not restarted or forced to react at all, but instead urged to prioritize stability over reloading.

Turning the server into development mode (either with the console command devmode or development = true in the config/server.toml) has a similar effect as frequent reloading. Many things will bypass their caches / reload on access, for example, File apps switch to direct file access instead of using pregenerated indexes.