Ultimate Environment Framework

A Railway-focused skill for managing environment variables, service configurations, and environment isolation across Railway projects. Ultimate Environment Framework handles variable scoping, shared variable groups, secret management, and environment-specific overrides for development, staging, and production.

When to Use This Skill

Choose Ultimate Environment Framework when:

• Managing environment variables across multiple Railway environments
• Setting up environment isolation (dev/staging/production)
• Configuring shared variables that apply to multiple services
• Debugging missing or incorrect environment variable issues

Consider alternatives when:

• Managing local development environment variables (use .env files)
• Setting up secrets in CI/CD pipelines (use GitHub Secrets or similar)
• You need a full secrets management solution (use Vault, AWS Secrets Manager)

Quick Start

Copy
claude "Set up environment variables for my Railway production environment"

Copy
# List all variables in current environment
railway variables

# Set a variable
railway variables --set KEY=value

# Set a variable for a specific environment
railway variables --set KEY=value --environment production

# Delete a variable
railway variables --delete KEY

# Use reference variables (link to another service's var)
railway variables --set DATABASE_URL='${{Postgres.DATABASE_URL}}'

Core Concepts

Variable Scoping

Scope	Applies To	Example
Service-specific	Single service in one environment	API_SECRET=prod-key-123
Shared Variable	All services referencing the group	REDIS_URL=redis://...
Reference Variable	Dynamic link to another service's var	${{Postgres.DATABASE_URL}}
Railway-injected	Auto-set by Railway plugins	PGHOST, REDISPORT

Environment Isolation

Copy
# Create separate environments
railway environment create staging
railway environment create production

# Each environment has independent:
# - Variables (different API keys, DB connections)
# - Deployments (different code versions)
# - Domains (staging.app.com vs app.com)
# - Resources (different scaling)

# Switch between environments
railway environment use staging
railway variables   # Shows staging variables

railway environment use production
railway variables   # Shows production variables

Variable References

Copy
# Reference variables from other services
# Format: ${{ServiceName.VARIABLE_NAME}}

# Link to PostgreSQL plugin's URL
DATABASE_URL=${{Postgres.DATABASE_URL}}

# Link to Redis plugin's URL
REDIS_URL=${{Redis.REDIS_URL}}

# Link to another service's port
API_URL=http://${{api-service.RAILWAY_PRIVATE_DOMAIN}}:${{api-service.PORT}}

Configuration

Parameter	Description	Default
environment	Target environment (dev, staging, production)	Current linked environment
scope	Variable scope (service, shared, reference)	service
sensitive	Mark variable as secret (masked in UI/logs)	false
override_priority	Service-specific overrides shared vars	true
sync_environments	Auto-sync non-sensitive vars across envs	false

Best Practices

1. Use reference variables instead of copying values. When your API needs the database URL, use ${{Postgres.DATABASE_URL}} instead of copying the connection string. References stay in sync when the source changes — copied values become stale.

2. Never store secrets in code or railway.json. Use railway variables --set to inject secrets at runtime. The railway.json file is committed to version control — any secrets there are visible to anyone with repo access.

3. Use consistent variable naming across environments. Production and staging should use the same variable names with different values. Your application code should reference DATABASE_URL regardless of environment — only the value changes.

4. Document non-obvious variables. When a service requires specific variables, list them in the README or a .env.example file. New team members shouldn't have to reverse-engineer which variables are needed from deployment errors.

5. Audit variables periodically. Remove variables for features that no longer exist and rotate secrets on a regular schedule. Stale variables increase confusion and old secrets increase security risk.

Common Issues

Variable available in one environment but missing in another. Variables are scoped per environment — setting API_KEY in staging doesn't set it in production. Use railway variables --environment production to check. Set variables in each environment individually, or use shared variable groups for values common across environments.

Reference variable resolves to empty string. The referenced service might not be deployed yet, or the variable name might be misspelled. Check that the source service exists with railway status and that the variable name matches exactly (case-sensitive). Format: ${{ServiceName.VARIABLE_NAME}}.

Sensitive variables visible in deployment logs. Railway doesn't automatically redact custom variables from stdout. Avoid logging environment variables in your application code. If a framework logs config on startup, configure it to mask sensitive fields or disable config logging in production.