> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pgw.sipmicro.services/llms.txt
> Use this file to discover all available pages before exploring further.

# Install a TLS certificate

> Give pgw's app listener a certificate from a public certificate authority, reload it without dropping apps, and watch its expiry.

A new pgw serves a certificate that it signed itself, so that it can start without any setup. Apps reject that certificate, because nothing on the phone trusts it. When you finish this page, pgw serves a certificate from Let's Encrypt for `pgw.example.com`, and loads each renewed certificate without dropping a connection.

pgw doesn't get certificates itself. It reads a certificate and a key from two files that you name in `tls_cert_file` and `tls_key_file`, so any certificate authority and any renewal tool work. This page uses certbot.

## Before you begin

* certbot on the host.
* Port 80/tcp open to the internet while certbot runs, for its standalone mode.

## Get and install the certificate

**1. Get the certificate**

```bash theme={null}
sudo certbot certonly --standalone -d pgw.example.com
```

**2. Create the renewal hook**

certbot keeps its files readable by root only, and pgw runs as the `pgw` user. So a hook copies each new certificate to a folder that pgw can read, and tells pgw to load it. Create `/etc/letsencrypt/renewal-hooks/deploy/pgw.sh`:

```bash theme={null}
#!/bin/sh
install -d -o root -g pgw -m 750 /etc/pgw/tls
install -o root -g pgw -m 640 /etc/letsencrypt/live/pgw.example.com/fullchain.pem /etc/pgw/tls/fullchain.pem
install -o root -g pgw -m 640 /etc/letsencrypt/live/pgw.example.com/privkey.pem /etc/pgw/tls/privkey.pem
systemctl reload-or-restart pgw
```

**3. Run the hook once**

certbot runs the hook only after a renewal, so run it once now to copy the first certificate:

```bash theme={null}
sudo chmod 755 /etc/letsencrypt/renewal-hooks/deploy/pgw.sh
sudo /etc/letsencrypt/renewal-hooks/deploy/pgw.sh
```

**4. Point pgw at the files**

Add these lines to `/etc/pgw/config.yaml`:

```yaml theme={null}
tls_cert_file: /etc/pgw/tls/fullchain.pem
tls_key_file: /etc/pgw/tls/privkey.pem
```

**5. Restart pgw**

pgw reads the two settings only at startup, so this one time it needs a restart:

```bash theme={null}
sudo systemctl restart pgw
```

pgw doesn't start when a named file is missing or isn't a valid certificate and key. Run `journalctl -u pgw` to see why.

From now on, certbot runs the hook after each renewal, and pgw loads the new certificate without closing any app connection.

## Check that it works

```bash theme={null}
openssl s_client -connect pgw.example.com:5061 -servername pgw.example.com </dev/null 2>/dev/null | openssl x509 -noout -issuer -enddate
```

The issuer is Let's Encrypt. The self-signed certificate shows `pgw` as its issuer. The log no longer shows `serving a self-signed certificate`.

## Reload the certificate

The hook reloads pgw for you. To reload by hand, after you replace the files yourself, use one of the methods in the table. A reload reads the certificate and key files again. New connections get the new certificate, and open connections stay. When the files aren't a valid pair, pgw keeps the old certificate and logs `certificate not reloaded; the old one stays`.

| Method | Notes |
| - | - |
| `sudo systemctl reload pgw` | Sends `SIGHUP` through the unit's `ExecReload`. |
| `pgw cert reload` | Needs `PGW_BOOTSTRAP_TOKEN`, or `--token`. Prints the new expiry. |
| `POST /api/v1/tls/reload` | Send `Authorization: Bootstrap <token>` with the bootstrap token. Returns `200` with `not_after`, `422` when the files aren't a valid pair, `401` for a missing or wrong token, and `403` when pgw runs without a bootstrap token. |

```bash theme={null}
pgw cert reload
```

```text theme={null}
certificate reloaded; it expires at 2027-11-15T23:53:19Z
```

With the API:

```bash theme={null}
curl -X POST -H "Authorization: Bootstrap $PGW_BOOTSTRAP_TOKEN" http://127.0.0.1:8080/api/v1/tls/reload
```

```text theme={null}
{"not_after":"2027-11-15T23:53:19Z"}
```

## Watch the expiry

The metric `pgw_tls_cert_not_after_timestamp_seconds` is when the served certificate expires, in Unix seconds. pgw sets it at startup and after each reload. Alert when it's less than 14 days away:

```text theme={null}
pgw_tls_cert_not_after_timestamp_seconds - time() < 14 * 86400
```

## Next steps

> [card] [Configure apps for pgw](https://docs.pgw.sipmicro.services/apps/overview.md)
>
> Register your app's push credentials, now that apps can connect.

> [card] [Alerts](https://docs.pgw.sipmicro.services/alerts.md)
>
> Add the certificate expiry rule to your other pgw alerts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.