# dockerRun

This step runs a docker image and executes the given shell bash script.

## Parameters

| Name      | Description                                                      | Type           | Default                                                             | Required |
| --------- | ---------------------------------------------------------------- | -------------- | ------------------------------------------------------------------- | -------- |
| script    | Inline or path to bash script to execute in the docker container | `String`       | n/a                                                                 | yes      |
| imageTag  | The image tag to run. eg 'node20'                                | `String`       | n/a                                                                 | yes      |
| imageRepo | Url to the image repository                                      | `String`       | '086679231553.dkr.ecr.us-east-1.amazonaws.com/docker-parent-images' | no       |
| user      | The user running the docker image                                | `String`       | null                                                                | no       |
| workDir   | The working directory in the container                           | `String`       | null                                                                | no       |
| envVars   | Map with environment variables to set/override in the container  | `Map`          | null                                                                | no       |
| volumes   | List with volumes to mount                                       | `List<String>` | null                                                                | no       |

## Usage

The step requires two parameters, `imageTag` and `script`.
The `imageTag` property refers by default to the image tags found in our [docker-parent-images](https://github.com/theorchard/docker-parent-images) repo.

The `script` is a inline script or a path to a script file to be executed inside the container.

### Set environment variables in container

Use the `envVars` property to set environment variables in the container.

```groovy
dockerRun(
    imageTag: 'node20',
    script: 'echo hi',
    envVars: [NODE_VERSION: '20.11.0']
)
```

### Mount volumes

Use the `volumes` property to mount directories into the container.
The property expects a list of strings in the [external:internal] format.
Please refer to the [docker run --volume](https://docs.docker.com/engine/reference/commandline/container_run/#volume) docs for more information.

The example below mounts the current directory into the container at the path `var/my-app` path.

```groovy
dockerRun(
    imageTag: 'node20',
    script: 'echo hi',
    volumes: ['$(pwd):var/my-app']
)
```

### Set the working directory

Use the `workdir` property to set the working directory inside the container.
The example below mounts the current directory into the container at the path `var/my-app` path and sets it as the working directory.

```groovy
dockerRun(
    imageTag: 'node20',
    script: 'echo hi',
    volumes: ['$(pwd):var/my-app'],
    workdir: 'var/my-app'
)
```

### Set the user

Use the `user` property to set the user in the container.
The property can be a user name or a UID. Accepted formats: `<name|uid>[:<group|gid>]`

**NB. Do not set the user to `root` unless you have been given explicit clearance by devops / security team**

The example below sets the user to the `node` user found in the node20 image.

```groovy
dockerRun(
    imageTag: 'node20',
    script: 'echo hi',
    user: 'node'
)
```

### Change the default image repo location

By default the image repository is set to `086679231553.dkr.ecr.us-east-1.amazonaws.com/docker-parent-images`.
Use the `imageRepo` property to specify a different location.

```groovy
dockerRun(
    imageTag: 'node20',
    script: 'echo hi',
    imageRepo: '086679231553.dkr.ecr.us-west-1.amazonaws.com/docker-parent-images'
)
```