> ## 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 pgw on a server

> Install the pgw binary on a Linux host, create its user, folders, master key, and bootstrap token, start it, and create the first tenant.

When you finish this page, pgw runs on a server as its own system user, starts at boot, and has its first tenant. If you haven't seen pgw work yet, run the [quickstart](https://docs.pgw.sipmicro.services/quickstart.md) first. It takes less time and needs nothing that this page sets up.

The install puts files in these places:

| Path | What it holds |
| - | - |
| `/usr/local/bin/pgw` | The binary. pgw is one file with no dependencies. |
| `/etc/pgw/` | The configuration file, the master key, and the bootstrap token. |
| `/var/lib/pgw/` | The database. This folder and the master key are what you back up. |

## Before you begin

* A 64-bit Linux host, amd64 or arm64, with systemd, a public IP address, and a DNS name, such as `pgw.example.com`.

* These ports open on the host:

  | Port | From | For |
  | - | - | - |
  | 5061/tcp | Apps | SIP over TLS |
  | 5060/udp, 5060/tcp | Your PBX | SIP |

* A PBX that the host can reach.

## Install pgw

**1. Download and check the binary**

Download the binary for your platform, such as `pgw-linux-amd64`, and the `SHA256SUMS` file from the [download page](https://pgw.sipmicro.services/#download). Then verify the checksum.

```bash theme={null}
sha256sum --check --ignore-missing SHA256SUMS
```

Each file that you downloaded shows `OK`.

**2. Install the binary**

```bash theme={null}
sudo install -m 755 pgw-linux-amd64 /usr/local/bin/pgw
pgw version
```

```text theme={null}
pgw v0.4.0 (9d1b63c)
```

**3. Create the user and folders**

pgw needs no root rights, so give it a system user of its own. That user owns the data folder and can read the configuration folder:

```bash theme={null}
sudo useradd --system --home /var/lib/pgw --shell /usr/sbin/nologin pgw
sudo install -d -o pgw -g pgw -m 700 /var/lib/pgw
sudo install -d -o root -g pgw -m 750 /etc/pgw
```

**4. Create the master key**

pgw encrypts the push credentials and SIP passwords in its database with the master key, 32 random bytes in base64. Anyone who has the key file and the database can read those secrets, so make the key file readable only by the `pgw` user:

```bash theme={null}
openssl rand -base64 32 | sudo tee /etc/pgw/master.key >/dev/null
sudo chown pgw:pgw /etc/pgw/master.key
sudo chmod 600 /etc/pgw/master.key
```

pgw doesn't start when the key file's group or other users have any access.

> [!WARNING]
>
> Back up the master key. Without it, pgw can't read the credentials that it stored.

**5. Create the bootstrap token**

The bootstrap token is the server's own password. It authorizes the few commands that belong to no tenant: creating the first tenant, reloading the certificate, and managing bans. It must have at least 32 characters:

```bash theme={null}
echo "PGW_BOOTSTRAP_TOKEN=$(openssl rand -base64 32)" | sudo tee /etc/pgw/bootstrap.env >/dev/null
sudo chmod 600 /etc/pgw/bootstrap.env
```

**6. Create the configuration file**

Besides the master key, pgw needs only its `hostname` to start. Create `/etc/pgw/config.yaml`, and set `hostname` to the DNS name that apps connect to:

```yaml theme={null}
hostname: pgw.example.com
data_dir: /var/lib/pgw
```

Without `tls_cert_file` and `tls_key_file`, pgw serves a self-signed certificate, which apps reject. You install a certificate after the first start.

**7. Start pgw**

Create the systemd unit and start pgw, as described in [Run pgw under systemd](https://docs.pgw.sipmicro.services/deploy/systemd.md#create-the-unit). Then run `journalctl -u pgw`. The log shows `serving a self-signed certificate, which apps reject`, and then `pgw ready` with the addresses that pgw listens on. Without `pgw ready`, the log's last line says why pgw didn't start.

**8. Check that pgw is ready**

```bash theme={null}
curl http://127.0.0.1:8080/readyz
```

```text theme={null}
ready
```

When a check fails, the status is `503` and the body names the failed check.

## Create the tenant

A tenant is your workspace in pgw, and every later command authenticates with its API key. `pgw bootstrap` creates the tenant and prints the key once. pgw stores only a hash of it, so you can't read it again. These commands put the key in `PGW_API_KEY` for this shell:

```bash theme={null}
export PGW_BOOTSTRAP_TOKEN="$(sudo sed -n 's/^PGW_BOOTSTRAP_TOKEN=//p' /etc/pgw/bootstrap.env)"
export PGW_API_KEY="$(pgw bootstrap --name example)"
```

Save the value of `PGW_API_KEY` somewhere safe before you close the shell.

`pgw bootstrap` works once. After a tenant exists, it fails:

```text theme={null}
pgw: POST /api/v1/bootstrap: 409 Conflict: already bootstrapped
```

## Next steps

> [card] [Install a TLS certificate](https://docs.pgw.sipmicro.services/deploy/tls.md)
>
> Replace the self-signed certificate, which apps reject.

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


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