Important!
Right after the installation of the Apiary Platform WebUI is available only on HTTP.
You can configure SSL by one of the following methods:
Upload SSL certificates in the PEM format to the directory /opt/hw-fh/fssl
.
Please note that uploaded files will not be overwritten when upgrading to the next version, so feel free to store them in this directory.
You can change default directory if it does not suit you:
/opt/hw-fh/config/user.ini
(root privileges required);Add the f.ssl.dir
option to the [main]
section and indicate new path:
[main]
f.ssl.dir = /my/certs/dir
To apply changes, run the command:
/opt/hw-fh/bin/reconfig
To configure HTTP to HTTPs redirect add the following options to the [main]
section of /opt/hw-fh/config/user.ini
file (root privileges required):
[main]
f.ssl.enabled = ssl_redirect
f.deck.ip.expose = 0.0.0.0
f.deck.port.expose = 80
f.deck.https.ip.expose = 0.0.0.0
f.deck.https.port.expose = 443
where,
f.ssl.enabled
- option, which enables SSL. Possible values:
no_ssl
- only insecure HTTP-connection is used (default value);ssl_both
- both insecure HTTP-connection and secure HTTPs-connection are used;ssl_redirect
- redirection from insecure connection HTTP-connection to secure HTTPs-connection;ssl_only
- only secure HTTPs-connection is used.f.deck.ip.expose
- IP address for insecure HTTP-connection (0.0.0.0
- public IP address, 127.0.0.1
- local IP address).
Required for no_ssl
, ssl_both
and ssl_redirect
.
f.deck.port.expose
- Port number for insecure HTTP-connection (default value - 80).
Required for no_ssl
, ssl_both
and ssl_redirect
.f.deck.https.ip.expose
- IP address for secure HTTPs-connection (0.0.0.0
- public IP address, 127.0.0.1
- local IP address).
Required for ssl_only
, ssl_both
and ssl_redirect
.f.deck.https.port.expose
- Port number for secure HTTPs-connection.
Required for ssl_only
, ssl_both
and ssl_redirect
.To apply changes, run the command:
/opt/hw-fh/bin/reconfig
If necessary, you can run Apiary behind your own reverse proxy.
For example, configure nginx
, which will proxy all requests for Apiary.
To use your proxy server on the same machine, change the following parameters in /opt/hw-fh/config/user.ini
:
[main]
f.ssl.enabled = no_ssl
f.deck.ip.expose = 127.0.0.0
f.deck.port.expose = 10002
To apply changes, run the command (root privileges required):
/opt/hw-fh/bin/reconfig
Example of nginx
configuration:
server {
server_name yourapiary.example.com;
access_log /var/log/nginx/yourapiary.example.com-access.log full_log;
error_log /var/log/nginx/yourapiary.example.com-error.log;
client_max_body_size 0;
location / {
proxy_pass http://localhost:10002;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
}
listen 443 ssl;
ssl_certificate /path/to-your/certs/fullchain.pem;
ssl_certificate_key /path/to-your/certs/privkey.pem;
}
server {
if ($host = yourapiary.example.com) {
return 301 https://$host$request_uri;
}
listen 80;
server_name yourapiary.example.com;
return 404;
}
where,
10002
- port number you set to f.deck.port.expose
in user.ini
;yourapiary.example.com
- hostname or IP address of your virtual machine.Example of Let's Encrypt
with certbot
configuration. You should set this configuration before you issue certificates using certbot
.
server {
listen 80;
server_name yourapiary.example.com;
access_log /var/log/nginx/yourapiary.example.com-access.log full_log;
error_log /var/log/nginx/yourapiary.example.com-error.log;
client_max_body_size 0;
location / {
proxy_pass http://localhost:10002;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
}
}
where,
10002
- port number you set to f.deck.port.expose
in user.ini
file;yourapiary.example.com
- hostname or IP address of your virtual machine.After installation, RabbitMQ by default is started on an insecure port 5672
.
You can use this port, for example, if Apiary and Hive platforms are installed in a secured local network.
For production environment we recommend using secure connection and setting up 5671
port instead of port 5672
.
To do it, you can use the same SSL certificate as for HTTPs in WebUI.
You can upload ready SSL certificates in the PEM format to the directory /opt/hw-fh/qssl
and configure RabbitMQ:
/opt/hw-fh/config/user.ini
(root privileges required);Add the following options to the [main]
section:
[main]
q.ssl.enabled = ssl_only
rmq.ip.ssl.expose = 0.0.0.0
rmq.port.ssl.expose = 5671
rmq.client.host = my.apiary.host.com
rmq.client.port = 5671
where,
q.ssl.enabled
- option, which enables SSL. Possible values:
no_ssl
- only insecure TCP-connection is used (set by default);ssl_both
- both insecure and secure TCP-connections are used (use this option only if you know why you need both types of TCP-connections);ssl_only
- only secure TCP-connection is used (is recommended for production).rmq.port.expose
- Port for insecure TCP-connection;
rmq.ip.expose
- IP address for insecure TCP-connection;rmq.port.ssl.expose
- Port for secure TCP-connection;rmq.ip.ssl.expose
- IP address for secure TCP-connection;rmq.client.host option
- Apiary IP address or hostname;rmq.client.port
- Apiary port number (5671
or 5672
);If you are using a self-signed certificate for a secure connection or certificate issued by organization's CA, basically any non-global SSL certificate — you need to share these root certificates with Apiary and Hive.
See option custom.root.certs.path
for Apiary and Hive in /opt/hw-fh/config/user-template.ini
.
You may need to convert CA from .pfx
if:
* it is necessary to transfer issues between Apiary and Hive via secure channel;
* it is impossible to use global valid certificates;
* it is necessary to use local Certificate Authority to issue certificates.
Create SSL key:
openssl pkcs12 -in your_file.pfx -nocerts -nodes -out key.pem
Create SSL certificate:
openssl pkcs12 -in your_file.pfx -clcerts -nokeys -out domain.pem
Note: remove the
-out
option from the commands and the key with other information will be displayed on the screen. In this case, copy everything from the linesBEGIN PRIVATE KEY / BEGIN CERTIFICATE
toEND PRIVATE KEY / END CERTIFICATE
and save it to a file.
Create a root certificate:
openssl pkcs12 -in your_file.pfx -cacerts -nokeys -chain -out ca.pem
Note: you will get a chain of root certificates. You will need only last one certificate in this chain. For example, you can open file for editing and delete everything except the last one.
Concatenate files into one certificate:
cat domain.pem ca.pem > cert.pem
Copy SSL certificates to a virtual machine with installed Platform to a directory with SSL certificates:
cp cert.pem /opt/hw-fh/ssl/
cp key.pem /opt/hw-fh/ssl/
Copy root certificate to a Platform directory with root certificates:
cp ca.pem /opt/certs
Note: in this case, it is necessary to specify path to directory with root certificates in
/opt/hw-fh/config/user.ini
filecustom.root.certs.path = /opt/certs
.
Restart the Platform (systemctl restart hw-fh
) or do /opt/hw-fh/bin/reconfig
if you have changed the /opt/hw-fh/config/user.ini
file.