Skip to content
SHC Docs

Step 4: an app that uses Postgres through a plug

New line, in development. Installed on a four-node test cluster built from shc next b43f0c168 (ce 5db649eb) on 2026-10-08. The output below is that run’s, trimmed.

Step 2’s Postgres offers a socket: “ask me for a database and a user”. An app that wants one declares a plug of the same name. Connecting the two at install makes SHC run the socket’s jobs, which create what the plug asked for, and hands the app the connection details. Here the app is pgweb, a web client for Postgres. Keep pg from step 2 installed.

pgweb/
app.yaml
vars.yaml
postgres.plug.yaml
compose.yaml
pgweb/app.yaml
name: pgweb
version: "0.16.2"
title: pgweb
description: A web client for a Postgres it reaches through a plug
category: development
license:
id: MIT
vars:
postgres:
database@identifier!: database the plug asks for
username@identifier!: user the plug asks for
password@secret!: that user's password
pgweb/vars.yaml
postgres:
database: pgweb
username: pgweb
password: "ref+vault://pgweb_db_password?autogen"
# pgweb/postgres.plug.yaml: the file name is the plug's name, and it matches the socket's
required: true # pgweb does not install without a connected postgres
services:
- pgweb # the services that receive the connection
data: # what the plug asks the socket for
database: "{{ vars.postgres.database }}"
username: "{{ vars.postgres.username }}"
password: "{{ vars.postgres.password }}"
pgweb/compose.yaml
services:
pgweb:
image: sosedoff/pgweb:0.16.2
environment:
PGWEB_DATABASE_URL: "postgres://{{ integrations.postgres.plug.data.username }}:{{ integrations.postgres.plug.data.password }}@{{ integrations.postgres.socket.hostname }}:{{ integrations.postgres.socket.port }}/{{ integrations.postgres.plug.data.database }}?sslmode=disable"
command: ["pgweb", "--bind=0.0.0.0", "--listen=8081"]
expose:
- "8081"
healthcheck:
test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8081/api/info"] # this image has curl, not wget
interval: 10s
retries: 6
deploy:
resources:
limits:
cpus: "0.25"
memory: 128M

integrations.postgres is the connected edge: plug.data is what this app asked for, socket what the Postgres deployment offers (its postgres.socket.yaml publishes hostname: "{{ environment }}.postgres.{{ stack }}" and port: 5432).

Terminal window
$ shc install /root/tutorial/pgweb -s pgweb -t rig -i postgres=pg --expose 8081=pgweb:8081
installing stack "pgweb"
pgweb: starting
pgweb: running
pgweb: pgweb running
installed deployment "pgweb"
exposure: lan
$ shc integration ls -t rig -e prod
CONSUMER STACK NAME CONSUMER PLUG PROVIDER STACK NAME PROVIDER SOCKET STATUS ID
pgweb postgres pg postgres connected 0

-i postgres=pg connects the plug postgres to the deployment pg. The install may run from any node: the socket’s contract and variables are read from the replicated store, not from pg’s directory (SHC-1546, ce modules/app/provider_render.go). Where the consumer runs follows the socket’s declared placement: {colocate: location} (modules/postgres/postgres.socket.yaml), so pgweb lands in pg’s location.

Before pgweb started, the socket’s create-database job connected to pg as its admin user and created the database and the user the plug asked for:

Terminal window
$ shc exec -s pg -t rig -S postgres-1 -- psql -U postgres -d postgres -tAc "select datname, pg_get_userbyid(datdba) from pg_database where datname = 'pgweb'"
pgweb|pgweb
$ curl -s http://<node address>:8081/api/query --data-urlencode "query=select current_user, current_database(), inet_server_addr()" | jq -c .rows
[["pgweb","pgweb","10.64.49.3"]]

pgweb is connected as its own user to its own database, and the server it reached is pg’s member postgres-1, at the address it answers on. The rendered environment, with the password left out:

environment:
PGWEB_DATABASE_URL: postgres://pgweb:<the password>@prod.postgres.pg:5432/pgweb?sslmode=disable

prod.postgres.pg is <environment>.<group>.<stack> of the Postgres deployment: the group postgres, whose name answers with its writer, member 1 here. The node resolver the render sets as the service’s dns answers it.

Terminal window
$ shc uninstall pgweb -t rig -y
uninstalling stack "pgweb"
pgweb: uninstalling stack "pgweb" on node far01, which holds it
pgweb: taking the safety backup of stack "pgweb"
pgweb: taking stack "pgweb" out of every node's service VIP table
pgweb: tearing down stack "pgweb"
pgweb: taking down the replicas of stack "pgweb" on node far01
pgweb: removing the copy of stack "pgweb" on node home01
uninstalled deployment "pgweb"
pgweb: removed with the deployment: config lanEnforcement

Uninstalling the consumer leaves pg, its database pgweb and the user in place. Keep pg for step 7.

Next: Step 5: Nextcloud on Postgres and S3.