Skip to content

Autodeploy unable to git pull the newer env.local file.#597

Merged
tlvu merged 4 commits intomasterfrom
fix-autodeploy-not-pulling-env.local
Oct 17, 2025
Merged

Autodeploy unable to git pull the newer env.local file.#597
tlvu merged 4 commits intomasterfrom
fix-autodeploy-not-pulling-env.local

Conversation

@tlvu
Copy link
Collaborator

@tlvu tlvu commented Oct 17, 2025

Overview

  • Autodeploy unable to git pull the newer env.local file.

    Previously the env.local file could be a symlink to a file anywhere on the
    disk.

    Now env.local can only be a symlink to a file under a folder listed in
    BIRDHOUSE_AUTODEPLOY_EXTRA_REPOS.

    This is a new restriction from the newer autodeploy docker image in the
    previous release 2.18.5 below. We can not volume-mount both the parent dir
    and the file at the same time and have write access. We can only
    volume-mount one of the two. For read-only access, it is still okay to
    volume-mount both.

Changes

Non-breaking changes

  • Fix autodeploy problem from using newer official Docker image

Breaking changes

  • None

Related Issue / Discussion

CI Operations

birdhouse_daccs_configs_branch: master
birdhouse_skip_ci: false

tlvu added 2 commits October 16, 2025 20:08
This assume the env.local file is part of
BIRDHOUSE_AUTODEPLOY_EXTRA_REPOS.

Previously, the env.local file could be a symlink to anywhere.  Now it
can only be a symlink to a file under one of the folders listed in
BIRDHOUSE_AUTODEPLOY_EXTRA_REPOS.

But the newer docker image seems to not allow both volume-mounting the
parent dir and the file at the same time.  Can only have one of the two.
@github-actions github-actions bot added documentation Improvements or additions to documentation ci/deployment Related to deployment utilities and scripts labels Oct 17, 2025
@crim-jenkins-bot
Copy link
Collaborator

E2E Test Results

DACCS-iac Pipeline Results

Build URL : http://daccs-jenkins.crim.ca:80/job/DACCS-iac-birdhouse/3738/
ResultFAILURE

BIRDHOUSE_DEPLOY_BRANCH : fix-autodeploy-not-pulling-env.local
DACCS_IAC_BRANCH : master
DACCS_CONFIGS_BRANCH : master
PAVICS_E2E_WORKFLOW_TESTS_BRANCH : master
PAVICS_SDI_BRANCH : master

DESTROY_INFRA_ON_EXIT : true
PAVICS_HOST : https://host-140-91.rdext.crim.ca

PAVICS-e2e-workflow-tests Pipeline Results

Tests URL : http://daccs-jenkins.crim.ca:80/job/PAVICS-e2e-workflow-tests/job/master/485/

NOTEBOOK TEST RESULTS
    
