Skip to content

Commit eb8e95f

Browse files
gkalpakAndrewKushnir
authored andcommitted
docs(docs-infra): add instructions on using Let's Encrypt for preview server certificates (angular#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 angular#47250
1 parent 8fa33ed commit eb8e95f

File tree

3 files changed

+85
-0
lines changed

3 files changed

+85
-0
lines changed

aio/aio-builds-setup/docs/_TOC.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,4 +30,5 @@
3030

3131
## Miscellaneous
3232
- [Debug docker container](misc--debug-docker-container.md)
33+
- [Use Let's Encrypt certificates](misc--use-lets-encrypt-certs.md)
3334
- [Integrate with CI](misc--integrate-with-ci.md)
Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Miscellaneous - Use Let's Encrypt TLS certificates
2+
3+
4+
[Let's Encrypt](https://letsencrypt.org/) is a free, automated, and open certificate authority (CA),
5+
provided by the [Internet Security Research Group (ISRG)](https://www.abetterinternet.org/). It can
6+
be used for issuing the certificates needed by the preview server. See the "Create TLS certificates"
7+
section in [this doc](vm-setup--create-host-dirs-and-files.md) for more details.
8+
9+
Let's Encrypt supports issuing
10+
[wildcard certificates](https://letsencrypt.org/docs/faq/#does-let-s-encrypt-issue-wildcard-certificates),
11+
but they have to be renewed every 3 months using a
12+
[DNS-01 challenge](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge).
13+
14+
Below are instructions for the creation of certificates using Let's Encrypt.
15+
16+
**Note 1:**
17+
It is assumed that the commands are executed on the VM that hosts the preview server. You can run
18+
the commands on any machine and adjust accordingly the steps for transfering the generated
19+
certificate and private key to the preview server VM.
20+
21+
**Note 2:**
22+
In order to complete the DNS-01 challenge and generate the certificate, one needs to have access
23+
to update the DNS records associated with the `ngbuilds.io` domain and subdomains.
24+
25+
26+
## Prerequisites
27+
- Install [certbot](https://certbot.eff.org/):
28+
- Old method: `sudo apt-get install certbot`
29+
- New method: Follow the instructions [here](https://certbot.eff.org/instructions).
30+
31+
32+
## Create new certificate
33+
- Run the following command and follow the on-screen instructions:
34+
```sh
35+
sudo certbot certonly \
36+
-d "ngbuilds.io,*.ngbuilds.io" \
37+
-m "devops@angular.io" \
38+
--agree-tos \
39+
--manual \
40+
--manual-public-ip-logging-ok \
41+
--preferred-challenges="dns"
42+
```
43+
44+
**Hint:**
45+
You can use `dig -t txt _acme-challenge.ngbuilds.io` (on Linux/macOS) or something like
46+
[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.
47+
48+
- [Optional] Remove the DNS TXT records added in the previous step.
49+
(They are no longer needed, unless you want to create more certificates now.)
50+
51+
52+
## Deploy new certificate
53+
- Copy files to the host machine's `/etc/ssl/localcerts` directory, replacing `YYYY-MM` in the file
54+
names with the current year and month (for example, `2022-08`):
55+
```sh
56+
# Copy certificate.
57+
sudo cp /etc/letsencrypt/live/ngbuilds.io/fullchain.pem /etc/ssl/localcerts/ngbuilds.io.crt.YYYY-MM
58+
sudo cp /etc/letsencrypt/live/ngbuilds.io/fullchain.pem /etc/ssl/localcerts/ngbuilds.io.crt
59+
60+
# Copy private key.
61+
sudo cp /etc/letsencrypt/live/ngbuilds.io/privkey.pem /etc/ssl/localcerts/ngbuilds.io.key.YYYY-MM
62+
sudo cp /etc/letsencrypt/live/ngbuilds.io/privkey.pem /etc/ssl/localcerts/ngbuilds.io.key
63+
64+
# Update permissions.
65+
sudo find /etc/ssl/localcerts -type f -exec chmod 400 {} \;
66+
```
67+
68+
**Note:**
69+
The `.YYYY-MM`-suffixed copies are not needed/used. They are just kept for reference and backup
70+
purposes.
71+
72+
- Reload `nginx`:
73+
```sh
74+
# Connect to the Docker container and reload reload `nginx`.
75+
sudo docker exec -it aio service nginx reload
76+
```
77+
78+
- [Optional] Verify that the certificate has been successfully deployed by visiting
79+
https://ngbuilds.io/ in a browser and inspecting the TLS certificate details. See, for example,
80+
[how to view certificate details in Chrome](https://www.howtogeek.com/292076/how-do-you-view-ssl-certificate-details-in-google-chrome/).

aio/aio-builds-setup/docs/vm-setup--create-host-dirs-and-files.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,10 @@ specify the domain name see [here](vm-setup--create-docker-image.md).
3232
If no directory is attached, nginx will use an internal self-signed certificate. This is convenient
3333
during development, but is not suitable for production.
3434

35+
Certificates from any certificate authority can be used. As an example, see
36+
[here](misc--use-lets-encrypt-certs) for instructions on using certificates from
37+
[Let's Encrypt](https://letsencrypt.org/).
38+
3539
**Note:**
3640
Since nginx needs to be able to serve requests for both the main domain as well as any subdomain
3741
(e.g. `ngbuilds.io/` and `foo-bar.ngbuilds.io/`), the provided certificate needs to be a

0 commit comments

Comments
 (0)