Hipache is a distributed proxy designed to route high volumes of http and websocket traffic to unusually large numbers of virtual hosts, in a highly dynamic topology where backends are added and removed several times per second. It is particularly well-suited for PaaS (platform-as-a-service) and other environments that are both business-critical and multi-tenant.
Hipache was originally developed at dotCloud, a popular platform-as-a-service, to replace its first-generation routing layer based on a heavily instrumented nginx deployment. It currently serves production traffic for tens of thousands of applications hosted on dotCloud. Hipache is based on the node-http-proxy library.
From the shell:
$ npm install hipache -g
The '-g' option will make the 'hipache' bin-script available system-wide (usually linked from '/usr/local/bin')
dotCloud proxy2 uses a Redis server to manage its configuration (and to share its state across the multiple workers). You can use the Redis server to change its configuration while it's running or simply check the health state of a backend.
{
"server": {
"accessLog": "/var/log/hipache_access.log",
"port": 80,
"workers": 5,
"maxSockets": 100,
"deadBackendTTL": 30,
"address": ["127.0.0.1"],
"address6": ["::1"],
"https": {
"port": 443,
"key": "/etc/ssl/ssl.key",
"cert": "/etc/ssl/ssl.crt"
}
},
"redisHost": "127.0.0.1",
"redisPort": 6379,
"redisDatabase": 0,
"redisPassword": "password"
}
- server.accessLog: location of the Access logs, the format is the same as nginx
- server.port: Port to listen to (HTTP)
- server.workers: Number of workers to be spawned (specify at least 1, the master process does not serve any request)
- server.maxSockets: The maximum number of sockets which can be opened on each backend (per worker)
- server.deadBackendTTL: The number of seconds a backend is flagged as `dead' before retrying to proxy another request to it
- server.address: IPv4 Addresses listening (HTTP and HTTPS)
- server.address6: IPv6 Addresses listening (HTTP and HTTPS)
- server.https: SSL configuration (omit this section to disable HTTPS)
- redisHost and redisPort: Redis configuration (you can omit those parameters to use the local redis on the default port)
- redisDatabase: Redis number database (default 0)
- redisPassword: Redis password (you can omit this if Redis doesn't require auth)
- redisMasterHost and redisMasterPort: Send redis write commands to master redis and other commands to redisHost/redisPort conf (assuming it could be a redis slave). You can omit this if Redis is not configured with master/slave arch)
- redisMasterPassword: Redis master pasword (you can omit this if Redis doesn't require auth and if you're not using multi-redis arch)
From the shell:
$ hipache
Or if you use the port 80:
$ sudo hipache
Or by specifying your configuration file:
$ hipache --config config.json
Managing multiple configuration files:
The default configuration file is config.json. It's possible to have
different configuration files named config_<suffix>.json. The suffix is got
from an environment variable called SETTINGS_FLAVOR.
For instance, here is how to spawn the server with the config_test.json
configuration file in order to run the tests.
$ SETTINGS_FLAVOR=test hipache
All the configuration is managed through Redis. This makes it possible to update the configuration dynamically and gracefully while the server is running.
It also makes it simple to write configuration adapters. It would be trivial to load a plain text configuration file into Redis (and update it at runtime).
Different configuration adapters will follow, but for the moment you have to provision the Redis manually.
Let's take an example, I want to proxify requests to 2 backends for the hostname www.dotcloud.com. The 2 backends IP are 192.168.0.42 and 192.168.0.43 and they serve the HTTP traffic on the port 80.
redis-cli is the standard client tool to talk to Redis from the terminal.
Here are the steps I will follow:
-
Create the frontend and associate an identifier
$ redis-cli rpush frontend:www.dotcloud.com mywebsite (integer) 1
The frontend identifer is mywebsite, it could be anything.
-
Associate the 2 backends
$ redis-cli rpush frontend:www.dotcloud.com http://192.168.0.42:80 (integer) 2 $ redis-cli rpush frontend:www.dotcloud.com http://192.168.0.43:80 (integer) 3 -
Review the configuration
$ redis-cli lrange frontend:www.dotcloud.com 0 -1 1) "mywebsite" 2) "http://192.168.0.42:80" 3) "http://192.168.0.43:80"
While the server is running, any of these steps can be re-run without messing up with the traffic.
Upstart
Copy upstart.conf to /etc/init/hipache.conf.
Then you can use:
< 8000 div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="start hipache stop hipache restart hipache">start hipache
stop hipache
restart hipache