[2025-10-17T00:46:12.669Z] ============================= test session starts ==============================
[2025-10-17T00:46:12.669Z] platform linux -- Python 3.11.12, pytest-8.3.5, pluggy-1.5.0
[2025-10-17T00:46:12.669Z] rootdir: /home/jenkins/agent/workspace/PAVICS-e2e-workflow-tests_master@2
[2025-10-17T00:46:12.669Z] plugins: anyio-4.9.0, dash-3.0.3, nbval-0.11.0, tornasync-0.6.0.post2, xdist-3.6.1
[2025-10-17T00:46:12.669Z] collected 537 items
[2025-10-17T00:46:12.669Z] 
[2025-10-17T00:46:19.995Z] notebooks-auth/geoserver.ipynb ..................                        [  3%]
[2025-10-17T00:47:09.993Z] notebooks-auth/test_cowbird_jupyter.ipynb ..........                     [  5%]
[2025-10-17T00:47:12.136Z] notebooks-auth/test_thredds.ipynb ...........                            [  7%]
[2025-10-17T00:48:56.948Z] pavics-sdi-master/docs/source/notebooks/CaSR_basic.ipynb ......          [  8%]
[2025-10-17T01:04:51.117Z] pavics-sdi-master/docs/source/notebooks/FAQ_dask_parallel.ipynb ..s..... [  9%]
[2025-10-17T01:05:58.831Z] .                                                                        [ 10%]
[2025-10-17T01:06:04.313Z] pavics-sdi-master/docs/source/notebooks/WCS_example.ipynb ......         [ 11%]
[2025-10-17T01:06:11.636Z] pavics-sdi-master/docs/source/notebooks/WFS_example.ipynb .....          [ 12%]
[2025-10-17T01:25:26.038Z] pavics-sdi-master/docs/source/notebooks/climex.ipynb ...........         [ 14%]
[2025-10-17T01:25:26.038Z] pavics-sdi-master/docs/source/notebooks/eccc-geoapi-climate-stations.ipynb . [ 14%]
[2025-10-17T01:25:26.038Z] ...............                                                          [ 17%]
[2025-10-17T01:25:33.716Z] pavics-sdi-master/docs/source/notebooks/eccc-geoapi-xclim.ipynb .....    [ 18%]
[2025-10-17T01:25:42.842Z] pavics-sdi-master/docs/source/notebooks/esgf-dap.ipynb ....              [ 18%]
[2025-10-17T01:25:57.587Z] pavics-sdi-master/docs/source/notebooks/forecasts.ipynb ......           [ 19%]
[2025-10-17T01:26:03.506Z] pavics-sdi-master/docs/source/notebooks/opendap.ipynb .......            [ 21%]
[2025-10-17T01:26:07.994Z] pavics-sdi-master/docs/source/notebooks/pavics_thredds.ipynb .....       [ 22%]
[2025-10-17T01:28:49.505Z] pavics-sdi-master/docs/source/notebooks/regridding.ipynb ............... [ 24%]
[2025-10-17T01:29:56.786Z] .............                                                            [ 27%]
[2025-10-17T01:30:01.860Z] pavics-sdi-master/docs/source/notebooks/rendering.ipynb ....             [ 28%]
[2025-10-17T01:30:03.812Z] pavics-sdi-master/docs/source/notebooks/subset-user-input.ipynb ........ [ 29%]
[2025-10-17T01:30:32.859Z] .................                                                        [ 32%]
[2025-10-17T01:30:39.971Z] pavics-sdi-master/docs/source/notebooks/subsetting.ipynb .....           [ 33%]
[2025-10-17T01:30:41.361Z] pavics-sdi-master/docs/source/notebook-components/weaver_example.ipynb . [ 33%]
[2025-10-17T01:30:51.386Z] .........                                                                [ 35%]
[2025-10-17T01:31:02.541Z] finch-main/docs/source/notebooks/dap_subset.ipynb ...........            [ 37%]
[2025-10-17T01:31:12.532Z] finch-main/docs/source/notebooks/finch-usage.ipynb ......                [ 38%]
[2025-10-17T01:31:13.904Z] PAVICS-landing-master/content/notebooks/climate_indicators/PAVICStutorial_ClimateDataAnalysis-1DataAccess.ipynb . [ 38%]
[2025-10-17T01:31:25.473Z] .....                                                                    [ 39%]
[2025-10-17T01:33:01.922Z] PAVICS-landing-master/content/notebooks/climate_indicators/PAVICStutorial_ClimateDataAnalysis-2Subsetting.ipynb . [ 40%]
[2025-10-17T01:34:11.675Z] ............                                                             [ 42%]
[2025-10-17T01:35:33.145Z] PAVICS-landing-master/content/notebooks/climate_indicators/PAVICStutorial_ClimateDataAnalysis-3Climate-Indicators.ipynb . [ 42%]
[2025-10-17T01:36:41.939Z] .....s.                                                                  [ 43%]
[2025-10-17T01:36:50.063Z] PAVICS-landing-master/content/notebooks/climate_indicators/PAVICStutorial_ClimateDataAnalysis-4Ensembles.ipynb . [ 43%]
[2025-10-17T01:36:55.882Z] ..                                                                       [ 44%]
[2025-10-17T01:37:05.877Z] PAVICS-landing-master/content/notebooks/climate_indicators/PAVICStutorial_ClimateDataAnalysis-5Visualization.ipynb . [ 44%]
[2025-10-17T01:38:19.503Z] .........                                                                [ 46%]
[2025-10-17T01:38:29.497Z] PAVICS-landing-master/content/notebooks/climate_indicators/PAVICStutorial_ClimateDataAnalysis-6Regridding_Conversion.ipynb . [ 46%]
[2025-10-17T01:41:56.898Z] ....                                                                     [ 47%]
[2025-10-17T01:41:56.898Z] PAVICS-landing-master/content/notebooks/hydrology/PAVICStutorial_Hydrology-01_Intro.ipynb . [ 47%]
[2025-10-17T01:41:58.408Z] ....                                                                     [ 48%]
[2025-10-17T01:42:02.610Z] PAVICS-landing-master/content/notebooks/hydrology/PAVICStutorial_Hydrology-02_Calibration.ipynb . [ 48%]
[2025-10-17T01:42:12.439Z] .....                                                                    [ 49%]
[2025-10-17T01:42:16.649Z] PAVICS-landing-master/content/notebooks/hydrology/PAVICStutorial_Hydrology-03_Watershed_properties.ipynb . [ 49%]
[2025-10-17T01:42:22.328Z] .............                                                            [ 51%]
[2025-10-17T01:42:27.617Z] PAVICS-landing-master/content/notebooks/hydrology/PAVICStutorial_Hydrology-04_Time_series_analysis.ipynb . [ 51%]
[2025-10-17T01:42:28.136Z] ......                                                                   [ 53%]
[2025-10-17T01:42:45.573Z] raven-main/docs/source/notebooks/Region_selection.ipynb .........        [ 54%]
[2025-10-17T01:42:47.478Z] raven-main/docs/source/notebooks/Subset_climate_data_over_watershed.ipynb . [ 54%]
[2025-10-17T01:43:09.471Z] ......                                                                   [ 56%]
[2025-10-17T01:43:11.371Z] RavenPy-main/docs/notebooks/00_Introduction_to_JupyterLab.ipynb ......   [ 57%]
[2025-10-17T01:43:24.143Z] RavenPy-main/docs/notebooks/01_Getting_watershed_boundaries.ipynb ...... [ 58%]
[2025-10-17T01:43:24.143Z] ..                                                                       [ 58%]
[2025-10-17T01:43:30.715Z] RavenPy-main/docs/notebooks/02_Extract_geographical_watershed_properties.ipynb . [ 58%]
[2025-10-17T01:43:36.486Z] .............                                                            [ 61%]
[2025-10-17T01:45:31.450Z] RavenPy-main/docs/notebooks/03_Extracting_forcing_data.ipynb ........... [ 63%]
[2025-10-17T01:45:31.450Z]                                                                          [ 63%]
[2025-10-17T01:45:35.675Z] RavenPy-main/docs/notebooks/04_Emulating_hydrological_models.ipynb ..... [ 64%]
[2025-10-17T01:45:42.013Z] ...............                                                          [ 67%]
[2025-10-17T01:45:47.872Z] RavenPy-main/docs/notebooks/05_Advanced_RavenPy_configuration.ipynb .... [ 67%]
[2025-10-17T01:45:55.892Z] .........                                                                [ 69%]
[2025-10-17T01:46:08.030Z] RavenPy-main/docs/notebooks/06_Raven_calibration.ipynb ......            [ 70%]
[2025-10-17T01:46:15.528Z] RavenPy-main/docs/notebooks/07_Making_and_using_hotstart_files.ipynb ... [ 71%]
[2025-10-17T01:46:18.116Z] ...                                                                      [ 71%]
[2025-10-17T01:46:23.393Z] RavenPy-main/docs/notebooks/08_Getting_and_bias_correcting_CMIP6_data.ipynb . [ 71%]
[2025-10-17T01:54:29.218Z] ...............                                                          [ 74%]
[2025-10-17T01:54:34.507Z] RavenPy-main/docs/notebooks/09_Hydrological_impacts_of_climate_change.ipynb . [ 74%]
[2025-10-17T01:54:41.085Z] ....                                                                     [ 75%]
[2025-10-17T01:55:24.744Z] RavenPy-main/docs/notebooks/10_Data_assimilation.ipynb ........          [ 77%]
[2025-10-17T01:55:34.073Z] RavenPy-main/docs/notebooks/11_Climatological_ESP_forecasting.ipynb .... [ 77%]
[2025-10-17T01:56:00.286Z] ....                                                                     [ 78%]
[2025-10-17T01:56:08.415Z] RavenPy-main/docs/notebooks/12_Performing_hindcasting_experiments.ipynb . [ 78%]
[2025-10-17T01:56:19.645Z] .......                                                                  [ 80%]
[2025-10-17T01:56:44.872Z] RavenPy-main/docs/notebooks/Assess_probabilistic_flood_risk.ipynb ...... [ 81%]
[2025-10-17T01:56:46.071Z] .                                                                        [ 81%]
[2025-10-17T01:56:56.068Z] RavenPy-main/docs/notebooks/Comparing_hindcasts_and_ESP_forecasts.ipynb . [ 81%]
[2025-10-17T01:57:16.851Z] .......                                                                  [ 82%]
[2025-10-17T01:57:23.429Z] RavenPy-main/docs/notebooks/Distributed_hydrological_modelling.ipynb ... [ 83%]
[2025-10-17T01:57:40.218Z] ....                                                                     [ 84%]
[2025-10-17T01:57:51.908Z] RavenPy-main/docs/notebooks/Hydrological_realtime_forecasting.ipynb .... [ 84%]
[2025-10-17T01:57:58.116Z] ..                                                                       [ 85%]
[2025-10-17T01:58:21.435Z] RavenPy-main/docs/notebooks/Managing_Jupyter_Environments.ipynb ...      [ 85%]
[2025-10-17T01:58:54.841Z] RavenPy-main/docs/notebooks/Perform_Regionalization.ipynb .......        [ 87%]
[2025-10-17T01:58:59.510Z] RavenPy-main/docs/notebooks/Running_HMETS_with_CANOPEX_dataset.ipynb ... [ 87%]
[2025-10-17T01:59:16.898Z] ..........                                                               [ 89%]
[2025-10-17T01:59:39.897Z] RavenPy-main/docs/notebooks/Sensitivity_analysis.ipynb ......            [ 90%]
[2025-10-17T01:59:45.404Z] RavenPy-main/docs/notebooks/time_series_analysis.ipynb ...........       [ 92%]
[2025-10-17T01:59:53.514Z] RavenPy-main/docs/notebooks/paper/Perform_a_climate_change_impact_study_on_a_watershed.ipynb . [ 92%]
[2025-10-17T02:04:34.295Z] .............Fxxxxxx                                                     [ 96%]
[2025-10-17T02:04:34.295Z] notebooks/hummingbird.ipynb ............                                 [ 98%]
[2025-10-17T02:07:04.516Z] notebooks/stress-tests.ipynb ......                                      [100%]
[2025-10-17T02:07:04.516Z] 
[2025-10-17T02:07:04.516Z] =================================== FAILURES ===================================
    
  

