Should .environment file be in .gitignore? Is it normal to need to set environment variables in the Upsun web console in addition to having the .environment file?

• Official comment

  

  Matthias Van Woensel

  June 17, 2026 15:00

  these files, while similar naming, serve a different purpose. 

  An `.env` file is used as a place where secrets live (ideally you don't use that at all and just use true environment variables but we know many frameworks out there use this method). In any case, we completely ignore that file. It's a file used by the php app itself. Think of it like ‘desribes the app environment’
  
  An `.environment` file is actually used by the upsun containers. Think of it like ‘describes the container environment’. It loads certain things in the container, outside of the scope of the app,  like a `.bashrc` file. It will load on each cron run, each ssh into the container, and each startup of the application. `upsun init` leverages it to add some convenience into it. For example, it will create new environment variables to allow symfony applications to read and access the database. 

  ```
  # Database configuration (MariaDB via Upsun relationship)
  export DB_CONNECTION="mysql"
  export DB_HOST="$DATABASE_HOST"
  export DB_PORT="$DATABASE_PORT"
  export DB_DATABASE="$DATABASE_PATH"
  export DB_USERNAME="$DATABASE_USERNAME"
  export DB_PASSWORD="$DATABASE_PASSWORD"
  ```
  
  But you can also add extra things to this yourself. I have these in one of my apps:

   

  ```
  # Set the app URL from the Upsun routes
  if [ -n "$PLATFORM_ROUTES" ]; then
     export APP_URL=$(echo "$PLATFORM_ROUTES" | base64 --decode | jq -r 'to_entries[] | select(.value.primary == true) | .key' | head -1 | sed 's:/$::')
  fi

  # Extract the Upsun region from /etc/hosts (e.g. eu-3, eu-5, fr-3)
  export UPSUN_REGION=$(cat /etc/hosts | grep smtp | cut -d. -f8)

  ```
• 

  Stephanie Goulet

  June 17, 2026 16:19

  Thanks, Matthias.

  > true environment variables

  what do you mean? How would you make a “true environment variable”? (Are you implying a “true environment variable” is one you'd make via the Upsun web console? I'm guessing not since you mention in while talking about the .env file) 

  > php app…symfony applications

  It doesn't matter for your main point (which seems to be that .env is ignored by Upsun and .environment is what is used by Upsun) but for clarity: I'm using python/django, not php/symfony

  Still seeking answers to my original questions

  0
• 

  Michael Riley

  June 17, 2026 23:15

  Apologies for any confusion here! Environment variables can be interpreted a few different ways depending on where and how they are used.

  When working with Upsun, it helps to break environment variables down into three distinct categories:

  1. File-Based Variables (.env vs. .environment)
  While both are configuration files, they serve completely opposite purposes:

  .env File: This should only exist in your local development environment. It holds secrets like passwords and API keys, and should never be committed to your repository. Make sure this file is in your .gitignore.

  .environment File: This file is meant to be committed and deployed to Upsun, so it should not hold any secrets. It allows you to declare global, non-sensitive variables in your codebase rather than manually adding them in the Web UI. It is automatically populated by the CLI's init command and can also be manipulated by AI agents. Do not put this file in your .gitignore.

  2. Relationship Variables (Service Connections)
  For Django applications, running the Upsun init command will modify your main settings.py file to import a dedicated Upsun settings file (e.g., settings_psh.py).

  This file automatically intercepts a dynamically generated "relationship" variable containing the credentials and connection info for the service containers your application relies on (like databases or caches).

  You can see here an example of how these settings files are structured here: Upsun Django Settings Snippet (Note: While the snippet mentions Django 1, the exact same logic applies to Django 5. This app has been around a while, but it works on Django 5!).

  3. Sensitive Variables (Web UI)
  If you need to define a secret, password, or third-party API key for your remote Upsun environments, you should create a Sensitive Variable via the Upsun Web Console. Once added, these are masked (hidden from view in the UI) and are only injected into the application runtime.

  How to Access Variables in Python/Django:
  Whether a variable comes from your .environment file or a Sensitive Variable created in the console, you access it the exact same way using Python's standard library:

  
  import os

  # Fetch the variable value safely
  my_variable = os.getenv("ENVIRONMENT_VARIABLE_NAME")

  
  Hopefully, this clears up the distinction! Let me know if you run into any snags getting these wired up.

  1
• 

  Stephanie Goulet

  June 18, 2026 10:34

  Got it; thanks, Michael; that answers the questions.

  Re: the settings files – thanks for another example. I followed the documentation on Upsun so I have pretty much that with just some slight differences. As I was going through, there were some seemingly conflicting recommendations in the Upsun documentation  so I already wasn't sure about some of it though and more importantly, I'm struggling to fix the problems coming up in the deploy logs

  Gonna try again today but if I still can't figure it out, I'll make a separate post about it with questions since this post's questions were answered

  0

Please sign in to leave a comment.