Run locally

Running Hydrui locally is fairly straight-forward. The first thing you need to do is download the appropriate executable binary files for your platform. Then, you can simply run the executable file. This will give you a basic Hydrui server in client-only mode (same as the hosted service).

Download the appropriate binary

Each platform supported by Hydrui has a corresponding set of binaries.

Go to the latest release, and you will see binaries for each supported system.

Latest Release

If your system is not listed, it may still be possible to compile from source.

Run binary

Windows

Under Windows, you can just double click the application. A rudimentary user interface is provided, and you should see an icon appear in your system tray. If you want Hydrui to run at startup, you could put it in your Startup folder.

Click the icon to open up Hydrui configuration. By default, Hydrui Server operates in client-only mode, since server mode requires some configuration; you can do that configuration in the UI.

Note that the UI currently does not have a way to edit the default log-in username/password. For now, you can generate an htpasswd file using the online htpasswd editor.

Other platforms

Under Linux, macOS, FreeBSD and other platforms, the primary interface is the CLI for now.

After extracting the program, mark it executable.

$ unzip hydrui-linux-amd64.zip
$ chmod +x ./hydrui-linux-amd64

Run the program from a terminal. For example:

$ ./hydrui-linux-amd64

This will run Hydrui in client-only mode. To run in server mode, you need to supply the relevant flags:

$ ./hydrui-linux-amd64 -server-mode -hydrus-api-key=xxx -hydrus-url=http://localhost:45869

Note that this will default to an insecure setup where the username and password is admin. You can supply an htpasswd file with the -htpasswd flag. For more information on what flags you can use, try passing -help.

It is also possible to run the Windows version of Hydrui Server under Wine, if you wish. Win32 is the true universal ABI, after all. Just note that the UI is a bit uglier than it even normally is when running under Wine.

htpasswd setup

When running in server mode, you can use the online htpasswd editor to make an htpasswd file, or you can use the htpasswd tool from the Apache httpd server package. Please note that Hydrui Server currently only supports Bcrypt password hashes in htpasswd files. You could create a new htpasswd file using the Apache httpd htpasswd tool like this:

$ htpasswd -B -c htpasswd.txt test
Enter password:
Re-type new password:
Adding password for user test
$

This will create a new htpasswd.txt file with one user, test, with the password you enter at the prompt.

Health checking

By default, the Hydrui server does not expose a health checking endpoint, but the -listen-internal or -socket-internal option will expose a plaintext HTTP server over TCP or UNIX domain sockets respectively that includes a health checking endpoint at /healthz. The health check endpoint is intended to be used with platforms like Docker and Kubernetes, allowing them to determine if the server is functioning properly. It returns the HTTP code 200 and the text "OK" when it succeeds, otherwise it will return a 5xx error with a single-line string error. For example:

$ ./hydrui-linux-amd64 -listen :8080 -listen-internal :5050 &
$ curl http://localhost:8080/healthz
404 page not found
$ curl http://localhost:5050/healthz
OK

When using server mode, it is possible to query for the hydrus client status by appending ?check_hydrus to the URL. This will verify that the hydrus client API is accessible and that the API key is valid. Since this round-trips the hydrus client API, you may want to have a more lax timeout and longer interval for this check.

$ curl http://localhost:5050/healthz\?check_hydrus
Hydrus API returned failure: Did not find an entry for that access key!

Options reference