Copy link
Member

@fmigneault fmigneault left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me, but I am not a user of autodeploy, so maybe better to double check with @mishaschwartz

@tlvu
Copy link
Collaborator Author

tlvu commented Oct 17, 2025

@mishaschwartz feel free to comment again on this PR and if anything we can open a follow up PR to address your concerns.

However I will have to merge this PR now because this is blocking Ouranos from catching up with tip of this repo in production.

@github-actions github-actions bot added the ci/operations Continuous Integration components label Oct 17, 2025
@tlvu tlvu merged commit 3e00782 into master Oct 17, 2025
4 of 5 checks passed
@tlvu tlvu deleted the fix-autodeploy-not-pulling-env.local branch October 17, 2025 16:13
@mishaschwartz
Copy link
Collaborator

mishaschwartz commented Oct 20, 2025

I also don't use autodeploy but I have a few questions:

  • why do we need read access to the env.local file? What needs to be able to write to it?
  • why not just volume mount BIRDHOUSE_LOCAL_ENV_REAL_PATH to the location of BIRDHOUSE_LOCAL_ENV in the container.
  • why did you remove the volume mount of BIRDHOUSE_LOCAL_ENV? Won't that just mean that the container can't find the local env file at all?

Unless I'm missing something I've very confused about this fix.

