myos/skills/myos/SKILL.md

name, description

name	description
myos	Deploy, inspect and troubleshoot docker compose stacks on a server or a fleet with the myos CLI (Make Your Own Stack). Use when asked to install myos, to start/stop/debug a stack (a host singleton, an application, a user stack), to add a stack to the catalogue, or to work on the myos framework itself.

myos

myos runs docker compose stacks. It decides which compose files to load, under which project name, with which variables. Everything else is docker.

Is this the right tool

Use it when the repository or the host has one of:

• a stack/ directory holding compose files,
• a Makefile that includes make/include.mk,
• /etc/conf.d/myos or /etc/default/myos,
• the myos command on PATH.

Otherwise call docker compose directly.

Look before you touch

myos doctor              # requirements, config layers, stack path
myos ls                  # stacks reachable from here
myos ls --groups         # groups and what they expand to
myos env                 # resolved variables
myos -n up host          # print what `up` would run, without running it

Always run myos -n before up, down or restart on a host/ stack. Host stacks bind privileged ports and are shared by everything on the machine: taking host/fabio down drops every site the machine serves.

Working loop

myos ls                       # find the stack
myos -n config <stack>        # check the file list and the project name
myos up <stack>               # create and start
myos ps <stack>               # what is running
myos logs <stack>             # follow the logs
myos exec <stack> -- sh       # a shell in the service named after the stack
myos down <stack>             # remove the containers

Naming a stack

A reference is [<group>/]<name>[:<version>], or a path.

Commands chain: myos build up logs host/fabio runs the three in order and stops at the first failure.

myos up                    # the current directory, when it holds a compose file
myos up host               # a group: expands to host/consul host/fabio ...
myos up host/fabio         # one stack
myos up postgres:9.6       # the 9.6 overlay of the postgres stack
myos -C /opt/app up        # somewhere else
myos -e master up          # in another environment

Stacks are looked up along the stack path: ./stack, ../stack, ~/.local/share/myos/stack, /usr/local/share/myos/stack, /usr/share/myos/stack. myos doctor prints the resolved path.

A stack found in several of them is merged, the project last, so a project adds stack/postgres/postgres.local.yml next to the catalogue's postgres.yml and refines it instead of replacing it. The same goes for the settings hooks.

Three kinds of stack

kind	reference	compose project	meaning
host	host/*	the hostname	one per machine: binds 80/443, consul, certbot. Shared. Treat as production.
user	User/*	the user identity	one per user: ssh-agent, personal services
app	anything else	<user>-<env>-<app>	many per machine, one per user and environment

Set MYOS_PROJECT_FORMAT=user-app-env on a deployment created before the rename, otherwise its containers and volumes look like a different project. See references/conventions.md.

Rules

• Never run myos clean on a host stack: it removes images and volumes, including the certificates.
• Secrets belong in a file outside the repository, never in a compose file.
• A stack of the catalogue is shared: change it in myos-stacks, not in place on a server.
• Before upgrading myos on a machine that already runs stacks, pin the naming (references/conventions.md), or every project gets a new name.

More

• references/commands.md — every command, and its equivalent in the old make targets
• references/conventions.md — file layout, naming, networks, variables, tags
• references/troubleshooting.md — what each failure means and how to fix it
• references/authoring.md — writing a stack, and working on myos itself