> ## 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.

# Keep a tenant in a file

> Describe your apps, upstreams, and users in one YAML file, preview each change, and apply it in one step.

Changes made one command at a time are hard to review and hard to repeat. Changes that you make one command at a time are hard to review and hard to repeat. A tenant file puts your tenant's apps, upstreams, and managed mode users in one file. You edit the file, pgw shows you what would change, and you apply it. Because the file holds no secrets, you can keep it in git and set up a second install from it.

## How a sync works

`pgw config sync` compares the file with what the tenant has now and builds a plan:

* pgw **creates** a record that the file has and the tenant lacks.
* pgw **updates** a record whose fields differ.
* pgw **leaves alone** a record that the tenant has and the file lacks, unless you pass `--prune`.

pgw applies the plan as one transaction. If any part fails, nothing changes.

pgw reads it only when you run a sync, and its database stays the source of truth. So a change that someone makes with the CLI stays in place until the next sync puts the file's values back.

## Before you begin

* The tenant's API key, in `PGW_API_KEY`. `pgw bootstrap` saves it in `.env`.
* The secret of each record that the file creates: the APNs key, the Firebase service account, or the SIP password.

## Export, edit, and sync

**1. Export the tenant**

```bash theme={null}
pgw config export --out pgw.yaml
```

Start from an export, not an empty file. An export lists every field with its current value, so a later sync changes only what you edit:

```yaml theme={null}
apps:
  - platform: ios
    bundle_id: com.example.phone
    apns_team_id: ABCDE12345
    apns_key_id: ABC123DEFG
    apns_environment: production
upstreams:
  - name: office
    host: pbx.example.com
    port: 5060
    transport: udp
    max_expires: 3600
    invite_source_cidrs:
      - 192.0.2.10/32
    strict_path: true
    contact_strategy: masquerade
    keepalive_seconds: 30
    mode: managed
    user_source: pgw
    app_auth: digest
    users:
      - username: "1001"
        enabled: true
      - username: "1002"
        auth_username: bob-auth
        enabled: true
```

A sync of the unchanged export prints `nothing to change`.

**2. Move each secret into a file or an environment variable**

The YAML file never holds a secret, so you can commit it. Keep the secret files out of version control.

```bash theme={null}
mkdir -p secrets
cp AuthKey_ABC123DEFG.p8 secrets/
chmod 600 secrets/*
```

**3. Add a reference to each secret**