@tlvu
Copy link
Collaborator Author

tlvu commented Oct 21, 2025

  • why do we need read access to the env.local file? What needs to be able to write to it?

Autodeploy is a 2 stages process.

First stage is to check whether any repos need to be updated. This needs to read env.local for BIRDHOUSE_AUTODEPLOY_EXTRA_REPOS in order to have this list of repos to check.

Second stage is actually performing the autodeploy (stop the full stack, git pull all the repos, restart the full stack).

This second stage is skipped if no repo needs update. If this stage is actually triggered, to stop/start it uses birdhouse-compose.sh which needs env.local as you are all familiar with and to git pull the newer version of env.local, autodeploy will need write access to env.local.

  • why not just volume mount BIRDHOUSE_LOCAL_ENV_REAL_PATH to the location of BIRDHOUSE_LOCAL_ENV in the container.

We never had the need because when volume-mounting a symlink, it actually follow the link and volume-mount the real path already. The not writable error I got is actually for the real path.

  • why did you remove the volume mount of BIRDHOUSE_LOCAL_ENV? Won't that just mean that the container can't find the local env file at all?

Because the repo that contain env.local is already volume-mount entirely so autodeploy can git pull it.

Recall this is the recommanded layout if env.local is sourced-controlled:

Suggested deployment layout:
.. code-block::
├── birdhouse-deploy/ # this repo
│   ├── bin/
│   │   ├── birdhouse
│   ├── birdhouse/
│   │   ├── env.local # relative symlink to env.local.real below
│   │   ├── (...)
├── private-config/ # your private config and override: sibling level of this repo
│   ├── docker-compose-extra.yml
│   ├── env.local.real
│   ├── .git/

