Web Server

ENiGMA½ comes with a built in content server for supporting both HTTP and HTTPS. Currently the File Base registers routes for file downloads, password reset email links are handled via the server, and static files can also be served for your BBS. Other features will likely come in the future or you can easily write your own!

Configuration

By default the web server is not enabled. To enable it, you will need to at a minimum configure two keys in the contentServers.web section of config.hjson:

contentServers: {
    web: {
        domain: bbs.yourdomain.com

        http: {
            enabled: true
            port: 8080
        }
    }
}

The following is a table of all configuration keys available under contentServers.web:

Key	Required	Description
domain	Yes	Sets the domain, e.g. bbs.yourdomain.com.
http	No	Sub configuration for HTTP (non-secure) connections. See HTTP Configuration below.
https	No	Sub configuration for HTTPS (secure) connections. See HTTPS Configuration below.
staticRoot	No	Path serving as the static/public root. Defaults to enigma-bbs/www. See Static Root below.
overrideUrlPrefix	No	Instructs the system to be explicit when handing out URLs. Useful if your server is behind a transparent proxy.

HTTP Configuration

Entries available under contentServers.web.http:

Key	Required	Description
enabled	Yes	Set to true to enable this server. Defaults to false.
port	No	Override the default port of 8080.
address	No	Sets an explicit bind address.

HTTPS Configuration

Entries available under contentServers.web.https:

Key	Required	Description
enabled	Yes	Set to true to enable this server. Defaults to false.
port	No	Override the default port of 8443.
address	No	Sets an explicit bind address.
certPem	No	Overrides the default certificate path of config/https_cert.pem. Certificate must be in PEM format. See Certificates below.
keyPem	No	Overrides the default certificate key path of config/https_cert_key.pem. Key must be in PEM format. See Certificates below.

Certificates

If you don’t have a TLS certificate for your domain, a good source for a certificate can be Let’s Encrypt who supplies free and trusted TLS certificates. A common strategy is to place another web server such as Caddy in front of ENiGMA½ acting as a transparent proxy and TLS termination point.

Note

Keep in mind that the SSL certificate provided by Let’s Encrypt’s Certbot is by default stored in a privileged location; if your ENIGMA instance is not running as root (which it should not be!), you’ll need to copy the SSL certificate somewhere else in order for ENIGMA to use it.

Static Root

Static files live relative to the contentServers.web.staticRoot path which defaults to enigma-bbs/www. This is also commonly known as your “public root” directory.

Custom Error Pages

Customized error pages can be created for HTTP error codes by providing a <error_code>.html file in the static routes area. For example: 404.html.

REST API

ENiGMA½ includes a built-in REST API served under /_enig/api/v1/, providing programmatic access to message bases, file areas, user profiles, and system information.

Web Handlers

Web Handlers are loaded by the web content server and provide a easy way for adding additional routes & functionality to ENiGMA.