Add basic documentation for admins

   dependency_resolvers

   container_resolvers

   conda_faq

   user_defined_tools

   db_migration

   reports

   useful_scripts

# 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