Using Environment Variables Securely

What this article covers

• What environment variables are and why you use them.
• How .env files work.
• Security rules for local AI projects.
• How Docker Compose processes environment variables.
• Common mistakes and better alternatives.

Introduction: Using environment variables securely

Environment variables offer a straightforward way to separate configuration from code. Passwords, API keys, and database URLs stay out of your source tree. In local AI projects, they’re everywhere: configuring Ollama, Open WebUI, Docker containers, and agents. Using them correctly prevents many security headaches.

This article is written for newcomers. It shows how to work with environment variables, explains common pitfalls, and covers when better solutions like encrypted .env files or secret managers make sense.

What are environment variables?

An environment variable is a value available to a running process. Programs read them and use them for configuration. Examples include:

• DATABASE_URL
• OPENAI_API_KEY
• OLLAMA_HOST
• PORT
• LOG_LEVEL

You typically set them in .env files or directly in the shell.

Why use environment variables?

• Separation: Configuration stays out of code.
• Flexibility: The same application runs with different values across environments.
• Security: Secrets don’t live in your repository.
• Simplicity: Quick to set and modify.

Core security rules

• Never commit .env files to Git.
• Restrict permissions: Make files readable only by the owner.
• Don’t log secrets: Keep them out of logs and error messages.
• Don’t embed secrets in container images.
• Grant access only to processes that need it.
• Rotate values regularly.

.env files

A .env file holds one variable per line:

OLLAMA_HOST=http://localhost:11434
OPEN_WEBUI_PORT=8080
DATABASE_URL=postgresql://user:pass@localhost/db

Many tools like Python-dotenv, Docker Compose, and Node.js load these files automatically.

Docker and Docker Compose

Docker Compose gives you several ways to pass environment variables:

• env_file: Reference a .env file.
• environment: Inline values in the Compose file.
• Secrets: Docker Secrets in Swarm or Kubernetes.

Example:

services:
  webui:
    image: open-webui:latest
    env_file:
      - .env
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434

Common mistakes

• .env in the repository: Leaks happen when you accidentally push it.
• Weak file permissions: Any user on the system can read secrets.
• Dumping to logs: Using print(os.environ) by accident.
• Too many variables: Becomes confusing and error-prone.
• Stale values: Old credentials keep running even after rotation.

Better alternatives

For higher security or larger teams, consider:

• Encrypted .env files using dotenvx or SOPS.
• Docker Secrets in Swarm.
• Kubernetes Secrets in K8s.
• Secret managers like Infisical or HashiCorp Vault.

Key terminology

• Shell variable: Valid only in the current shell.
• Environment variable: Inherited by child processes.
• env_file: A file that loads variables.
• Secret: Sensitive data requiring special protection.
• Export: Make a variable available in the shell.

Practical example: Ollama and Open WebUI

# .env
OLLAMA_BASE_URL=http://ollama:11434
OPEN_WEBUI_PORT=8080
OPEN_WEBUI_ENABLE_SIGNUP=false

Create this file locally. Don’t include it in your Docker Compose distribution.

Further reading and resources

• BotServ.de Managing API keys securely
• BotServ.de Secret management
• BotServ.de Docker basics
• dotenvx

FAQ: Environment variables

Are .env files secure? Only if they never reach your repository and have correct permissions. For production teams, encrypted solutions are better.

How do I protect .env files? Use chmod 600 .env to make them readable only by the owner, and add them to .gitignore.

Can I encrypt environment variables in Docker Compose? Yes, using Docker Secrets, bind mounts with encrypted files, or external tools.

What happens if I commit the file to Git? Rotate all values immediately, as they’re now compromised.

Should I put all configuration in .env files? Only sensitive values and environment-specific settings. General configuration belongs in code or config files.

Sources and further reading

• OWASP Secrets Management: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
• Docker Compose Environment: https://docs.docker.com/compose/environment-variables/
• dotenvx: https://dotenvx.com/

Summary: Using environment variables securely

Environment variables and .env files provide a simple way to keep configuration and secrets separate from your codebase. They’re essential in local AI projects. The keys are correct file permissions, exclusion from Git, avoiding logs, and regular rotation. For larger or production setups, move to encrypted .env files, Docker Secrets, or dedicated secret managers.