Skip to content
SHC Docs

Creating apps: tutorial

Layer 6. Services. Services

This walkthrough builds a complete SHC app end-to-end. By the end you’ll understand how the file layout, variable model, integration system, hooks, and backup converters fit together, with working code at each step.

For the reference-style schema of each file, see app-definition. For the integration system specifically, see plugs-and-sockets.

What we’re building. A tiny “feedback form” app called feedback: a single web service that stores form submissions in a Postgres database. It:

  • reads its admin password from the vault (autogenerated)
  • connects to an existing Postgres deployment via a plug
  • seeds its own DB schema in a post_install hook
  • dumps the DB in a pre_backup converter so backups are consistent

Prerequisites: a working SHC install (see installation) and a Postgres deployment to connect to:

Terminal window
shc install postgres --stack db

Apps can be installed straight from a local directory. Repos are remote-only (git / http(s)), so local development uses direct-path installs. Create a working directory for the app:

Terminal window
mkdir -p ~/my-apps/feedback

Later, shc install ~/my-apps/feedback installs it directly. When the app is ready to share, push ~/my-apps to a git remote and register that with shc repo add my-apps https://… so every node can install it by name.


Create ~/my-apps/feedback/app.yaml:

name: feedback
version: "1.0.0"
description: Simple feedback-form app with Postgres backend
category: productivity
tags:
- feedback
- forms
requires:
runtimes: [docker, podman]
vars:
hostname@string!: Public hostname (e.g. feedback.example.com)
adminEmail@email!: Administrator email address
adminPassword: "!ref+vault://adminPassword?autogen&length=32"

A few things worth pointing out:

  • Publish the deployment with --expose, not a key in this file. expose: in shc.yaml only declares the listening port.
  • Required variables use the trailing !: hostname@string! means install fails without it.
  • Autogenerated secrets don’t need user input. The first install generates a 32-char password and stores it in the vault; subsequent renders reuse it. See vault: reference syntax.

We want feedback to get its own database inside a shared Postgres deployment. That’s exactly what the database vApp on apps/postgres/ is for; see vapps.

Create ~/my-apps/feedback/postgres.plug.yaml:

data:
database: feedback
username: feedback
password: "!ref+vault://dbPassword?autogen&length=32"

socket: is derived from the filename (postgres), so we don’t need to declare it. The data block gets validated against the provider’s schema at connect time; see the Postgres socket schema.

The names are the app’s own. Don’t derive them from {{ stack }}: in plug data: on an edge to a deployment, {{ stack }} is the Postgres deployment’s name, not feedback’s, so every app on that Postgres would ask for the same database, and a Postgres deployed as postgres would hand out its superuser (SHC-1451; see plugs and sockets). To run a second feedback against the same Postgres, move the names into vars: and set them with --var.


Create ~/my-apps/feedback/shc.yaml:

services:
web:
image: python:3.12-slim
command: >
python -m http.server 8080
--directory /app/public
volumes:
- name: static
path: /app/public
- source: ./files/app.py
path: /app/app.py
read_only: true
environment:
ADMIN_EMAIL: "{{ vars.adminEmail }}"
ADMIN_PASSWORD: "{{ vars.adminPassword }}"
DATABASE_URL: "postgres://{{ integrations.postgres.socket.username }}:{{ integrations.postgres.socket.password }}@{{ integrations.postgres.socket.hostname }}:{{ integrations.postgres.socket.port }}/{{ integrations.postgres.socket.database }}"
expose:
- "8080"

shc.yaml is SHC’s own schema. A key it does not name is refused at install, naming the service and the key, so a typo fails loudly instead of being ignored. static is a named volume: the render declares it, so there is no top-level volumes: block. ./files/app.py is a file in the app directory. See shc.yaml for every key. An app you already have as a compose.yaml keeps working, and shc convert ~/my-apps/feedback prints its shc.yaml.