Name each secret with `<field>_file` and a path, or `<field>_env` and the name of an environment variable. A relative path starts at the folder of the YAML file. [Secret references](#secret-references) lists every field.

```yaml theme={null}
apps:
  - platform: ios
    bundle_id: com.example.phone
    apns_team_id: ABCDE12345
    apns_key_id: ABC123DEFG
    apns_key_pem_file: secrets/AuthKey_ABC123DEFG.p8
    apns_environment: production
upstreams:
  - name: office
    host: pbx.example.com
    # ...the other fields of the export...
    users:
      - username: "1001"
        password_env: PGW_PASSWORD_1001
        enabled: true
      - username: "1002"
        auth_username: bob-auth
        password_file: secrets/1002.password
        enabled: true
```

A record that the sync creates needs its secret, so add every reference before you use the file on a new install. When the file names a secret, pgw compares it with the stored one and shows the field as changed when it differs.

**4. Preview the change**

```bash theme={null}
read -rs PGW_PASSWORD_1001 && export PGW_PASSWORD_1001
pgw config sync pgw.yaml --dry-run
```

pgw prints one line for each change, then the count of creates, updates, and deletes. An update names the fields that change. A changed secret appears by its field name, never its value.

```text theme={null}
  ~ upstream pbx.example.com  keepalive_seconds
  ~ user pbx.example.com/1002  password
  + user pbx.example.com/1003
+1 ~2 -0
```

`+` marks a create, `~` an update, and `-` a delete. A dry run changes nothing.

**5. Apply the change**

```bash theme={null}
pgw config sync pgw.yaml
```

pgw prints the plan again, applies it, and prints `applied`.

## How pgw matches records

The file contains no IDs. pgw recognizes a record by the fields that identify it:

| Record | Identified by |
| - | - |
| App | `platform` and `bundle_id` |
| Upstream | `host` |
| User | The upstream's `host`, the user's `domain`, and its `username` |

If you change an identifying field, pgw treats the record as a new one. Changing an upstream's `host` creates a second upstream, and with `--prune` deletes the first, together with its users and devices.

A field that you leave out of the file returns to its default. The exceptions are every secret, a user's `enabled`, and an upstream's Bearer token settings, which always keep their current value when you leave them out.

An unknown key is an error, so pgw rejects a misspelled field instead of ignoring it. The file must hold one YAML document.

## Remove records with --prune

With `--prune`, pgw deletes each app, upstream, and user that the tenant has and the file leaves out, within the sections that the file names:

* A file without the `apps:` key leaves every app alone. A file without `upstreams:` leaves every upstream and its users alone.
* An upstream without the `users:` key keeps its users.
* An empty list deletes every record of that kind. `upstreams: []` deletes every upstream, and `users: []` deletes all of that upstream's users.

An export always writes `apps:` and `upstreams:`, and it writes `users:` for each upstream whose users pgw stores. It writes a key that has no records as `[]`. So `--prune` deletes each record that you remove from an exported file. `--prune` never deletes the users of a Kamailio upstream.

| Deleted record | What happens to its devices |
| - | - |
| App | pgw removes its devices and unregisters its managed devices at the PBX. |
| Upstream | pgw removes its users and devices. The PBX keeps the devices' registrations until they expire, and pgw refuses the calls that the PBX sends to them meanwhile. |
| User | pgw removes its devices and unregisters them at the PBX. |

The plan marks each delete with `-`, and shows the number of devices that a deleted app or upstream has. When the plan deletes a record, pgw asks before it applies:

```bash theme={null}
pgw config sync pgw.yaml --prune
```

```text theme={null}
  - user pbx.example.com/1003
+0 ~0 -1
Apply these changes? [y/N]
```

Type `y` or `yes` to apply. If the tenant changes before you answer, pgw applies nothing, and you run the sync again. To delete from a script, see [Run a sync in CI](https://docs.pgw.sipmicro.services/config-as-code/sync-in-ci.md).

## Secret references

| Record | Secret | File form | Variable form |
| - | - | - | - |
| iOS app | APNs `.p8` key | `apns_key_pem_file` | `apns_key_pem_env` |
| Android app | Firebase service account key | `fcm_service_account_json_file` | `fcm_service_account_json_env` |
| Web app | VAPID private key, optional | `vapid_private_key_pem_file` | `vapid_private_key_pem_env` |
| Upstream with a Kamailio user source | Database password, under `kamailio` | `password_file` | `password_env` |
| User | SIP password | `password_file` | `password_env` |

* Give each secret in one form. Setting both is an error.
* A secret written as a value, such as `password:` or `apns_key_pem:`, is an error that names the record and the field.
* An unset or empty variable is an error.
* An `_env` reference can name a `PGW_` variable from the `.env` file in the folder where you run `pgw`. A name without the `PGW_` prefix resolves only from the shell.
* pgw reads a key file whole. From a password file, pgw drops one trailing line break.
* A web app without a VAPID key gets a new one when the sync creates it, and keeps it on later syncs. To move a web app to a new tenant with its browser subscriptions, write the key with `pgw app export-vapid-key` and name it in `vapid_private_key_pem_file`. A key that differs from the app's is an error, because a new key ends every subscription.

pgw never prints a secret. An error names the record, the field, and the variable or path.

## What a sync can't change

* **Tenants, API keys, devices, push history, and bans** aren't in the file.
* **Users of a Kamailio user source** live in Kamailio. A file that lists them is an error.
* **An upstream's `mode`, `contact_strategy`, `realm`, `user_source`, and `kamailio.use_domain`** are fixed when the upstream is created. A sync that changes one fails and names the field. To change one, remove the upstream from the file, sync with `--prune`, add it back with the new value, and sync again. This deletes the upstream's users and devices.

Any error stops the whole sync, and a dry run fails in the same way, so you find a problem before anything changes.

## Next steps

> [card] [Run a sync in CI](https://docs.pgw.sipmicro.services/config-as-code/sync-in-ci.md)
>
> Apply the file from a pipeline after a person approves the plan.

> [card] [Serve several domains](https://docs.pgw.sipmicro.services/upstreams/several-domains.md)
>
> Learn the rules for the `domains` that an upstream in the file lists.


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