And we suggest in env.local.example to add that repo containing env.local to BIRDHOUSE_AUTODEPLOY_EXTRA_REPOS:

#export BIRDHOUSE_AUTODEPLOY_EXTRA_REPOS="/path/to/private-config-containing-env.local"

And in the autodeploy scheduler job we volume-mount all repos in the var BIRDHOUSE_AUTODEPLOY_EXTRA_REPOS:

export BIRDHOUSE_AUTODEPLOY_EXTRA_REPOS_AS_DOCKER_VOLUMES='$(for d in ${BIRDHOUSE_AUTODEPLOY_EXTRA_REPOS}; do printf " --volume %s:%s:rw " "$d" "$d"; done)'

- name: autodeploy
comment: Auto-deploy entire Birdhouse platform
schedule: '${BIRDHOUSE_AUTODEPLOY_PLATFORM_FREQUENCY}'
command: '${COMPOSE_DIR}/deployment/triggerdeploy.sh ${COMPOSE_DIR}'
dockerargs: >-
--rm --name autodeploy${BIRDHOUSE_AUTODEPLOY_EXTRA_REPOS_AS_DOCKER_VOLUMES}

So basically we were double volume-mounting the folder containing env.local and env.local itself. With the older version of docker-cli it looks like less strict and let this slide. Now the newer version, if you double mount, you can have read-only access but not write access ! So in order to have write access, I need to remove one of the two volume-mount !

Unless I'm missing something I've very confused about this fix.

Yes it took me a while to get this too because I could not understand why this suddenly do not work. I rebooted my VM twice thinking something got stuck on my VM. Then I had to reproduce on another VM to be sure it's not my first VM that suddenly gone mad.

@mishaschwartz
Copy link
Collaborator

OK I understand how this specifically fixes things for PAVICS now but this change will still break things for anyone else that is using a more conventional structure where env.local is not symlinked.

No one else as far as I know is using the autodeploy but if the code for it is in this repo then I don't want to force people to use a very specific PAVICS-oriented setup to run it.

There is no need for env.local to be a symlink since you can specify the real location of the local environment file with a command line option or an environment variable. So I think it would be unusual for a node to be set up in that way going forward.

I'm also concerned that you're putting your env.local.real under source control since it contains all sorts of credentials, secrets, and passwords for various services. At the very least I hope the upstream repo is local to your network and is encrypted in some way (and not on github for example).

I think it's a major security issue to encourage users (in the documentation) to put their local environment file under source control at all.

Here is what I would suggest.... this should work for both your setup and anyone else's who is not symlinking env.local to a repository:

# in birdhouse/optional-components/scheduler-job-autodeploy/config.yml.template

--volume ${BIRDHOUSE_LOCAL_ENV_REAL_PATH}:/tmp/birdhouse-local-env
--env BIRDHOUSE_LOCAL_ENV=/tmp/birdhouse-local-env

In your case, when the env.local.real file is updated (with a git pull), the file in the container that is mounted to /tmp/birdhouse-local-env will also be updated.

Since that file is mounted under /tmp (and presumably the repo containing env.local.real is not mounted to /tmp) you will not have the issue of nested mount-points on the container.

@tlvu
Copy link
Collaborator Author

tlvu commented Oct 21, 2025

this change will still break things for anyone else that is using a more conventional structure where env.local is not symlinked.

The current checkout of birdhouse-compose is not in BIRDHOUSE_AUTODEPLOY_EXTRA_REPOS because it is always volume-mount by default, which means if env.local is not a symlink, it will already be part of the default volume-mount.

- name: autodeploy
comment: Auto-deploy entire Birdhouse platform
schedule: '${BIRDHOUSE_AUTODEPLOY_PLATFORM_FREQUENCY}'
command: '${COMPOSE_DIR}/deployment/triggerdeploy.sh ${COMPOSE_DIR}'
dockerargs: >-
--rm --name autodeploy${BIRDHOUSE_AUTODEPLOY_EXTRA_REPOS_AS_DOCKER_VOLUMES}
--volume /var/run/docker.sock:/var/run/docker.sock:ro
--volume ${BIRDHOUSE_LOG_DIR}:${BIRDHOUSE_LOG_DIR}:rw
--volume ${COMPOSE_DIR}/..:${COMPOSE_DIR}/..:rw

