Install The Gateway Server
This is the documentation of the legacy standalone Gateway Server. This server is deprecated and will be removed at some point. You should use the Caddy module instead.
The Vulcain Gateway Server can be put in front of any existing REST API to transform it in a Vulcain-enabled API. It works with hypermedia APIs (JSON-LD, JSON:API, HAL, Siren ...) as well as with other non-hypermedia APIs by configuring the server using a subset of the OpenAPI specification.
Tip: the easiest way to create a hypermedia API is to use the API Platform framework (by the same author than Vulcain).
First, download the archive corresponding to your operating system and architecture from the release page, extract the archive and open a shell in the resulting directory.
Note: Mac OS users must use the
mkdir tls openssl req -x509 -newkey rsa:4096 -keyout tls/key.pem -out tls/cert.pem -days 365
Then, on UNIX, run:
UPSTREAM='http://your-api' ADDR=':3000' KEY_FILE='tls/key.pem' CERT_FILE='tls/cert.pem' ./vulcain
On Windows, start PowerShell, go into the extracted directory and run:
$env:UPSTREAM='http://your-api'; $env:ADDR='localhost:3000'; $env:KEY_FILE='key.pem'; $env:CERT_FILE='cert.pem'; .\vulcain.exe
The Windows Defender Firewall will ask you if you want to allow
vulcain.exe to communicate through it. Allow it for both public and private networks. If you use an antivirus, or another firewall software, be sure to whitelist
The gateway is now available on
To run it in production mode, and generate automatically a Let's Encrypt TLS certificate, just run the following command as root:
UPSTREAM='http://your-api' ACME_HOSTS='example.com' ./vulcain
Using Windows in production is not recommended.
The value of the
ACME_HOSTS environment variable must be updated to match your domain name(s).
A Let's Encrypt TLS certificate will be automatically generated.
If you omit this variable, the server will be exposed using a not encrypted HTTP connection, so you will not be able to use Server Push.
To compile the development version and register the demo page, see CONTRIBUTING.
A Docker image is available on Docker Hub. The following command is enough to get a working server:
docker run \ -v /your/tls/certs:/tls \ -e UPSTREAM='http://your-api' -e KEY_FILE='tls/key.pem' -e CERT_FILE='tls/cert.pem' \ -p 443:443 \ dunglas/vulcain:legacy-latest
The gateway is available on
In production, run:
docker run \ -e UPSTREAM='http://your-api' -e ACME_HOSTS='example.com' \ -p 80:80 -p 443:443 \ dunglas/vulcain:legacy-latest
Be sure to update the value of
ACME_HOSTS to match your domain name(s), a Let's Encrypt TLS certificate will be automatically generated.