Key template variables:

  • {{ vars.* }}: everything declared in the vars: block (and auto-generated secrets resolve to their real values, not the ref+vault:// URI)
  • {{ integrations.postgres.socket.* }}: the provider socket’s data, keyed by the plug name (postgres.plug.yaml → plug name postgres)
  • {{ stack }}, {{ environment }}, {{ tenant }}: the deployment’s stack name, environment and tenant. stack is the app-identity axis.

See app-definition, shc.yaml or compose.yaml for the full template context.


We want to create the schema after install succeeds. Jobs live in *.job.yaml files next to app.yaml.

Create ~/my-apps/feedback/init-schema.job.yaml:

name: init-schema
context: container
image: postgres:16-alpine
entrypoint:
- psql
- "{{ integrations.postgres.socket.database_url }}"
- -c
- |
CREATE TABLE IF NOT EXISTS submissions (
id SERIAL PRIMARY KEY,
name TEXT NOT NULL,
email TEXT NOT NULL,
message TEXT NOT NULL,
submitted_at TIMESTAMPTZ DEFAULT now()
);
networks:
- "shc_{{ tenant_name }}"
timeout: 60
on_failure: abort

The context: container is deliberate: we can’t exec into our own web service for schema bootstrap (its container runs python -m http.server, not psql). We spawn a throwaway postgres:16-alpine container just for the psql call. See lifecycle-hooks: Job contexts for when each context applies.

Now wire it up in app.yaml:

# add to app.yaml
hooks:
post_install:
- init-schema

post_install fires after compose up succeeds; by then the integration is fully connected so {{ integrations.postgres.socket.database_url }} resolves. See lifecycle-hooks for the full hook contract.


We want shc backup create feedback to include a consistent database dump. Create ~/my-apps/feedback/backup.yaml:

converters:
- name: dump-db
phase: capture
context: container
image: postgres:16-alpine
entrypoint:
- sh
- -c
- "pg_dump {{ integrations.postgres.socket.database_url }} > /backup/feedback.sql"
networks:
- "shc_{{ tenant_name }}"
output: /backup/feedback.sql
timeout: 300
volumes:
- name: static
strategy: rsync

converters[].phase: capture runs during the capture phase of backup, after the deployment is snapshot-stopped and before the restic commit. The output: path is relative to the backup staging directory, which becomes part of the archive.

See flow: backup/restore for where each converter phase fires.

To restore the dump on a restore, add a restore converter too:

# backup.yaml (add)
- name: restore-db
phase: apply # runs during restore, after volumes are back
context: container
image: postgres:16-alpine
entrypoint:
- sh
- -c
- "psql {{ integrations.postgres.socket.database_url }} < /backup/feedback.sql"
networks:
- "shc_{{ tenant_name }}"
timeout: 300

Terminal window
shc repo sync my-apps
shc install feedback \
--stack fb \
--repo my-apps \
--var hostname=feedback.local \
-i postgres=db.database:fb

Breaking down the -i flag: postgres=db.database:fb means: connect our postgres plug to the database vSocket on the db deployment, specifically the fb instance. See plugs-and-sockets: CLI spec.

If the fb instance of db’s database vApp doesn’t exist yet, create it first:

Terminal window
shc install postgres.database --stack db --instance fb

Check the install:

Terminal window
shc ls
shc status fb
shc logs --stack fb
shc job history -s fb # should show init-schema as completed
curl http://feedback.local/

Getting the autogenerated admin password back

Section titled “Getting the autogenerated admin password back”
Terminal window
shc vault get adminPassword --stack fb

Scope defaults to deployment, the same tuple the install used.


Re-install to trigger pre_uninstall + post_uninstall:

Terminal window
shc uninstall fb --yes

Watch events:

Terminal window
shc -s fb events

You’ll see A200000STKUNI fire as the uninstall completes.


Terminal window
shc backup create fb
# List backups:
shc backup list fb
# Restore (will use the dump-db converter to re-seed schema)
shc backup restore <backup-id> --stack fb

Step 10: Static validation while developing

Section titled “Step 10: Static validation while developing”

shc validate runs the same schema checks the install flow uses, but without needing a running target:

Terminal window
shc validate ~/my-apps/feedback/

This catches:

  • missing required variables
  • YAML parse errors
  • plug/socket schema mismatches
  • reference to undefined job names in hooks
  • a --expose target that names no service in shc.yaml

Run it on every save while iterating.


Intentionally omitted, deeper topics you’d reach for in production apps:

  • Exposing a socket so other deployments can plug into yours: see plugs-and-sockets with a complete socket example from apps/postgres/.
  • vApps: letting operators provision per-tenant sub-resources inside your deployment. See vapps.
  • Crons: scheduled jobs inside the deployment. Add a crons: map to app.yaml:
    crons:
    nightly-cleanup: "0 3 * * *"
    …where nightly-cleanup is a *.job.yaml file. See architecture/modules/schedule.
  • Multiple environments: the same stack name in another environment (-e prod, -e staging) is another deployment: separate data, secrets and DNS.
  • Where it runs: --where names nodes the deployment may run on and --prefer names nodes it prefers. A node runs one runtime.
  • Resource quotas: requires.storage: whitelists storage providers; shc quota tunes per-tenant limits. See architecture/modules/quota.

For reference, everything in one place:

name: feedback
version: "1.0.0"
description: Simple feedback-form app with Postgres backend
category: productivity
tags:
- feedback
- forms
requires:
runtimes: [docker, podman]
vars:
hostname@string!: Public hostname (e.g. feedback.example.com)
adminEmail@email!: Administrator email address
adminPassword: "!ref+vault://adminPassword?autogen&length=32"
hooks:
post_install:
- init-schema

Directory after all steps:

~/my-apps/feedback/
├── app.yaml
├── shc.yaml
├── postgres.plug.yaml
├── init-schema.job.yaml
├── backup.yaml
├── files/
│ └── app.py
└── tests/
└── install.bats