Skip to main content
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

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:
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.
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 lists every field.
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

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.
+ marks a create, ~ an update, and - a delete. A dry run changes nothing.
5

Apply the change

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

Secret references

  • 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

Run a sync in CI

Apply the file from a pipeline after a person approves the plan.

Serve several domains

Learn the rules for the domains that an upstream in the file lists.