[deutsch]

Kontrast HTTP server

The Kontrast HTTP server serves files from a directory on your disk over HTTP to your browser. We created the Kontrast HTTP server as a standalone executable that you can use for local development.

Browser http://localhost:8000/
⇄
HTTP server
⇄
Files on your disk

Features

Kontrast HTTP server ...

Usage

Kontrast HTTP server is an application that runs without a dedicated graphical user interface. On Windows and MacOS, the application automatically will open the system terminal, which shows a log of all activities (along with possible warnings and errors) from the application. If you close the terminal (or press Ctrl-C in the terminal) the HTTP server terminates and stops serving files.

When executing Kontrast HTTP server for the first time, a configuration file is automatically created for you. You can customize this configuration file according to the description below.

On Windows

Execute kontrast-http-server.exe (by double-clicking) and your browser will navigate automatically to the correct location. By default, the HTTP server will make files inside the directory site accessible over HTTP.

To terminate the server, press Ctrl + C (the interrupt signal) in the terminal or simply close the terminal.

On MacOS

If you start Kontrast HTTP server for the first time, right-click on kontrast-http-server and select Open. You will be asked whether you trust the application. If you continue to select Open, the HTTP server will start.

Once you completed the above steps, you can start the HTTP server in the future by simply double-clicking kontrast-http-server.

If you prefer using the command line, you can simply execute the binary kontrast-http-server. You can also copy this binary to different directories, as it works standalone. The included wrapper shell script is only necessary for Finder, as for some reason Finder executes applications with the Users' home directory as the current working directory (instead of the actual current working directory).

To terminate the server, press Ctrl + C (the interrupt signal) in the terminal or simply close the terminal.

On Linux

In your favorite terminal, navigate to the directory where the binary is located and execute ./kontrast-http-server to start the application.

To terminate the server, press Ctrl + C.

Configuration

All settings of the HTTP server can be changed by editing the file kontrast-http-server-config.json in a text editor of your choice. This is the default configuration:

Address and port

The address property specifies the IP address at which the HTTP server listens for requests. The value 127.0.0.1 means that the server listens to local connections only. This is the safest setting, as no other computers in your network are able to access the HTTP server. If you know what you are doing, you can use the wildcard address 0.0.0.0 to allow all computers in your local network to access the HTTP server (if your firewall is configured to allow this).

The port property specifies the port at which the HTTP server listens for requests. Port 80 is the default port for the HTTP protocol. If you choose a different port, you have to explicitly change the URL in your browser to address:port. For example, if address equals "127.0.0.1" and port is set to 8000, you can reach the HTTP server at http://127.0.0.1:8000/. This information is also shown in the terminal output of the application.

The route list

The HTTP server serves files according to a set of routes specified within the filesystem property. The property routeList is an array of objects with an alias path that specifies the first part of an URL and a target path that specifies a directory on your disk to be reached under the corresponding alias.

For each incoming request, the routeList is traversed in the given order until the first part of the requested URL matches with the alias. The file is consequently served from the directory specified in target.

For convenience, Kontrast HTTP server automatically serves the file index.html from a directory (if the file exists) and automatically appends the .html file extension. So instead of http://localhost:8000/support.html you can enter http://localhost:8000/support and instead of http://localhost:8000/doc/index.html you can enter http://localhost:8000/doc/ or even http://localhost:8000/doc (the trailing slash is automatically added). This is also detailed in the next paragraph.

Files and directories

URLs with a forward slash at the end specify a directory; URLs without a forward slash at the end refer to files.

When you request the URL http://localhost:8000/abc, the HTTP server will first try to serve the file TARGET/abc and secondly the file TARGET/abc.html. If neither file exists, the HTTP server checks whether there is a directory TARGET/abc/. If this is the case, the HTTP server will send a 301 Permanently Moved redirection to the location http://localhost:8000/abc/ (notice the trailing slash). As a consequence, your browser will navigate to the new URL with the trailing slash.

If you enter the URL http://localhost:8000/abc/ (or if you get forwarded to the URL) the HTTP server will try to serve the file TARGET/abc/index.html. If there is no such file, the HTTP server will list the contents of the directory TARGET/abc/ instead.

Example: Using multiple routes to access data from different directories

The following example includes routes to two different directories: One site target directory with the root alias / and a more specific route that maps all requests for /data/... to the specified target directory.

Path specifications

The target directory can be an absolute or a relative path. If you do not specify an absolute path, the specified path is assumed to be relative to your current working directory. Typically, this is simply the directory containing the HTTP server executable when you execute the application.

It does not matter whether you use forward slashes (/) or backward slashes (\). However, the JSON configuration file format requires backward slashes to be escaped by another backward slash. For example, you can use either "C:\\directory\\projectA" or "C:/directory/projectA".

Symbolic links are never followed/expanded for security reasons. This cannot be disabled. Instead of symbolic links, you can add corresponding entries to the routeList.

Writing files over HTTP

You can use the HTTP PUT method to write files to disk over HTTP. For security reasons, this feature is not enabled by default. You can enable the write separately for individual routes by specifying allowWrite: true. Consider using this feature with care and do not enable the feature if you do not need it.

The following example shows a configuration where you additionally have write access to the target directory site/write-data/. For more information on how to use the HTTP PUT method please refer to Using external data resources.

Deleting files over HTTP

You can use the HTTP DELETE method to delete files. For security reasons, this feature is not enabled by default. You can enable the write separately for individual routes by specifying allowDelete: true. Consider using this feature with care and do not enable the feature if you do not need it.

Automatic browser navigation

In Windows and MacOS you can instruct the Kontrast HTTP server to automatically open your browser to a specific URL when you start the HTTP server. The Kontrast HTTP server will ask your operating system to launch the default browser as defined in your operating system settings. Note: This feature is not available on Linux and FreeBSD.

If the browser section within the configuration file has the property open set to true, the Kontrast HTTP server will automatically open your browser at the address where the HTTP server can be reached. The URL that is initially requested is specified using the path property. The path property must start with a forward slash and must only contain characters that are valid within URLs. Characters that would be invalid (such as a space) must be percent-encoded as detailed in the MDN Glossary for percent-encoding.