There is no need for env.local to be a symlink since you can specify the real location of the local environment file with a command line option or an environment variable. So I think it would be unusual for a node to be set up in that way going forward.

I thought allowing env.local path to be set by env var BIRDHOUSE_LOCAL_ENV was just for testing and you want to keep this ability hidden? You said it yourself here #304 (comment) !

I'm also concerned that you're putting your env.local.real under source control since it contains all sorts of credentials, secrets, and passwords for various services. At the very least I hope the upstream repo is local to your network and is encrypted in some way (and not on github for example).

Exactly, this 100% private is on our local source control, not on the internet.

Are you suggesting we should add a reminder next to our recommendation to source-control env.local to remind the users to not put that on the internet? I thought that was a given, but better be safe than sorry I guess. It's a good suggestion.

I think it's a major security issue to encourage users (in the documentation) to put their local environment file under source control at all.

If env.local is not source controlled

  1. How do you track changes to it, because it contains many many configs that impact each other. Sometime just the ordering matter. You can insert something new that legit, but at the wrong place, and breaks the entire stack. It's important to be able to go back.
  2. You won't have full autodeploy experience. Right now, unless I am adding a new external repo which I need to perform a checkout, looking up the logs, updating the docker engine or the OS, I don't really have to touch the stack. New commits to this birdhouse-deploy, or any of the external repos, new commits to the env.local that override any configs, enabled new components, etc, can all be handled by autodeploy. Given all these activities are driven by commits, it is fully traceable if something goes wrong and I can reproduce exactly the same setup on another machine for debugging/testing.

Here is what I would suggest.... this should work for both your setup and anyone else's who is not symlinking env.local to a repository:

# in birdhouse/optional-components/scheduler-job-autodeploy/config.yml.template

--volume ${BIRDHOUSE_LOCAL_ENV_REAL_PATH}:/tmp/birdhouse-local-env
--env BIRDHOUSE_LOCAL_ENV=/tmp/birdhouse-local-env

In your case, when the env.local.real file is updated (with a git pull), the file in the container that is mounted to /tmp/birdhouse-local-env will also be updated.

Since that file is mounted under /tmp (and presumably the repo containing env.local.real is not mounted to /tmp) you will not have the issue of nested mount-points on the container.

This is a good suggestion, I can give it a try. Hopefully it solves our nested mount-points problem and not create new problems because we are overriding BIRDHOUSE_LOCAL_ENV when the original user also override BIRDHOUSE_LOCAL_ENV from its default value !

@mishaschwartz
Copy link
Collaborator

The current checkout of birdhouse-compose is not in BIRDHOUSE_AUTODEPLOY_EXTRA_REPOS because it is always volume-mount by default, which means if env.local is not a symlink, it will already be part of the default volume-mount.

That's only true if it is in the ${COMPOSE_DIR}/.. directory which is not necessarily the case.

I thought allowing env.local path to be set by env var BIRDHOUSE_LOCAL_ENV was just for testing and you want to keep this ability hidden?

The environment variable is meant to be used internally yes, but that variable is set when you run bin/birdhouse --env-file some-other-env.local which is part of the public interface and is meant to be used by the user.

Exactly, this 100% private is on our local source control, not on the internet.

Nice!

Are you suggesting we should add a reminder next to our recommendation to source-control env.local to remind the users to not put that on the internet?

Yeah I think that's a good idea. I think that there's a very good chance that people automatically think that if it's a git repository then it's hosted by github/gitlab/bitbucket etc.

How do you track changes to it

Daily backups with the backup scheduler job!!

You won't have full autodeploy experience

True, but in my case I could get most of that with backups and scheduled manual updates. I see the advantages you describe I just also see the risks if you don't secure the credentials in env.local properly. It's always a trade-off.

and not create new problems because we are overriding BIRDHOUSE_LOCAL_ENV when the original user also override BIRDHOUSE_LOCAL_ENV from its default value

It shouldn't because BIRDHOUSE_LOCAL_ENV_REAL_PATH is derived from BIRDHOUSE_LOCAL_ENV and is guaranteed not to be a symlink.

@tlvu
Copy link
Collaborator Author

