Edit environment variables

Almost every application keeps its secrets and settings in a .env file: the database password, the application key, mail credentials, API tokens. SrvYard keeps an encrypted copy of that file for each site and writes it to the server for you, so you can change a variable without opening an SSH session.

This article shows the Environment tab: the two editing modes, how values stay hidden, what each save option does, and how to pull the file back from the server if someone edited it there. It also explains where the file lives on a zero-downtime site, which surprises people the first time.

Before you begin#

• An owner or admin role. The .env holds secrets, so only owners and admins (or a custom role with the permission to manage the environment) can see or change it. Everyone else sees a Restricted notice instead of the file.
• A site in the Ready state. The editor is read-only until the site has finished installing.
• A first deployment, ideally. A site that has never deployed has no .env yet. SrvYard creates one during the first deployment from the application's own .env.example (or .env.dist for Symfony), applies the database it created for the site, and then keeps an encrypted copy so it can be edited here. You can also write a file by hand before that deployment.

1. Open the Environment tab#

Open the site and choose Environment.

1. Normal / Developer. Switch between the row editor (Normal) and the text editor (Developer). Your choice is remembered in your browser, so each person has their own default.
2. Reveal values. Values are dots by default. This button shows every value at once; it changes to Hide values. Each row also has its own eye button for revealing one value.
3. Filter variables. Narrows the list by name. The counter next to it shows how many variables the file has.
4. Add variable. Adds an empty row at the top of the list.

On the right the Server card shows where the file lives and when it was last written. The next step covers it.

A saved file is encrypted in SrvYard and written to the server as the site user with mode 0600, so other users on the machine cannot read it. A deployment that is already running does not pick up a change made while it runs.

2. Add, change and remove variables in Normal mode#

1. Add variable. Press it once per variable.
2. KEY. The name. Letters, digits and underscores, not starting with a digit. An invalid name is listed under the editor as "Line N: ..." and blocks saving until you fix it.
3. value. The value. SrvYard quotes it for you when the file needs it. The eye button beside the row reveals this value alone; the bin button deletes the row and offers Undo for a few seconds in the toast that appears.

Things to know about Normal mode:

• Comments and blank lines survive. They stay in the file even though the row editor does not show them. Switch to Developer mode to see or edit them.
• Duplicates are allowed but flagged. A name that appears twice gets an amber note, "is already set on line N; the last one wins", because that is how most .env parsers behave.
• Unsaved changes. An Unsaved changes badge appears next to the title until you save. Reset changes discards your edits.

3. Edit the whole file in Developer mode#

1. Developer. Switches to the text view. Your edits in one mode carry over to the other.
2. The masked file. Each line keeps its name and shows dots instead of the value. Below it SrvYard reminds you: "Values are hidden. Use Reveal values to edit the file." An empty file shows "The .env is empty." and a file that does not exist yet says the first deployment creates it from .env.example, "or write one here".
3. Reveal values. Turns the masked view into a code editor with the real text. Only reveal values when nobody is looking over your shoulder.

The file may be up to 100,000 characters and may not contain a null byte. Windows line endings are converted, and the file always ends with one newline.

4. Save, and decide what happens next#

1. Run php artisan config:cache. Shown for Laravel-based sites. Tick it when the application caches its configuration (most production setups do): without it the app keeps using the old cached values and ignores your change.
2. Restart queue workers. Also Laravel only. Queue workers load the environment once when they start, so restart them after changing anything they read, such as a queue connection or an API key.
3. Save and write to server. Saves the file in SrvYard and queues a job that writes it to the server. The toast says "Saving the .env on the server...". The Status line changes to Writing to the server... and then to On the server with the time. The button is disabled while nothing has changed.
4. Save and deploy. Saves, writes and then starts a deployment. It is shown only when the site has a repository. Use it when the change goes together with a code change.
5. Reload from server. Reads the file as it is on the server and replaces the saved copy. See step 5.

If the server cannot take the file, a red The server did not take the change notice shows the reason, for example that the server is unreachable. Fix it and save again.

Where the file is#

The File row shows the full path. On a zero-downtime site this is a shared copy, for example /home/srvyard/api.harborlane.example/.env: every release links to it, so a new release never loses its environment and a rollback keeps the current values. On a site that deploys in place it is the .env inside the application folder.

5. Pull the file back from the server#

If someone edited the .env over SSH, the copy in SrvYard is out of date and your next save would overwrite their change. Press Reload from server.

1. Pull from server. Replaces the saved copy, including any unsaved edits in the editor, with the file the site uses right now. The toast says "Pulled the .env from the server." The content is never written to a log.

Troubleshooting#

• "The .env holds secrets, so only owners and admins can view or change it." Ask an owner or admin for access, or for a role that includes the environment permission.
• The Save button is greyed out. Nothing changed, a line has an invalid variable name, or the site is not Ready. Fix the red "Line N" messages first.
• I saved, but the application still uses the old value. The configuration is cached or a worker is running with the old environment. Save again with Run php artisan config:cache and Restart queue workers ticked, or run those commands from the Commands tab.
• "The server did not take the change." The write job failed. The message gives the reason; the usual causes are an unreachable server or a full disk.
• A value with a # or spaces is cut off. Wrap it in double quotes in Developer mode. Normal mode adds quotes when needed.
• The deployment I started did not see my change. A deployment that was already running when you saved does not pick up the new file. Start another one.
• Two people edited at once. The last save wins. Use Reload from server before editing if you suspect a colleague changed the file.

Related#

• Write and test a deploy script: the Make .env variables available to the deployment script switch.
• Queue workers and the Laravel scheduler: restart workers after a change.
• Connect a site to its database: the variables that point an app at its database.
• What SrvYard stores and how credentials are encrypted: how the saved copy is protected.