March 9, 20251 yr TL;DR: Looking for a method to properly use environment variables/secrets in Unraid containers, specifically for Homepage but also as a general solution for the containers I am using. Considering migrating to Docker Compose with Portainer if that's a better approach. Current Setup Unraid Version: 7.0.1 Container Focus: Homepage (container template installed via Community CA) Container Path: /mnt/user/appdata/homepage Total Containers: 26 running containers The Problem I need to securely store and use API keys and sensitive URLs for my Homepage container, as well as other containers in my environment. According to the Homepage Docker Environment Secrets documentation, I should be able to: Create a .env file in my /mnt/user/appdata/homepage folder Define variables like HOMEPAGE_VAR_APIKEY=my_secret_key Reference them in my config with {{HOMEPAGE_VAR_APIKEY}} However, these variables aren't being evaluated properly, resulting in non-functional URLs and services. What I've Already Tried Created a .env file in correct location with proper syntax passed that .env file into the container using a ENV_FILE attribute with a value of /mnt/user/appdata/homepage/.env this was based on Docker documentation on env_file attribute, but this appears to be for Docker Compose context Verified file permissions on the .env file Double-checked the variable reference syntax in my config files Searched container logs for any environment variable errors adding a extra parameter to the container of --env-file /mnt/user/appdata/homepage/.env Questions Homepage Specific: Has anyone successfully used environment variables/secrets with Homepage in Unraid? How? General Unraid Question: Is there a standard way to use an environment file (like .env) with Unraid's built-in container management? Container Settings: Do I need to modify specific settings in the Unraid UI to point to an env file? Alternative Approach: Would switching to Docker Compose / Docker Compose Manager with an orchestration tool like Portainer be a better solution for managing environment variables across all my containers? Request for Examples If you've found a reusable method to use environment variables in your Unraid Docker setup, would you mind sharing: A redacted example of your container configuration How you've structured your environment variables How you reference them in your container settings Migration Consideration I'm considering switching to Docker Compose with Portainer to take advantage of the more standardized approach to environment variables. If you've made this switch: Was it worth the effort? Any unforeseen issues with Unraid? Any tips for a smooth transition? Thank you for your help! Edited March 9, 20251 yr by gvns
March 9, 20251 yr Community Expert Solution 1 hour ago, gvns said: adding a extra parameter to the container of --env-file /mnt/user/appdata/homepage/.env This is all you need to do, but you need to restart... or possibly force update (rebuild) the container for the envs to stick. note: I've explicitly stated /mnt/cache, but /mnt/user is fine. Edited March 9, 20251 yr by tjb_altf4
March 9, 20251 yr Author 42 minutes ago, tjb_altf4 said: This is all you need to do, but you need to restart... or possibly force update (rebuild) the container for the envs to stick. Ooh, I think you may be right... though I have not yet been able to get this rebuild to work. I am about to remove and reinstall and see where that gets me.
March 9, 20251 yr Author 3 hours ago, tjb_altf4 said: - Alllright, so I think what I already had did work - or should have. I nuked and reinstalled Homepage and my same --env-file /mnt/cache/appdata/homepage/.env extra parameter, as you described, worked. At first I thought I was missing an equal sign, eg. --env-file=/mnt/cache/appdata/homepage/.env - but that did not seem to make the difference. I am still not certain what specifically prevented my previous setup from working, however, I can confirm that Homepage is respecting my environment variables from a .env at /mnt/cache/appdata/homepage/.env Anyways, thanks!
March 22, 20251 yr I have tried restarting, removing the image and reinstalling (rebuilding) - I can get this to work for SOME services but not all. I'm mainly just using the env variables for passwords and API keys. I'm getting API data for Plex and two Piholes. It's not pulling it in for Portainer or Proxmox nodes I have running (I am able to get the data when the PW/key is hardcoded in the services.yaml file). What is the expected behavior? Do you need to just rebuild one time so Homepage uses the .env file and then you can just add variables to it and it will see them dynamically? Or would I have to restart Homepage each time I add a new variable? Or would I need to REBUILD each time I add a new variable? Is there some sort of cache storing things so the updated keys take a while to work? I'm just at a loss why some key variables from the .env file work and some do not. I have allowed tired with/without single and double quotes around the keys with special characters, to no avail. (Notably, one PW with a ! in it works fine without any quotes around it.)
March 31, 20251 yr Author Good question(s), @aeisan. I have not found much in terms of what "expected" behaviour is in terms of how Unraid docker management handles environment variables it its Docker engine. To answer your question, I do not believe a rebuild is necessary for env variables to be read and substituted by the Docker engine. I believe they are "read" at runtime, though I do not fully understand how. I see this was just over a week ago, did you get anywhere further?
Join the conversation
You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.