Add basic documentation for admins

Author: mvdbeek

doc/source/admin/index.rst

@@ -26,6 +26,7 @@ This documentation is in the midst of being ported and unified based on resource
    dependency_resolvers
    container_resolvers
    conda_faq
+   user_defined_tools
    db_migration
    reports
    useful_scripts

doc/source/admin/user_defined_tools.md

@@ -0,0 +1,102 @@
+# User-Defined Tools (Beta)
+
+Starting with Galaxy 25.0, users can create their own tools without requiring administrator privileges to install them. These tools are written in YAML, defined through the Galaxy user interface, and stored in the database.
+
+## Differences from Standard Galaxy Tools
+
+Standard Galaxy tools are written in XML and have broad access to the Galaxy database and filesystem during the command and configuration file templating phase, which uses the Cheetah templating language.
+
+For example, the following XML tool command section queries the Galaxy database and writes a file to the home directory of the system user running the Galaxy process:
+
+```xml
+<command><![CDATA[
+    #from pathlib import Path
+    #user_id = $__app__.model.session().query($__app__.model.User.id).one()
+    #open(f"{Path.home()}/a_file", "w").write("Hello!")
+]]></command>
+```
+
+This level of access is acceptable when only administrators install tools. However, allowing regular users to define and execute arbitrary tools requires stricter controls.
+
+To address this, Galaxy now supports a restricted tool language for user-defined tools. This format is modeled after the XML tool definition but replaces Cheetah templating with sandboxed JavaScript expressions that do not have access to the database or filesystem.
+
+Example: Concatenate Files Tool (YAML)
+```yaml
+class: GalaxyUserTool
+id: cat_user_defined
+version: "0.1"
+name: Concatenate Files
+description: tail-to-head
+container: busybox
+shell_command: |
+  cat $(inputs.datasets.map((input) => input.path).join(' ')) > output.txt
+inputs:
+  - name: datasets
+    multiple: true
+    type: data
+outputs:
+  - name: output1
+    type: data
+    format_source: datasets
+    from_work_dir: output.txt
+```
+
+Equivalent Tool in XML:
+```xml
+<tool id="cat" version="0.1">
+    <description>tail-to-head</description>
+    <requirements>
+        <requirement type="container">busybox</requirement>
+    </requirements>
+    <command><![CDATA[
+cat
+#for dataset in datasets:
+    '$dataset'
+#end for
+> '$output1'
+    ]]></command>
+    <inputs>
+        <input name="datasets" format="data" type="data" multiple="true"/>
+    </inputs>
+    <outputs>
+        <output name="output1" format_source="datasets" />
+    </outputs>
+</tool>
+```
+
+While the structure is similar, several key differences exist:
+
+- The YAML version includes a required `class: GalaxyUserTool` line to signal the use of the restricted `UserToolSource` schema.
+- All user-defined tools must be executed inside a container, specified using the `container` key.
+- The command to be executed is defined under the `shell_command` key, using a string with embedded JavaScript expressions inside $(). In the example above, the expression iterates over the input dataset paths and joins them into a single command string.
+
+## Enabling User-Defined Tools
+
+To enable this feature:
+
+1. Set `enable_beta_tool_formats: true` in your Galaxy configuration.
+2. Create a role of type `Custom Tool Execution` in the admin user interdace.
+3. Assign users or groups to this role.
+
+## Sharing User-Defined Tools
+
+User-defined tools are private to their creators. However, if a tool is embedded in a workflow, any user who imports that workflow will automatically have the tool created in their account.
+
+These tools can also be exported to disk and loaded like regular tools, enabling instance-wide availability if needed.
+
+## Security considerations
+
+User-defined tools share the same security risks as interactive tools..
+See https://training.galaxyproject.org/training-material/topics/admin/tutorials/interactive-tools/tutorial.html#securing-interactive-tools for an extended discussion.
+While the feature is in beta we recommend that only trusted users are allowed to use this feature.
+
+## Limitations
+
+The user-defined tool language is still evolving, and additional safety audits are ongoing.
+
+Current limitations include:
+
+- [configfiles](https://docs.galaxyproject.org/en/master/dev/schema.html#tool-configfiles) are not supported
+- Access to reference data is not supported
+- Access to metadata and metadata files (such as BAM indexes) is not supported
+- Access to the `extra_files` directory is not supported