Introduction

Setting environment variables on EC2 is simple in syntax but easy to misconfigure because shells, services, cron jobs, and containers each load configuration differently. A variable that works over SSH may still be missing in production processes. The correct approach is to choose scope first, then configure and verify in the same runtime context that consumes the variable.

Decide the Scope Before Setting Anything

Most failures come from scope mismatch, not command mistakes.

Common scopes:

• Current SSH session only.
• Persistent user login shell.
• One systemd service.
• System-wide configuration.

If your app runs as systemd service, editing ~/.bashrc usually does nothing for that service.

Session-Only Variables for Temporary Testing

For quick checks during troubleshooting, export in the current shell.

1export APP_ENV=production
2export API_BASE_URL=https://api.example.internal
3
4echo "$APP_ENV"

These values disappear when the shell exits.

Persist Variables for a Specific User Shell

If you need values each time a user logs in interactively, add exports to shell startup files.

echo 'export APP_ENV=production' >> ~/.bashrc
echo 'export API_BASE_URL=https://api.example.internal' >> ~/.bashrc
source ~/.bashrc

For zsh, use ~/.zshrc. Always verify in a new session, not only by sourcing current shell.

Configure Variables for systemd Services

For long-running applications on EC2, systemd is the reliable place to define service-level environment variables.

1# /etc/systemd/system/myapp.service
2[Unit]
3Description=My App
4After=network.target
5
6[Service]
7User=ec2-user
8WorkingDirectory=/opt/myapp
9ExecStart=/opt/myapp/bin/start.sh
10Environment="APP_ENV=production"
11EnvironmentFile=/etc/myapp/myapp.env
12Restart=always
13
14[Install]
15WantedBy=multi-user.target

Apply changes:

sudo systemctl daemon-reload
sudo systemctl restart myapp
sudo systemctl show myapp --property=Environment

This is the safest setup for production service workloads.

Keep Secrets Out of Shell Profiles

Do not store database passwords or API secrets in user dotfiles. Prefer managed secret systems and restricted files.

Recommended options:

• AWS Systems Manager Parameter Store.
• AWS Secrets Manager.
• Root-owned environment files with strict permissions.

Example secure env file creation:

sudo install -m 600 -o root -g root /dev/null /etc/myapp/myapp.env
sudo sh -c 'printf "DB_PASSWORD=example-secret\n" >> /etc/myapp/myapp.env'

Then reference it using EnvironmentFile in systemd.

Automate Through Provisioning

Manual SSH edits create drift. For auto-scaling groups and reproducibility, set environment files through cloud-init or infrastructure code.

1#cloud-config
2write_files:
3  - path: /etc/myapp/myapp.env
4    permissions: '0600'
5    owner: root:root
6    content: |
7      APP_ENV=production
8      API_BASE_URL=https://api.example.internal

This ensures replacement instances come up with consistent configuration.

Verify in Process Context, Not Just Shell

A shell check only proves shell scope. Confirm what the running process actually sees.

sudo systemctl show myapp --property=Environment
sudo journalctl -u myapp -n 100 --no-pager

If running containers on EC2, inspect container runtime environment separately.

Troubleshooting Sequence

When variables appear missing:

1. Identify process owner and startup mechanism.
2. Confirm variable exists in intended configuration source.
3. Reload systemd after edits.
4. Restart service and inspect active environment.
5. Check quoting, whitespace, and file permissions.

This sequence resolves most EC2 environment-variable issues quickly.

Common Pitfalls

• Exporting in shell profiles and expecting systemd services to inherit values.
• Storing secrets in plain shell files or command history.
• Editing unit files without running systemctl daemon-reload.
• Using inconsistent variable names between scripts and service units.
• Verifying only via SSH shell and not from actual service environment.

Summary

• Environment-variable setup on EC2 must match runtime scope.
• Shell exports are for temporary or interactive use, not service guarantees.
• Use systemd Environment and EnvironmentFile for service processes.
• Keep sensitive values in managed secrets or restricted files.
• Always validate variables in the exact process context that needs them.