Skip to main content

​
Overview

This template provides a PostgreSQL runnable exposing port 5432 with a persistent data volume. Use it directly for quick starts, or inherit it in your app and wire credentials via Monk secrets.

​
Quick start (run directly)

monk load MANIFEST
monk run postgresql/db
Connect to localhost:5432 with the default credentials from postgres.yml.

​
Configuration

Key variables in postgres.yml (under postgresql/db): 
variables:
  db_user: monk                 # env: POSTGRES_USER
  db_pass: adminpassword        # env: POSTGRES_PASSWORD
  db_name: monk                 # env: POSTGRES_DB
Note: When running the base template directly, values come from the template. For production, inherit and replace with Monk secrets. 
namespace: myapp

db:
  defines: runnable
  inherits: postgresql/db

api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    database:
      runnable: db
      service: postgres
  variables:
    database-host:
      value: <- connection-hostname("database")
    database-user:
      value: <- secret("db_user")
    database-password:
      value: <- secret("db_pass")
    database-name:
      value: <- secret("db_name")
Set secrets once, then run: 
monk secrets add -g db_user="appuser"
monk secrets add -g db_pass="STRONG_PASSWORD"
monk secrets add -g db_name="appdb"

monk run myapp/api

​
Ports and persistence

  • Service: postgres on TCP 5432
  • Data path: ${monk-volume-path}/postgresql:/var/lib/postgresql/data

​
Credential updates

This template includes a custom entrypoint that automatically updates the database password when the POSTGRES_PASSWORD environment variable changes. Unlike the default PostgreSQL Docker image behavior (which only applies credentials on first initialization), this template ensures password changes take effect on existing databases. When the container starts:
  1. If an existing database is detected, the entrypoint updates the user password via ALTER USER
  2. If it’s a fresh initialization, credentials are applied normally by the PostgreSQL image

​
Troubleshooting

  • Ensure the host volume is writable by the container.
  • Check container logs (monk logs postgresql/db) if credential updates fail.