PostgreSQL

This geneset contains fodder for installing and configuring a PostgreSQL server on Linux.

The fodder is cross-platform across Linux families. It works on Debian/Ubuntu and on the RHEL family (AlmaLinux, Rocky Linux, ...). It has been tested on Debian 13 and AlmaLinux 10.

Usage

Add a gene reference to a Linux catlet, give it a data drive for its persistent state (see Persistent state), and set the password:

name: postgresql-server
parent: dbosoft/debian-13/starter

drives:
 - name: sdb
   size: 10
   location: postgresql-data

fodder:
 - source: gene:dbosoft/postgresql:server
   variables:
     - name: db_name
       value: appdb
     - name: db_user
       value: appuser
     - name: db_password
       value: change-me-please
       secret: true

The fodder pairs with an application catlet that connects to the database via its db_host variable, set to the address of the PostgreSQL catlet.

The fodder:

• installs PostgreSQL and initialises its data directory on the state drive
• creates the database and a login role that owns it
• enables TLS with a self-signed certificate (valid for 10 years)
• listens on all interfaces (listen_addresses = '*')
• adds a pg_hba.conf rule (scram-sha-256) that allows the role to connect from allowed_host
• opens port 5432/tcp when firewalld or ufw is active

Persistent state

A database server's data must survive a redeploy, but the OS disk is recreated from the gene each time. Give the catlet a second drive and make it persistent with an explicit location. This is the key detail: name (sdb) only sets the device order inside the guest, while location is the drive's identity on the host. Without a location, eryph assigns a throwaway storage id and deletes the drive together with the catlet; with one, the drive lives independently of the catlet and is re-attached on the next deploy. Pick a location that is unique within the project (the example uses postgresql-data).

The fodder formats the drive on first use (ext4, label postgresql) and puts the PostgreSQL data directory on it — mounted at /var/lib/pgsql/data on the RHEL family, and at /var/lib/postgresql/eryph/pgdata (with data_directory pointed there) on Debian/Ubuntu. On a redeploy — removing the catlet and deploying it again with the same location — the drive is re-attached, so the existing databases are used as-is. If no empty drive is present, provisioning stops with a clear error. (Guest device names are not stable, so the fodder selects the drive by label or as the empty non-root disk, never by a fixed /dev/sdX name.)

Configuration

The following variables can be used to configure the server fodder:

• db_name
  default value: db

  The name of the database that is created.

• db_user
  default value: dbuser

  The name of the login role that is created. The role owns the database.

• db_password
  required, secret, no default value

  The password of the role.

• allowed_host
  default value: 0.0.0.0/0

  The CIDR the role may connect from, written as a pg_hba.conf address (e.g. 10.0.0.0/24). 0.0.0.0/0 allows any IPv4 host.

TLS

The certificate is self-signed. A client only verifies it with sslmode=verify-ca or verify-full; with the default prefer or require the connection is still encrypted. Whether to trust the certificate is a decision of the client.

Versioning

This geneset contains only fodder genes and is versioned with a major-minor version scheme.

There is no patch version - when a bug is fixed, a new minor version will be released.
A new major version is released when a gene is removed from the geneset.

The tag latest is updated with each released version. If you want to have a stable reference, don't use the latest tag, use a specific version tag.

Contributing

This geneset is maintained by dbosoft and is open for contributions.

You can find the repository for this geneset on github.com/dbosoft/eryph-genes.

License

All public dbosoft genesets are licensed under the MIT License.