Environment variables

Environment variables hold settings that differ between environments or must stay secret: database URLs, API keys, feature flags.

Add, replace or delete a variable

On the app page, find Environment variables.

• Add: type a name and value, then click Add.
• Replace: type an existing name with a new value; the button changes to Replace. You can also click Replace next to a variable.
• Delete: click the delete icon next to it.

Changes apply to the next deployment. Click Deploy or push a commit to use them; the running version keeps its current values until then.

You can also add variables in the last step of Create application.

How values are protected

• Values are encrypted before they’re stored.
• After saving, a value is never shown again: not to you, not to admins, not through the API. You can only replace or delete it. Keep the original in your password manager.
• Values are given to the build as a temporary secret and are never written into the app’s image.
• Every change is recorded in the activity log with who made it, but never with the value.
• Developers, admins and owners can manage variables. Viewers see the names only.

Rules

Rule	Detail
Names	Letters, numbers and _, not starting with a number. For example DATABASE_URL, STRIPE_KEY.
Reserved	PORT is set by Shiplon from the app’s Port setting. Names starting with KUBERNETES_ or PLATFORM_ are reserved too.
Size	Up to 32 KB per value.
Count	Up to 100 variables per app.

Using them

At runtime, every variable is in the app’s environment:

const db = new Pool({ connectionString: process.env.DATABASE_URL });

During the build:

• For Static and Node.js apps, variables are available to your install and build commands. This is how tools like Vite pick up VITE_* variables.
• For Dockerfile apps, mount them in the build step that needs them; see Using environment variables while building.

Static sites make build-time values public

A static site’s build copies variables such as VITE_API_URL into the JavaScript files that every visitor downloads. Only use public values there: an API’s address, yes; its secret key, never. Keep secrets in a server-side app.

Good practice

• Use a separate set of credentials for each app, so you can revoke one without touching the others.
• When you rotate a secret, Replace the variable, then Deploy, then revoke the old credential.
• Don’t commit .env files to your repository. Shiplon doesn’t read them; use the variables here instead.