Requirements

Node.js

Hohenheim requires at least node.js version 10.21.0

Mongodb

You will need a mongodb server.

n

Although technically not required, you can configure your sites to use a specific node.js version installed through the n node version manager

Capabilities

Hohenheim requires that your node.js binary has some extra capabilities. These are:

• cap_setuid: for setting the uid of the instances it spawns
• cap_setgid: for setting the gid of the instances it spawns
• cap_kill: for killing spawned instances with another uid than its own
• cap_net_bind_service: for binding to privileged ports, like port 80 & 443

(If you prefer to route port 80 & 443 to another port, you can drop cap_net_bind_service)

It's best to give hohenheim its own node executable, otherwise all scripts running would have these capabilities.

File Descriptor Limits

As a reverse proxy handling many concurrent connections, Hohenheim may need more file descriptors than the default limit (typically 1024). You should increase this limit to avoid EMFILE: too many open files errors under load.

For systemd services, add this to your service file (see Systemd section below):

LimitNOFILE=60000

For manual runs, set the limit before starting:

ulimit -n 60000

System-wide configuration via /etc/security/limits.conf:

www-data soft nofile 60000
www-data hard nofile 60000

(Replace www-data with the user running Hohenheim)

Here's an easy example on how to create a new node binary (your locations may differ)

sudo cp /usr/local/bin/node /usr/local/bin/hohenode

That's easy. Now give it the required capabilities:

sudo setcap 'cap_kill,cap_setuid,cap_setgid,cap_net_bind_service=+ep' /usr/local/bin/hohenode

Should you ever want to remove all capabilities from the binary, you can do so like this:

sudo setcap -r /usr/local/bin/hohenode

Configuration

You will need to configure the following files

app/config/local.js

module.exports = {

    // The main port to listen on
    proxyPort: 80,

    // The main port to listen on for HTTPS/http2 traffic
    proxyPortHttps: 443,

    // Your current environment. Can be dev, preview or live
    environment: 'live',

    // When no sites match, this address will be tried last
    // (This can be your apache server, for instance)
    fallbackAddress: 'http://localhost:8080',

    // The host hohenheim will use to access the spawned node sites,
    // this should probably remain "localhost"
    redirectHost: 'localhost',

    // The first port to use for child node instances
    firstPort: 4748,

    // This is the port the admin interface listens on
    port: 2999,

    // Set to true to enable letsencrypt
    letsencrypt: true,

    // The default e-mail address to use for letsencrypt registrations
    letsencrypt_email: '[email protected]',

    // Add the ipv6 address you want to listen on
    ipv6Address: ''
};

app/config/dev/database.js or app/config/live/database.js

You'll find the database settings here, by default these are:

Datasource.create('mongo', 'default', {
    host     : '127.0.0.1',
    database : 'hohenheim-live',
    login    : false,
    password : false
});

Admin interface

Once you have everything configured and running, you can go to the admin interface at http://localhost:2999/chimera

The default credentials are admin:admin

HTTPS & HTTP/2

If you want https & http/2 support, you need to set letsencrypt: true in your local configuration.

If you want to use your own certificates (and not letsencrypt), the greenlock module we use lets you do that. You just need to put your own certificate files into the correct directory.

Eg: if you have your own certificates for the domain example.com, you can put them here:

~/hohenheim/temp/letsencrypt/etc/acme/live/example.com/privkey.pem
~/hohenheim/temp/letsencrypt/etc/acme/live/example.com/cert.pem
~/hohenheim/temp/letsencrypt/etc/acme/live/example.com/chain.pem
~/hohenheim/temp/letsencrypt/etc/acme/live/example.com/fullchain.pem
~/hohenheim/temp/letsencrypt/etc/acme/live/example.com/bundle.pem

Systemd

Keep hohenheim running by setting up a Systemd service, for example:

sudo nano /etc/systemd/system/hohenheim.service

And then enter

