Environment Variables

Environment variables (ENV Vars) are configuration values that your application reads at startup. They control database connections, API keys, feature flags, and other runtime settings without touching your code.

On Muppy, ENV Vars are stored in /etc/muppy.env on each server and loaded automatically when you log in via SSH.

How ENV Vars are organized

Muppy uses a layered system where higher layers override lower ones:

Layer	Source	Who manages it
Computed	Server settings (database, ports, URLs, git tokens)	Muppy (automatic)
Vault envfiles	Your custom variables	You

Vault envfiles have the highest precedence — if you define a variable that Muppy also computes, your value wins.

Defining custom ENV Vars

Custom variables are defined through vault envfiles in the ENV Vars tab of your server.

Step by step

1. Open your server form and go to the ENV Vars tab
2. In the Vault ENV Files section, click Add a line
3. Give the link a name (e.g. "My app config")
4. Choose a scope — Qualifier, User or App Server (see Scopes and qualifiers below)
5. Click Edit Vault to open the vault editor
6. Enter your variables, one per line:

   SMTP_HOST=smtp.example.com
   SMTP_PORT=587
   MY_API_KEY=sk-abc123
   REDIS_URL=redis://localhost:6379
   

7. Save the vault, then save the server

Format rules

• One KEY=VALUE per line
• Write raw values without quotes — Muppy adds shell-safe quoting automatically so that /etc/muppy.env can be sourced by the shell
• Lines starting with # are comments (on their own line)
• Inline comments are not supported — KEY=value # comment would include # comment as part of the value
• Empty lines are ignored
• If the same key is defined in multiple levels, the highest-precedence level wins (vault envfiles > computed > migration)

Do not quote values yourself

Write MY_VAR=hello world, not MY_VAR="hello world". Muppy wraps every value with shlex.quote() before writing /etc/muppy.env. If you add your own quotes, they become part of the value (double-quoting).

How ENV Vars reach your server

After saving, the Effective /etc/muppy.env section shows the final file that will be written. To push it to the server:

1. Click Upload /etc/muppy.env to Host
2. The file is written to /etc/muppy.env on the server
3. Next SSH login automatically sources it via ~/.bashrc

No restart needed for new SSH sessions

ENV Vars are loaded at each SSH login. Already running processes won't see the changes until they are restarted.

Scopes and qualifiers

Every server is created from an App Definition (a template that defines the application type, repository, etc.). Each server also belongs to a qualifier — a category like Development, Staging, or Production that groups servers sharing the same role.

Server code and vault sharing

The {server} part in vault codes comes from your server's code (e.g. mpy18c), chosen at creation time. All servers sharing the same code automatically share the same qualifier-scoped vaults — that's why choosing a meaningful, consistent code matters.

Vault envfiles also use scopes to control how they are attached to servers. Muppy finds the vault of a link by its code, which the scope builds:

Scope	Vault code pattern	Shared by
Qualifier	{server}-{qualifier}-{type}-{name}	Every server with the same code and qualifier. When you create a new Development server from the same App Definition, it automatically gets the qualifier-scoped vaults.
User	{server}-{qualifier}-{username}-{type}-{name}	Every server with the same code and qualifier that runs under the same Unix account — {username} is the server's Username, usually muppy, not your Muppy login.
App Server	{app-server-name}-appsrv-{type}-{name}	This server only. The vault belongs to the server's owner.

What a vault keeps:

• A Qualifier vault follows the App Definition: at each upload of /etc/muppy.env, and when you click Update ENV Vars from App. Def., its content is rewritten from the link's default value.
• A User or App Server vault is filled from the link's default value once, when it is created. After that it keeps what you write in it.
• An App Server vault stays when its server is deleted, and a server created again under the same name finds it.
• An App Server vault follows its server when the server is renamed: Muppy gives it the new code. A rename also happens without you typing a name: the Refresh button recomputes a server's name unless Force Name is set, from parts such as your user slug or the branch. If a vault already holds the new code, Muppy uses that vault and leaves the old one under its old code.

When to use which:

• Qualifier — team-shared config that every server of that type needs (e.g. shared API endpoints, feature flags)
• User — overrides shared by the servers of one Unix account (e.g. debug settings)
• App Server — config that belongs to one server and must differ from its siblings (e.g. one Sunray worker per LXD host, each with its own settings). Declared on the App Definition, the link gives each server created from it a vault of its own, filled from the default value.