tlvu commented Oct 21, 2025

The current checkout of birdhouse-compose is not in BIRDHOUSE_AUTODEPLOY_EXTRA_REPOS because it is always volume-mount by default, which means if env.local is not a symlink, it will already be part of the default volume-mount.

That's only true if it is in the ${COMPOSE_DIR}/.. directory which is not necessarily the case.

Sorry I meant when the env.local is at default location.

I thought allowing env.local path to be set by env var BIRDHOUSE_LOCAL_ENV was just for testing and you want to keep this ability hidden?

The environment variable is meant to be used internally yes, but that variable is set when you run bin/birdhouse --env-file some-other-env.local which is part of the public interface and is meant to be used by the user.

Oh ! I didn't register that new option --env-file existed on bin/birdhouse sorry. Still using birdhouse-compose.sh for day to day. But then how do you persist this? When using an alternate env.local, the user will always have to remember to use --env-file option all the time on the command-line?

The symlink is actually the way to "persist" this override value.

and not create new problems because we are overriding BIRDHOUSE_LOCAL_ENV when the original user also override BIRDHOUSE_LOCAL_ENV from its default value

It shouldn't because BIRDHOUSE_LOCAL_ENV_REAL_PATH is derived from BIRDHOUSE_LOCAL_ENV and is guaranteed not to be a symlink.

I am not talking about BIRDHOUSE_LOCAL_ENV_REAL_PATH, I am talking about the value of BIRDHOUSE_LOCAL_ENV that user choose to override and now we will also override on top of the original user override !

And there is the question of persistence of the override of BIRDHOUSE_LOCAL_ENV. Currently all config var overrides are persisted in env.local so they can be shared with any scripts, including autodeploy.

Obviously we can not persist BIRDHOUSE_LOCAL_ENV in env.local itself !

How can this new value of BIRDHOUSE_LOCAL_ENV be shared to all scripts outside of bin/birdhouse? Well, bin/birdhouse don't even know this new value, it requires the user to supply the new value via --env-file on each invocation?

@mishaschwartz
Copy link
Collaborator

Still using birdhouse-compose.sh for day to day. But then how do you persist this?

I really recommend you start using bin/birdhouse. We made that script to be the interface for the stack. If you're using something else things may change for you when the stack updates. But that is unrelated to the current discussion...

But then how do you persist this?

Well there are a few usual strategies for this...

  1. you put your local env in a default location
  2. your automation script calls the command line option with the location of the local env
  3. you put a symlink to the file in a default location (your current strategy)

Note that the scheduler job is essentially doing strategy 2. It notes the location of the local env file when the stack is first started up and saves that location (by writing a template file) for the scheduler job to use.

I thought allowing env.local path to be set by env var BIRDHOUSE_LOCAL_ENV was just for testing and you want to keep this ability hidden? You said it yourself here #304 (comment)

I think a lot of your issues could be solved if you used this environment variable and put it in your .profile or .bashrc file so you wouldn't have to worry about symlinking. In my comment, I said that we should keep it private "for now" but I think that this is a good use case for documenting it and making it public so that you can comfortably use it in your workflow.

However, the strategies that I mentioned above also solve the "persistence" problem that you mentioned.

@tlvu
Copy link
Collaborator Author

tlvu commented Oct 22, 2025

Still using birdhouse-compose.sh for day to day. But then how do you persist this?

I really recommend you start using bin/birdhouse.

Eventually yes. I have many external scripts and components that uses birdhouse-compose.sh so they all have to transition before I can switch.

That's pretty low on my list. Right now I want to go to prod with tip of BH and there is #593 and #598 blocking me. Then after that I want all the new metrics and longterm metrics storage to work.

But then how do you persist this?

Well there are a few usual strategies for this...

1. you put your local env in a default location

2. your automation script calls the command line option with the location of the local env

3. you put a symlink to the file in a default location (your current strategy)

Note that the scheduler job is essentially doing strategy 2. It notes the location of the local env file when the stack is first started up and saves that location (by writing a template file) for the scheduler job to use.

The scheduler job can save the location of the local env file when the stack is first started up because it has a job to save to ! Not all scripts have this availability (no jobs associated) or does this explicitly in their job. So option 2 is not a 100% foolproof, option 3 is. Once the symlink is there, it is completely transparent to any scripts or jobs authors.

I thought allowing env.local path to be set by env var BIRDHOUSE_LOCAL_ENV was just for testing and you want to keep this ability hidden? You said it yourself here #304 (comment)

