Jupyterhub: update recommended paths for public share folders (#481)

## Overview
 
The recommended public share folders in the `env.local.example` file
create a conflict with the default `PUBLIC_WORKSPACE_WPS_OUTPUTS_SUBDIR`
path when both are enabled and mounted on a Jupyterlab container. This
change updates the recommended paths for the public share folders to
avoid this conflict and adds a warning helping users to avoid this
conflict.

Note: the conflict arises when `PUBLIC_WORKSPACE_WPS_OUTPUTS_SUBDIR` is
mounted to a container as read-only volume and then Jupyterhub tries to
mount the public share folder within that volume. Since the parent
volume is read-only, the second volume mount fails.

## Changes

**Non-breaking changes**
None, documentation only

**Breaking changes**
None

## Related Issue / Discussion

- Resolves #392

## Additional Information

Links to other issues or sources.

## 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

CHANGES.md

@@ -21,6 +21,18 @@
 
   Update description of the `configs` subcommand to better describe it.
   The description when calling `bin/birdhouse -h` now matches the description when calling `bin/birdhouse configs -h`
+
+- Jupyterhub: Update recommended paths for public share folders
+
+  The recommended public share folders in the `env.local.example` file create a conflict with the default
+  `PUBLIC_WORKSPACE_WPS_OUTPUTS_SUBDIR` path when both are enabled and mounted on a Jupyterlab container.
+  This change updates the recommended paths for the public share folders to avoid this conflict and adds a
+  warning helping users to avoid this conflict.
+
+  Note: the conflict arises when `PUBLIC_WORKSPACE_WPS_OUTPUTS_SUBDIR` is mounted to a container as read-only
+  volume and then Jupyterhub tries to mount the public share folder within that volume. Since the parent volume
+  is read-only, the second volume mount fails.
+
 
 [2.6.1](https://github.com/bird-house/birdhouse-deploy/tree/2.6.1) (2024-11-22)
 ------------------------------------------------------------------------------------------------------------------

birdhouse/env.local.example

@@ -388,8 +388,8 @@ export GEOSERVER_ADMIN_PASSWORD="${__DEFAULT__GEOSERVER_ADMIN_PASSWORD}"
 ## /data/jupyterhub_user_data/public-share/
 #public_read_on_disk = join(jupyterhub_data_dir, 'public-share')
 #
-## /notebook_dir/public/
-#public_read_in_container = join(notebook_dir, 'public')
+## /notebook_dir/public-share/
+#public_read_in_container = join(notebook_dir, 'public-share')
 #
 #c.DockerSpawner.volumes[public_read_on_disk] = {
 #    'bind': public_read_in_container,
@@ -401,14 +401,17 @@ export GEOSERVER_ADMIN_PASSWORD="${__DEFAULT__GEOSERVER_ADMIN_PASSWORD}"
 ## /data/jupyterhub_user_data/public-share/{username}-public
 #public_share_on_disk = join(public_read_on_disk, '{username}-public')
 #
-## /notebook_dir/mypublic
-#public_share_in_container = join(notebook_dir, 'mypublic')
+## /notebook_dir/mypublic-share
+#public_share_in_container = join(notebook_dir, 'mypublic-share')
 #
 #c.DockerSpawner.volumes[public_share_on_disk] = {
 #    'bind': public_share_in_container,
 #    'mode': 'rw',
 #}
 #
+## If enabling the public-share paths above, make sure that the paths in the container don't conflict
+## with the PUBLIC_WORKSPACE_WPS_OUTPUTS_SUBDIR path.
+#
 ### create dir with proper permissions
 #
 #def custom_create_dir_hook(spawner):