Humphrey is a very fast, robust and flexible HTTP/1.1 web server, with support for static and dynamic content through its plugin system. It has no dependencies when only using default features, and is easily extensible with a configuration file and dynamically-loaded plugins.
To install the binary, run cargo install humphrey_server and it will be automatically downloaded, compiled and added to your path as humphrey. Alternatively, you can find precompiled binaries from the latest GitHub release.
The Humphrey executable is run with a maximum of one argument, which specifies the path to the configuration file (defaulting to humphrey.conf in the current directory). The configuration file is where all configuration for Humphrey and any plugins is stored. The syntax is similar to Nginx, with comments starting with a #. Below is an example of a configuration file with every supported field specified. Unless specified otherwise, all fields are optional.
```conf server { address "0.0.0.0" # Address to host the server on port 80 # Port to host the server on threads 32 # Number of threads to use for the server websocket "localhost:1234" # Where to proxy WebSocket connections to
blacklist { file "conf/blacklist.txt" # Text file containing blacklisted addresses, one per line mode "block" # Method of enforcing the blacklist, "block" or "forbidden" (which returns 403 Forbidden) }
log { level "info" # Log level, from most logging to least logging: "debug", "info", "warn", "error" console true # Whether to log to the console file "humphrey.log" # Filename to log to }
cache { size 128M # Size limit of the cache time 60 # Max time to cache files for, in seconds }
route /proxy/* { proxy "127.0.0.1:8000,127.0.0.1:8080" # Comma-separated proxy targets loadbalancermode "round-robin" # Load balancing mode, either "round-robin" or "random" }
route /* { directory "/var/www" # Serve static content from this directory } } ```
To use Humphrey with PHP, compile the PHP plugin in the plugins folder and add the path to the output file to your plugin configuration (also available precompiled in the GitHub releases). You'll need Humphrey installed with plugins enabled (using cargo install humphrey_server --features plugins) and you'll also need PHP-CGI or PHP-FPM. Start the PHP server first, and specify its address in the Humphrey configuration file as specified below. Ensure your PHP configuration allows for multithreading if you set more than one thread in the configuration. Finally, you can start Humphrey in the normal way and it will work with PHP.
Add the following in the server section of your configuration file:
conf
plugins {
php {
library "plugins/php/target/release/php.dll" # Path to compiled library, `.dll` on Windows and `.so` on Linux
address "127.0.0.1" # Address to connect to the PHP-CGI interpreter
port 9000 # Port of the interpreter
threads 8 # Number of threads to connect to the interpreter with
}
}
Note: by default, the PHP interpreter is single-threaded, so don't increase the threads in the configuration unless you also change the PHP-CGI configuration.
To create a plugin, take a look at the plugin example. In short, you need to create a library crate with type cdylib to compile to a DLL, then implement the humphrey_server::plugins::plugin::Plugin trait for a struct and declare it with the declare_plugin! macro.