I think a lot of your issues could be solved if you used this environment variable and put it in your .profile or .bashrc file so you wouldn't have to worry about symlinking.

Setting BIRDHOUSE_LOCAL_ENV in .profile or .bashrc is another option for persistence but that means one single checkout of birdhouse-deploy on a machine. The symlink trick is more flexible, each checkout can have their symlink. This could be an option if user want to avoid symlink, which I do not see why for the moment.

So I guess we can use bin/birdhouse --env-file to quickly test out multiples variants of env.local but the "default" env.local should have the symlink point to it to facilitate usage by other scripts/components, etc. Is this a reasonable conclusion?

@mishaschwartz
Copy link
Collaborator

I get what you're saying but I think we're getting a bit side tracked here. My point is just this:

Your set-up is a good, valid use-case. I'm not asking you to change how you have things set up.
But, the change you made in this PR breaks things for others that set things up differently from you.

Please see if the change I suggested also works for you so that we can support your use-case as well as others. Here is my suggestion again:

# in birdhouse/optional-components/scheduler-job-autodeploy/config.yml.template

--volume ${BIRDHOUSE_LOCAL_ENV_REAL_PATH}:/tmp/birdhouse-local-env
--env BIRDHOUSE_LOCAL_ENV=/tmp/birdhouse-local-env

@tlvu
Copy link
Collaborator Author

tlvu commented Oct 23, 2025

But, the change you made in this PR breaks things for others that set things up differently from you.

Yes I will for sure try what you suggest. If being able to support both methods (the symlink and BIRDHOUSE_LOCAL_ENV override) is the best scenario.

What I am trying to say is BIRDHOUSE_LOCAL_ENV override is not the most transparent solution unless there is somehow a reason why the symlink solution can not be used. Currently overriding BIRDHOUSE_LOCAL_ENV is used during testing scenarios and that's fine. For production use, the symlink solution should be used as it is more transparent and compatible with a wider range of external scripts and jobs.

@mishaschwartz
Copy link
Collaborator

For production use, the symlink solution should be used as it is more transparent and compatible with a wider range of external scripts and jobs.

That is a choice that PAVICS can make but should not be dictated to all users. Your use-case is not the only valid use-case.

tlvu added a commit that referenced this pull request Oct 23, 2025
@tlvu
Copy link
Collaborator Author

tlvu commented Oct 23, 2025

dictated to all users

Woo, if I was dictating my choice, I would have remove that variable ! I think you are mis-understanding here.

I am simply saying between the 2 approaches, the symlink one is more transparent and compatible with wider range of external scripts and jobs.

tlvu added a commit that referenced this pull request Nov 10, 2025
…loy raven and xclim testdata missing logs (#601)

## Overview

### Changes

- scheduler-job-autodeploy: make compatible with change of
`BIRDHOUSE_LOCAL_ENV` via env var and not symlink

See
#597 (comment).

### Fixes

- scheduler-jobs: fix deploy raven and xclim testdata missing logs,
forgot delayed eval

## CI Operations

<!--
The test suite can be run using a different DACCS config with
``birdhouse_daccs_configs_branch: branch_name`` in the PR description.
To globally skip the test suite regardless of the commit message use
``birdhouse_skip_ci`` set to ``true`` in the PR description.

Using ``[<cmd>]`` (with the brackets) where ``<cmd> = skip ci`` in the
commit message will override ``birdhouse_skip_ci`` from the PR
description.
Such commit command can be used to override the PR description behavior
for a specific commit update.
However, a commit message cannot 'force run' a PR which the description
turns off the CI.
To run the CI, the PR should instead be updated with a ``true`` value,
and a running message can be posted in following PR comments to trigger
tests once again.
-->

birdhouse_daccs_configs_branch: master
birdhouse_skip_ci: false
tlvu added a commit that referenced this pull request Nov 27, 2025
…as env var again"

This reverts commit a1f649f.

Have error 'error: unable to unlink old 'env.local': Resource busy' in autodeploy.log.

Even if `env.local` is not physically in `COMPOSE_DIR`, its parent dir
is still in the list of `BIRDHOUSE_AUTODEPLOY_EXTRA_REPOS` so we again
have the same problem describe in
#597 (comment)
where double volume-mounting the folder containing `env.local` and
`env.local` itself is not allowed for write-access (readonly-access is
fine) since the newer Docker image.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci/deployment Related to deployment utilities and scripts ci/operations Continuous Integration components documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants