From 8b199cfacd059a647d2f798bd116e62861c75516 Mon Sep 17 00:00:00 2001
From: j-atkins <106238905+j-atkins@users.noreply.github.com>
Date: Mon, 16 Feb 2026 14:29:22 +0100
Subject: [PATCH] add tutorial on changing file permissions on SURF

---
 docs/conf.py                                  |  1 +
 .../UU-dyoc/file_permissions.md               | 31 +++++++++++++++++++
 docs/user-guide/teacher-content/index.md      |  1 +
 3 files changed, 33 insertions(+)
 create mode 100644 docs/user-guide/teacher-content/UU-dyoc/file_permissions.md

diff --git a/docs/conf.py b/docs/conf.py
index a630f491..c93f3c5e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -84,6 +84,7 @@
     "user-guide/tutorials/surf_research_cloud_setup": "user-guide/_images/freepik_research_vessel.jpg",
     "user-guide/tutorials/working_with_expedition_yaml": "user-guide/_images/AnnaWeber.jpeg",
     "user-guide/teacher-content/UU-dyoc/example_expedition": "user-guide/_images/AnnaWeber.jpeg",
+    "user-guide/teacher-content/UU-dyoc/file_permissions": "user-guide/_images/AnnaWeber.jpeg",
 }
 
 sphinx_gallery_conf = {"default_thumb_file": "_static/virtual_ship_logo.png"}
diff --git a/docs/user-guide/teacher-content/UU-dyoc/file_permissions.md b/docs/user-guide/teacher-content/UU-dyoc/file_permissions.md
new file mode 100644
index 00000000..9317f4aa
--- /dev/null
+++ b/docs/user-guide/teacher-content/UU-dyoc/file_permissions.md
@@ -0,0 +1,31 @@
+# File Permissions on the SURF RC Virtual Machine
+
+The shared storage directory in the SURF RC virtual machine (e.g. `data/virtualship-storage/`) is configured such that all users of the workspace can read and access the files within it, but only the owner of a file can edit it. This can prevent seamless collaboration on the same expedition content, for example within your group.
+
+## How to share and edit files within the shared storage
+
+To enable collaboration on expedition content within your group, you can change the permissions of files within the shared storage directory to allow editing by all users. This can be done using the `chmod` command in the terminal (see [here](https://en.wikipedia.org/wiki/Chmod) for more detail on the `chmod` command).
+
+For example, for your `expedition.yaml` file, you can run the following command in the terminal (after navigating to your group's directory and replacing `EXPEDITION_NAME` with your actual expedition directory):
+
+```
+chmod 777 /EXPEDITION_NAME/expedition.yaml
+```
+
+This will allow _all_ users in the SURF environment to edit the `expedition.yaml` file. You can repeat this process for any other files within the shared storage that you wish to collaborate on with your group members.
+
+```{warning}
+Be careful when using `chmod 777`, as it grants read, write, and execute permissions to **all** users. This means _everyone_ who has access to the SURF environment can edit the file (i.e. the whole class), which could cause accidental changes or deletions if not used carefully. We recommend you make backups of important files before changing permissions.
+
+This is generally fine for the purposes of this unit where the virtual environment is a controlled setting, but in other contexts, it can pose security risks. Always ensure you understand the implications of changing file permissions and consider more restrictive permissions when necessary.
+
+**TL;DR the `chmod 777` command is fine for this unit, but be very careful when using it in other contexts!**
+```
+
+## Reverting the file permissions
+
+If you wish to revert the file permissions back to only allowing the owner to edit, you can run the following command in the terminal:
+
+```
+chmod 644 /EXPEDITION_NAME/expedition.yaml
+```
diff --git a/docs/user-guide/teacher-content/index.md b/docs/user-guide/teacher-content/index.md
index bdd0f95f..d6a39eb0 100644
--- a/docs/user-guide/teacher-content/index.md
+++ b/docs/user-guide/teacher-content/index.md
@@ -40,4 +40,5 @@ UU-ocean-of-future/plot_slider.py
 caption: UU Dynamical Oceanography
 ---
 UU-dyoc/example_expedition.md
+UU-dyoc/file_permissions.md
 ```