Skip to content
SHC Docs

Your first app

An app is a directory with two files: app.yaml, which names the app, and compose.yaml, which lists the containers it runs. This page writes the smallest one there is, one service from one image, and installs it.

The app is guestbook. It starts as nginx serving its own welcome page and grows a page at a time. Write it on home01.

~/learn/guestbook/app.yaml
name: guestbook
version: "1.0.0"
license:
id: MIT
~/learn/guestbook/compose.yaml
services:
web:
image: nginx:1.27-alpine
expose:
- "80"

name must match the directory’s name, version is what listings show, and license is the app’s licence; this ladder’s apps are MIT. compose.yaml is plain compose: one service, web, from the nginx image, and expose says it listens on port 80. Nothing outside the app reaches that port until you say so at install.

shc validate reads the directory the way an install would and stops at the first thing SHC would refuse.

home01
$ shc validate ~/learn/guestbook
...

Install it with a hostname. -s names the deployment, the running copy of the app. --expose <hostname> routes the hostname to the app’s service on port 443 of every node, with a certificate from the cluster’s own CA; port 80 sends a browser there.

home01
$ shc install ~/learn/guestbook -s guestbook --expose guestbook.learn.test
installing deployment "guestbook"
[guestbook] Healthy 1/1
✔ web healthy
✔ installed deployment "guestbook"
exposure: lan
$ shc ls
...

Open it. The hostname has no DNS record, so tell curl where it is with --resolve, and -k accepts the cluster’s CA, which curl does not know.

home01
$ curl -sk --resolve guestbook.learn.test:443:127.0.0.1 https://guestbook.learn.test/
...
<h1>Welcome to nginx!</h1>
...

That is the whole app: an image, a port and a name. Keep guestbook installed; every page until the shc.yaml page grows it.

Next: Your own page.