[Unit]
Description=Hohenheim site dispatcher
After=mongodb.service

[Service]
WorkingDirectory=/home/www-data/hohenheim/
ExecStart=/usr/local/bin/hohenode /path/to/your/hohenheim/server.js
Restart=always
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=hohenheim
User=www-data
Group=www-data
Environment=NODE_ENV=production
LimitNOFILE=60000

[Install]
WantedBy=multi-user.target

You will need to change:

• After: Other services to wait for (in this case mongodb)
• WorkingDirectory: The path to the directory where the server.js file is
• ExecStart: The path to the capabilities-enabled node binary + the server.js file
• User and Group: The user you want to run hohenheim as
• Environment: Your own environment variables

Finally, enable it:

sudo systemctl enable hohenheim.service

Using screen

Another interesting way to run hohenheim is to add screen. This will give you access to hohenheim through janeway:

[Unit]
Description=hohenheim

[Service]
Type=forking
User=skerit
Restart=always
ExecStart=/usr/bin/screen -d -m -S hohenheim -d -m /usr/local/bin/hohenode server.js
ExecStop=/usr/bin/killall -w -s 2 hohenheim
WorkingDirectory=/home/www-data/hohenheim/

[Install]
WantedBy=multi-user.target

Now, if you want to access the hohenheim shell, you can do:

screen -r hohenheim

Fail2ban Integration

Hohenheim can log suspicious domain lookups for fail2ban to block IPs that scan for non-existent subdomains (a common bot/attack pattern).

How It Works

1. Hohenheim tracks unique domain misses per IP using a time-windowed reputation system
2. Only IPs that hit multiple non-existent domains within a short time window are logged
3. Fail2ban monitors the log file and bans repeat offenders at the firewall level

This approach catches bots scanning for admin., test., dev., staging., etc. while ignoring legitimate users who occasionally mistype a URL.

Configuration Settings

Add these to your app/config/local.js to customize the behavior:

module.exports = {
    // ... other settings ...

    hohenheim: {
        // Enable/disable fail2ban logging (default: true)
        log_domain_misses: true,

        // Log file path (default: /var/log/hohenheim/domain-misses.log)
        domain_misses_log_path: '/var/log/hohenheim/domain-misses.log',

        // Only log after this many unique domain misses (default: 5)
        domain_misses_log_threshold: 5,

        // Time window in minutes for counting misses (default: 10)
        domain_misses_window_minutes: 10,
    },
};

Fail2ban Filter

Create /etc/fail2ban/filter.d/hohenheim.conf:

[Definition]
failregex = ^.*DOMAIN_MISS ip=<HOST> domain=.* path=.* user_agent=.*$
ignoreregex =

Fail2ban Jail

Create /etc/fail2ban/jail.d/hohenheim.conf:

[hohenheim]
enabled = true
filter = hohenheim
logpath = /var/log/hohenheim/domain-misses.log
maxretry = 10
findtime = 600
bantime = 3600

This configuration bans an IP for 1 hour if it triggers 10+ log entries within 10 minutes. Since Hohenheim already filters for suspicious behavior (5+ unique domains in 10 minutes), these are confirmed scanners.

Logrotate

Create /etc/logrotate.d/hohenheim:

/var/log/hohenheim/domain-misses.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    copytruncate
}

Log Format

Each log entry follows this format:

2026-01-25T14:30:45.123Z DOMAIN_MISS ip=192.168.1.100 domain=unknown.example.com path=/some/path user_agent="Mozilla/5.0 ..."

Node versions

You can configure your websites to use a specific node.js version, these versions are available:

• The system node binary (which node result)
• The binary /usr/bin/node if available
• The binary /usr/local/bin/node if available
• All global installed versions through the n module

If a configured version is not found, the system node binary will be used.

Thanks

Many thanks go out to Félix "passcod" Saparelli who allowed me to use the hohenheim package name on npm.