Skip to content
Snippets Groups Projects
Verified Commit f580fb5c authored by Stan Hu's avatar Stan Hu
Browse files

Add docs for configuring encrypted SSL keys for Puma

This documents the Omnibus GitLab changes in
omnibus-gitlab!6932.

Relates to omnibus-gitlab#7799

Changelog: added
parent 1696422a
No related branches found
No related tags found
No related merge requests found
......@@ -211,6 +211,69 @@ make Prometheus scrape them over HTTPS, and support for it is being discussed
Hence, it is not technically possible to turn off this HTTP listener without
losing Prometheus metrics.
### Using an encrypted SSL key
> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7799) in GitLab 16.1.
Puma supports encrypted private SSL keys, which can be decrypted at
runtime. The following instructions illustrate how to configure this:
1. Encrypt the key with a password if it is not already:
```shell
openssl rsa -aes256 -in /path/to/ssl-key.pem -out /path/to/encrypted-ssl-key.pem
```
Enter in a password twice to write the encrypted file. In this
example, we'll use `some-password-here`.
1. Create a script or executable that will print the password. For
example, create a basic script in
`/var/opt/gitlab/gitlab-rails/etc/puma-ssl-key-password` that echoes
the password:
```shell
#!/bin/sh
echo some-password-here
```
Note that in production, you should avoid storing the password on
disk and use a secure mechanism for retrieving a password, such as
Vault. For example, the script might look like:
```shell
#!/bin/sh
export VAULT_ADDR=http://vault-password-distribution-point:8200
export VAULT_TOKEN=<some token>
echo "$(vault kv get -mount=secret puma-ssl-password)"
```
1. Ensure the Puma process has sufficient permissions to execute the script and read the encrypted key:
```shell
chown git:git /var/opt/gitlab/gitlab-rails/etc/puma-ssl-key-password
chmod 770 /var/opt/gitlab/gitlab-rails/etc/puma-ssl-key-password
chmod 660 /path/to/encrypted-ssl-key.pem
```
1. In `/etc/gitlab/gitlab.rb`, replace `puma['ssl_certificate_key']` with the encrypted key and specify
`puma['ssl_key_password_command]`:
```ruby
puma['ssl_certificate_key'] = '/path/to/encrypted-ssl-key.pem'
puma['ssl_key_password_command'] = '/var/opt/gitlab/gitlab-rails/etc/puma-ssl-key-password'
```
1. Reconfigure GitLab:
```shell
sudo gitlab-ctl reconfigure
```
1. If GitLab comes up successfully, you should be able to remove the
unencrypted SSL key that was stored on the GitLab instance.
## Switch from Unicorn to Puma
NOTE:
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment