Set up the server

Run your own humble-server on Windows, Linux, macOS or in Docker.

humble-server is one self-contained program. The dashboard and the database are built in, so there is nothing else to install. It needs to be reachable by every computer that will use it, so give it a fixed address or a DNS name.

Try it in the foreground first

humble-server serve

Open http://localhost:8080. The first visit asks you to create the administrator account. Press Ctrl+C to stop it.

Install as a background service

The same command works on all three systems. Run it from an Administrator terminal on Windows, or with sudo on Linux and macOS:

humble-server service install --bind 0.0.0.0:8080 --public-url https://remote.example.com

It registers the service, starts it, and remembers the options you gave. To change an option, run service install again with the new options. To remove it, run humble-server service uninstall; your data is kept.

Windows

msiexec /i humble-server-windows-x86_64-<version>.msi PORT=8080 PUBLICURL=https://remote.example.com

The MSI installs and starts the service and opens the port in Windows Firewall. For HTTPS or other options, run humble-server service install with those options afterwards from an Administrator terminal.

Linux

The packages ship the service but do not start it:

sudo systemctl enable --now humble-server

To change options with the packaged service, run sudo systemctl edit humble-server and add lines such as:

[Service]
Environment=HUMBLE_BIND=0.0.0.0:443
Environment=HUMBLE_PUBLIC_URL=https://remote.example.com
Environment=HUMBLE_TLS_CERT=/etc/humble/cert.pem
Environment=HUMBLE_TLS_KEY=/etc/humble/key.pem

Without a package, copy the humble-server binary to /usr/local/bin and use sudo humble-server service install.

macOS

Open the .pkg. It installs /usr/local/bin/humble-server and starts the service on port 8080. Change options with sudo humble-server service install and the new options.

Docker

cd deploy
cp .env.example .env     # set HUMBLE_DOMAIN and HUMBLE_ADMIN_PASSWORD
mkdir -p dist
docker compose up -d

This starts the server behind Caddy, which obtains and renews an HTTPS certificate by itself. Point a DNS record at the host and open ports 80 and 443. The administrator account is created from the values in .env.

Create the first account

Use whichever is convenient:

• Open the dashboard. While no account exists, it asks you to create one: personal (just you) or organization (several people; see Accounts).
• From a terminal on the server: humble-server create-admin alice --password "a long passphrase"
• Set HUMBLE_ADMIN_USER and HUMBLE_ADMIN_PASSWORD before the first start. This is what the Docker setup does.

Run a public relay

A server on the internet can serve everyone: the Humble Support app (quick support, no account) and anyone who wants an account.

humble-server service install --public-url https://relay.example.com --open-signup --name "Humble Relay"

• --open-signup lets anyone create a personal or organization account.
• Quick support (--adhoc, on by default) gives Humble Support its IDs and lets anyone connect to such an ID with its password. Attempts are limited per address and per device.
• Announcements and ads in Humble Support come from promo.json in the promo folder (promo in the data folder, or --promo-dir). It is read on every request, so you can change it while the server runs. Images (PNG or JPEG) go in the same folder:

{"items": [
  {"title": "Humble Pro", "text": "Unattended access for your team.", "url": "https://example.com/pro", "image": "/promo/pro.png"}
]}

The Humble Support app and the full app use the public relay built into them, https://relay.humbleviewer.com (another one when building with HUMBLE_PUBLIC_RELAY); humble-support --relay <url> picks another one.

Sign in with Google or GitHub

People can sign up and sign in with a Google or GitHub account instead of a password. Their password stays with Google or GitHub; the server only learns who they are. Existing users keep their password and can add Google or GitHub under Account → Sign-in methods. In the desktop app, Sign in with a browser opens the server's page, so this works there too.

1. Google: in the Google Cloud console, set up the OAuth consent screen (external, scopes openid, email, profile), then create an OAuth client ID of type Web application with the authorized redirect URI https://relay.example.com/api/oauth/google/callback.
2. GitHub: under Settings → Developer settings → OAuth Apps, create an app with the authorization callback URL https://relay.example.com/api/oauth/github/callback, and generate a client secret.
3. Give the server the client IDs and secrets, as environment variables (a file only root can read, for example a systemd EnvironmentFile) rather than on the command line:

HUMBLE_GOOGLE_CLIENT_ID=1234-abc.apps.googleusercontent.com
HUMBLE_GOOGLE_CLIENT_SECRET=...
HUMBLE_GITHUB_CLIENT_ID=Ov23li...
HUMBLE_GITHUB_CLIENT_SECRET=...

The redirect address is built from --public-url, so set it. With --password-signup false, new accounts can only be made with Google or GitHub (the first account on a server can always be made with a password).

Use PostgreSQL

By default the server keeps everything in a SQLite file, humble.db in the data folder, which needs no setup. A bigger or hosted server can use PostgreSQL instead:

HUMBLE_DATABASE=postgres://humble:password@db.example.com:5432/humble

Give the server a database and a user of its own that owns it; the server creates and upgrades its tables. Characters such as #, $ or @ in the password must be written as %23, %24, %40 in the URL. Encrypt the connection (?sslmode=require) unless it goes over a private network.

To move an existing server to PostgreSQL, stop it and copy its database into the new, empty one, then start it with HUMBLE_DATABASE set:

HUMBLE_COPY_TO=postgres://humble:password@db.example.com/humble humble-server copy-database

server.key stays in the data folder whichever database you use.

Turn on HTTPS

People sign in to the dashboard with a password, so serve it over HTTPS whenever it is reachable from outside your own network. There are two ways.

Built in

Give the server a certificate and key in PEM format, for example from Let's Encrypt (certbot on Linux and macOS, win-acme on Windows) or your own certificate authority:

humble-server service install --bind 0.0.0.0:443 \
  --public-url https://remote.example.com \
  --tls-cert /path/to/fullchain.pem --tls-key /path/to/privkey.pem

The files are read when the server starts. After renewing a certificate, restart the service.

Self-signed, for a server of your own

Without a domain name you can still keep passwords off the network in clear text. --self-signed makes a certificate on first start (kept in tls in the data folder, for localhost, the computer's name and address, and the host of --public-url) and serves HTTPS with it:

humble-server service install --bind 0.0.0.0:443 --self-signed --http-bind 0.0.0.0:8080 \
  --public-url http://192.168.1.10:8080

Browsers warn once that they do not know the certificate. Compare the SHA-256 fingerprint the server logs at start with the one the browser shows, then accept it. The Humble app does the same: the first time it reaches the server (signing in, getting an ID, adding a computer) it shows the fingerprint and asks whether to trust it, and from then on accepts that certificate, and only that one, for this server. On the command line, humble login prints the fingerprint and takes it with --trust-certificate.

--http-bind is optional: it keeps plain HTTP on port 8080 next to HTTPS, for older Humble versions or for installers made with an http:// --public-url. Use it only on a network you trust. With a real certificate, use HTTPS everywhere.

Behind a reverse proxy

Let Caddy, nginx or IIS handle HTTPS and pass requests to the server on port 8080. Add --trust-proxy so the server reads the visitor's real address from the proxy, and keep port 8080 closed to the outside. The proxy must pass WebSocket connections through; Caddy does this by default. A complete Caddy configuration is one line:

remote.example.com {
    reverse_proxy localhost:8080
}

Set the public address

--public-url is the address other computers use to reach the server. It is written into every installer the server generates, so set it to the address that works from outside, including https://. If you leave it out, the server uses whatever address the administrator's browser used, which is fine on a single network and wrong behind a proxy.

Enable installer generation

To produce installers, the server needs copies of the desktop app. Put these files in the dist folder inside the data folder (or point --dist-dir somewhere else):

The release workflow publishes them together as humble-dist.tar.gz. Without them the dashboard still works; only the installer downloads fail.

Options

Every option can be given on the command line or as an environment variable.

Back up, move and upgrade

• Back up the whole data folder while the service is stopped. It holds humble.db (accounts, devices, groups, audit log) and server.key. With PostgreSQL, back up the database with pg_dump and the data folder for server.key.
• Keep server.key safe and keep it with the database. Every enrolled device remembers this key and refuses to talk to a server that presents a different one. If you lose it, every device must be enrolled again.
• Move to another machine by copying the data folder and keeping the same public address.
• Upgrade by installing the newer package, or by replacing the binary and restarting the service.
• Locked out? humble-server reset-password alice --password "new passphrase" sets a new password and turns off that user's two-factor sign-in.