Skip to content
SHC Docs

Exporters

A backup takes every data volume, for disaster recovery. An export takes what the app chooses to hand over, in its own format, so data can move to another deployment or be read by a person. An exporter is a file of the app, <name>.exporter.yaml: the parameters each direction takes, and the jobs that write the artifact and read it back.

Give notebook one called notes on home01.

~/learn/notebook/notes.exporter.yaml
schema:
export:
lines:
type: int
required: false
default: 100
description: how many of the newest lines to export
import:
mode:
type: string
required: false
default: replace
description: replace the log, or append to it
jobs:
export:
- name: take-lines
context: service
service: notes
command: tail -n {{ params.export.lines }} /srv/notes/log > /output/log
volumes:
- "@output:/output"
import:
- name: put-lines
context: service
service: notes
command: |
if [ {{ params.import.mode }} = append ]; then
cat /input/log >> /srv/notes/log
else
cp /input/log /srv/notes/log
fi
volumes:
- "@input:/input"

schema declares each direction’s parameters with a type and a default; a parameter it does not declare is refused before any job runs. Each job runs command, one shell script, inside the running notes container (context: service). @output is the directory the export packs into its artifact, and @input is the artifact unpacked again for the import; SHC copies both in and out of the container around the job. The rest is in Writing an exporter.

home01
$ shc update notebook
...

Export the newest lines with the default, then with a parameter, as a flag and as one JSON object. --output-dir copies the artifact into a directory of yours.

home01
$ shc export notes -s notebook
...
$ shc export notes -s notebook -p lines=5 --output-dir ~/learn/exports
...
$ shc export notes -s notebook --params-json '{"lines": 3}'
...
$ shc export notes -s notebook -p line=5
export runs as operation 92924062-11d7-4af4-8a3e-bb70dcc3c912
shc: [X400528EXPUND] exporter notes declares no export parameter line, its export parameters are lines, nothing was run
$ shc export ls -s notebook
...

--params-json takes the same parameters as one JSON object. line is not a parameter the exporter declares, so that export ran nothing.

An artifact is a .exp file. mount checks it and unpacks it into a directory to read, until umount deletes the copy or it sits idle for --idle-ttl seconds. umount takes the artifact the mount was made from.

home01
$ shc export mount ~/learn/exports/*.exp --idle-ttl 600
...
$ shc export umount ~/learn/exports/*.exp
...

An import reads an artifact from the import directory, /var/lib/shc/import, and nowhere else. Copy the five lines there, empty the log, and import them.

home01
$ mkdir -p /var/lib/shc/import/notes
$ cp ~/learn/exports/*.exp /var/lib/shc/import/notes/
$ shc exec -s notebook -S notes -- sh -c ': > /srv/notes/log'
$ shc import notes -s notebook -i /var/lib/shc/import/notes
...
$ shc exec -s notebook -S notes -- wc -l /srv/notes/log
...
$ shc import notes -s notebook -i /var/lib/shc/import/notes -p mode=append
...
$ shc import notes -s notebook -i /var/lib/shc/import/notes --params-json '{"mode": "append"}'
...
$ shc exec -s notebook -S notes -- wc -l /srv/notes/log
...

--wrap makes an artifact of a plain file first, so the import reads a file nobody exported. The file lands at the root of @input under its own name, which is the log put-lines reads.

/var/lib/shc/import/wrap/log
a line written by hand
home01
$ shc import notes -s notebook --wrap /var/lib/shc/import/wrap/log
...
$ shc exec -s notebook -S notes -- head -n 1 /srv/notes/log
a line written by hand

Keep notebook installed.

Next: Your own socket and plug.