Skip to content

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 scope qualifier (shared across servers of the same type) or user (private to you)
  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:

Scope Vault code pattern What it means
qualifier {server}-{qualifier}-{type}-{name} Shared across all servers with the same App Definition 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} Private to your user. Other users with servers on the same qualifier won't see your user-scoped vaults.

When to use which:

  • qualifier — team-shared config that every server of that type needs (e.g. shared API endpoints, feature flags)
  • user — personal secrets or overrides (e.g. your own API keys, debug settings)