Environment variables & secrets
Give your app its settings and secrets — add them in the Configuration tab or the CLI, keep the sensitive ones masked, and apply changes without a full rebuild.
Most apps need a few pieces of information to run: a database address, an API key, a "am I in production?"
flag. Those are environment variables — little named settings your app reads when it starts. Think of
them as sticky notes you hand your app: DATABASE_URL = ..., STRIPE_KEY = .... Openship keeps those notes
for you, hands them to your app every time it builds and runs, and hides the sensitive ones so nobody can
read them over your shoulder.
What you need first
- A project you've already created in Openship (if not, start with Deploy from GitHub).
- The names and values you want to set — for example
DATABASE_URLand its connection string. - Nothing else. Openship encrypts and stores the values for you.
Add or edit variables in the dashboard
Open the Configuration tab
Go to your project and open the Configuration tab. Find the Environment variables card and press Edit. A panel opens showing the variables you already have (empty is fine — a brand-new app often has none).
Screenshot
Add a variable
Press Add variable. You get a row with two boxes: the KEY on the left (the name, like DATABASE_URL)
and the value on the right. Type both.
Add as many rows as you need. To remove one, press the trash icon at the end of its row.
Mark the secret ones
Some values are sensitive — passwords, API keys, tokens. For each of those, press the key icon on the
row to mark it as secret. A secret's value is stored the same way, but from then on it shows as dots
(••••••••) instead of plain text, so it stays hidden whenever you reopen the editor.
Everything is encrypted at rest
Whether or not you mark a variable secret, Openship encrypts every value before saving it. Marking a value secret adds the on-screen masking on top — it controls what you can see later, not whether it's protected on disk.
Save
Press Save changes. Openship only writes the rows you actually added, changed, or deleted — every other variable is left exactly as it was. That's why a masked secret you didn't touch is never overwritten: you never re-typed it, so it's never re-sent.
Saving isn't the same as applying
A saved change is stored right away, but the running app keeps its old values until the next deploy. If something is already live, Openship offers a shortcut to push the change out immediately — see Apply without a full rebuild below. Otherwise the new values take effect the next time you deploy.
When your app sees these values
Openship hands your variables to your app at two moments:
- During the build — so a value baked in at build time (for example a
NEXT_PUBLIC_...setting in a frontend) is there when the build runs. - At runtime — so your running server can read them the normal way (like
process.env.DATABASE_URL).
You don't do anything special for this. Set the variable, deploy, and it's present in both places.
Reveal, hide, and replace a secret
Inside the editor, each value has an eye icon to show or hide it. A secret you saved earlier comes back
masked with the placeholder •••••••• (set — type to replace). To change it, just type the new value over
the dots. To keep it, leave it alone — Openship keeps the stored value untouched.
Production and preview values
Openship keeps variables per environment, so your test setup and your live setup can differ (a preview
build can point at a test database while production points at the real one). The three environments are
production, preview, and development.
The dashboard editor manages your production values. To set values for preview or development, use
the CLI (below) with the --environment flag.
Apply without a full rebuild
Rebuilding an app just to change a setting is slow — nothing about your code changed. So when you save an env change and the project is already deployed, the editor shows an Apply (restart, no rebuild) button.
Press it and Openship recreates the running container from the image it already built, with the new values injected. No git clone, no build — just a quick restart. It's the fastest way to roll out a changed key or a rotated secret.
Screenshot
The same thing from the terminal is openship deploy --refresh (shown below).
Prefer the terminal?
Everything above works from the CLI. Secret values always come back masked when you list them.
# List a project's variables (secrets show masked)
openship project env get <project-id>
# Set one or more values (repeat --set for each)
openship project env set <project-id> --set DATABASE_URL=postgres://... --set LOG_LEVEL=info
# Mark the values in this command as secret
openship project env set <project-id> --set STRIPE_KEY=sk_live_... --secret
# Remove a variable
openship project env set <project-id> --unset OLD_FLAG
# Target a different environment (defaults to production)
openship project env set <project-id> --environment preview --set API_URL=https://staging.example.com
# Push the current env to the running app — no git pull, no rebuild
openship deploy --refreshenv set merges: it only touches the keys you name with --set and --unset, leaving everything else
in place.
For a multi-service (compose) project, each service has its own variables. Target the stack with
-p and the service by name:
# List a service's variables (secrets masked)
openship service env get web -p my-stack
# Set values for a service (KEY=VALUE pairs)
openship service env set web -p my-stack DATABASE_URL=postgres://... --secret
# Pick the environment (defaults to production)
openship service env set web -p my-stack -e preview API_URL=https://staging.example.comSecrets and service env
The service command writes the whole environment at once, so it first reads the current values and merges
yours in. Because saved secret values can't be read back, if the service already has a secret you didn't
re-type, the command stops and asks you to re-specify it — or pass --replace to drop every value that
isn't in your command.
If something goes wrong
I saved a variable but my app still doesn't see it
Saving stores the value; the running app only picks it up on a deploy. Use Apply (restart, no
rebuild) (or openship deploy --refresh) to push it out now, or just redeploy.
A secret shows as dots and I can't read it back
That's on purpose — Openship never reveals a stored secret's value again, in the dashboard or the CLI. If you need to change it, type a new value over the dots. If you've lost the original, set a fresh one.
The build failed with a missing-variable error
Your app expected a variable that isn't set yet. Add it in the Configuration tab (or with openship project env set), make sure the name matches exactly — env names are case-sensitive — then deploy again. See
Troubleshooting → Deployments for more.
What next?
Custom domains, DNS & SSL
Put your app on your own address like app.example.com, with automatic HTTPS — add the domain, point your DNS, verify, done.
Compose & multi-service apps
Run an app that's really several pieces at once — web, worker, database — from a docker-compose file or added by hand, and keep every service in sync.