Skip to content

Commit

Permalink
docs(docs-infra): add instructions on using Let's Encrypt for preview…
Browse files Browse the repository at this point in the history
… server certificates (#47250)

Add a new doc with instructions on how to use TLS certificates issues by
[Let's Encrypt][1] in the PR preview server.

[1]: https://letsencrypt.org/

PR Close #47250
  • Loading branch information
gkalpak authored and AndrewKushnir committed Sep 6, 2022
1 parent 6ef1d37 commit ee8a3a2
Show file tree
Hide file tree
Showing 3 changed files with 85 additions and 0 deletions.
1 change: 1 addition & 0 deletions aio/aio-builds-setup/docs/_TOC.md
Expand Up @@ -30,4 +30,5 @@

## Miscellaneous
- [Debug docker container](misc--debug-docker-container.md)
- [Use Let's Encrypt certificates](misc--use-lets-encrypt-certs.md)
- [Integrate with CI](misc--integrate-with-ci.md)
80 changes: 80 additions & 0 deletions aio/aio-builds-setup/docs/misc--use-lets-encrypt-certs.md
@@ -0,0 +1,80 @@
# Miscellaneous - Use Let's Encrypt TLS certificates


[Let's Encrypt](https://letsencrypt.org/) is a free, automated, and open certificate authority (CA),
provided by the [Internet Security Research Group (ISRG)](https://www.abetterinternet.org/). It can
be used for issuing the certificates needed by the preview server. See the "Create TLS certificates"
section in [this doc](vm-setup--create-host-dirs-and-files.md) for more details.

Let's Encrypt supports issuing
[wildcard certificates](https://letsencrypt.org/docs/faq/#does-let-s-encrypt-issue-wildcard-certificates),
but they have to be renewed every 3 months using a
[DNS-01 challenge](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge).

Below are instructions for the creation of certificates using Let's Encrypt.

**Note 1:**
It is assumed that the commands are executed on the VM that hosts the preview server. You can run
the commands on any machine and adjust accordingly the steps for transfering the generated
certificate and private key to the preview server VM.

**Note 2:**
In order to complete the DNS-01 challenge and generate the certificate, one needs to have access
to update the DNS records associated with the `ngbuilds.io` domain and subdomains.


## Prerequisites
- Install [certbot](https://certbot.eff.org/):
- Old method: `sudo apt-get install certbot`
- New method: Follow the instructions [here](https://certbot.eff.org/instructions).


## Create new certificate
- Run the following command and follow the on-screen instructions:
```sh
sudo certbot certonly \
-d "ngbuilds.io,*.ngbuilds.io" \
-m "devops@angular.io" \
--agree-tos \
--manual \
--manual-public-ip-logging-ok \
--preferred-challenges="dns"
```

**Hint:**
You can use `dig -t txt _acme-challenge.ngbuilds.io` (on Linux/macOS) or something like
[DNSChecker.org](https://dnschecker.org/all-dns-records-of-domain.php?query=_acme-challenge.ngbuilds.io&rtype=TXT) to verify that the DNS updates have been successfully deployed and propagated.

- [Optional] Remove the DNS TXT records added in the previous step.
(They are no longer needed, unless you want to create more certificates now.)


## Deploy new certificate
- Copy files to the host machine's `/etc/ssl/localcerts` directory, replacing `YYYY-MM` in the file
names with the current year and month (for example, `2022-08`):
```sh
# Copy certificate.
sudo cp /etc/letsencrypt/live/ngbuilds.io/fullchain.pem /etc/ssl/localcerts/ngbuilds.io.crt.YYYY-MM
sudo cp /etc/letsencrypt/live/ngbuilds.io/fullchain.pem /etc/ssl/localcerts/ngbuilds.io.crt

# Copy private key.
sudo cp /etc/letsencrypt/live/ngbuilds.io/privkey.pem /etc/ssl/localcerts/ngbuilds.io.key.YYYY-MM
sudo cp /etc/letsencrypt/live/ngbuilds.io/privkey.pem /etc/ssl/localcerts/ngbuilds.io.key

# Update permissions.
sudo find /etc/ssl/localcerts -type f -exec chmod 400 {} \;
```

**Note:**
The `.YYYY-MM`-suffixed copies are not needed/used. They are just kept for reference and backup
purposes.

- Reload `nginx`:
```sh
# Connect to the Docker container and reload reload `nginx`.
sudo docker exec -it aio service nginx reload
```

- [Optional] Verify that the certificate has been successfully deployed by visiting
https://ngbuilds.io/ in a browser and inspecting the TLS certificate details. See, for example,
[how to view certificate details in Chrome](https://www.howtogeek.com/292076/how-do-you-view-ssl-certificate-details-in-google-chrome/).
Expand Up @@ -32,6 +32,10 @@ specify the domain name see [here](vm-setup--create-docker-image.md).
If no directory is attached, nginx will use an internal self-signed certificate. This is convenient
during development, but is not suitable for production.

Certificates from any certificate authority can be used. As an example, see
[here](misc--use-lets-encrypt-certs) for instructions on using certificates from
[Let's Encrypt](https://letsencrypt.org/).

**Note:**
Since nginx needs to be able to serve requests for both the main domain as well as any subdomain
(e.g. `ngbuilds.io/` and `foo-bar.ngbuilds.io/`), the provided certificate needs to be a
Expand Down

0 comments on commit ee8a3a2

Please sign in to comment.