docs/docker.md
# How to use ShellSpec with Docker
- [Official docker images](#official-docker-images)
- [Using ShellSpec docker image](#using-shellspec-docker-image)
- [1. Run ShellSpec and your specfiles within container](#1-run-shellspec-and-your-specfiles-within-container)
- [2. Run simple with helper script and extra hooks](#2-run-simple-with-helper-script-and-extra-hooks)
- [Hooks](#hooks)
- [.shellspec-docker/initrc](#shellspec-dockerinitrc)
- [.shellspec-docker/pre-test](#shellspec-dockerpre-test)
- [.shellspec-docker/post-test](#shellspec-dockerpost-test)
- [3. Using ShellSpec image as parent image](#3-using-shellspec-image-as-parent-image)
- [4. Include ShellSpec into another image](#4-include-shellspec-into-another-image)
- [Appendix](#appendix)
- [How to build official ShellSpec docker image yourself](#how-to-build-official-shellspec-docker-image-yourself)
## Official docker images
There are official images on the [Docker Hub](https://hub.docker.com/r/shellspec/shellspec).
| Name | Linux | Included | Size |
| ------------------------------- | ------ | ------------------------- | -------------------------------------------------------------------------------------------------------------: |
| shellspec/shellspec | Alpine | busybox (ash) | ![Docker Image Size (tag)](https://img.shields.io/docker/image-size/shellspec/shellspec/latest?label=) |
| shellspec/shellspec:kcov | Alpine | busybox (ash), bash, kcov | ![Docker Image Size (tag)](https://img.shields.io/docker/image-size/shellspec/shellspec/kcov?label=) |
| shellspec/shellspec-debian | Debian | dash, bash | ![Docker Image Size (tag)](https://img.shields.io/docker/image-size/shellspec/shellspec-debian/latest?label=) |
| shellspec/shellspec-debian:kcov | Debian | dash, bash, kcov | ![Docker Image Size (tag)](https://img.shields.io/docker/image-size/shellspec/shellspec-debian/kcov?label=) |
| shellspec/shellspec-scratch | None | none (shellspec only) | ![Docker Image Size (tag)](https://img.shields.io/docker/image-size/shellspec/shellspec-scratch/latest?label=) |
- Version specified images are also available (VERSION: 0.21.0 and above)
- `shellspec/shellspec[-VARIANT]:<VERSION | master>[-kcov]`
## Using ShellSpec docker image
### 1. Run ShellSpec and your specfiles within container
```sh
# Run docker command on the project root
$ docker run -it --rm -v "$PWD:/src" shellspec/shellspec
# Display help
$ docker run -it --rm -v "$PWD:/src" shellspec/shellspec --help
# Run with kcov (requires kcov supported image)
$ docker run -it --rm -u $(id -u):$(id -g) \
-v "$PWD:/src" shellspec/shellspec:kcov --kcov
# For users using Docker Desktop for Windows within WSL 1
$ docker run -it --rm -v "$(wslpath -wa .):/src" shellspec/shellspec
```
### 2. Run simple with helper script and extra hooks
Use [contrib/shellspec-docker](../contrib/shellspec-docker) helper script.
```sh
# Specify the Docker image to use (default: shellspec/shellspec)
$ export SHELLSPEC_DOCKER=shellspec/shellspec
# Run helper script on the project root
$ shellspec-docker
# Display help
$ shellspec-docker --help
# Run with kcov (requires kcov supported image)
$ shellspec-docker --kcov
# Enter the Docker container
$ shellspec-docker -
# Execute command with in the Docker container
$ shellspec-docker - hostname
```
If you want to run manually.
```sh
$ docker run -it --rm --entrypoint=/shellspec-docker \
-u $(id -u):$(id -g) -v "$PWD:/src" shellspec/shellspec
# For users using Docker Desktop for Windows within WSL 1
$ docker run -it --rm --entrypoint=/shellspec-docker \
-u $(id -u):$(id -g) -v "$(wslpath -wa .):/src" shellspec/shellspec
```
#### Hooks
##### .shellspec-docker/initrc
This file should be a shell script. You can override [docker_run()](../contrib/shellspec-docker) to
changes options, pass environment variables, etc.
##### .shellspec-docker/pre-test
Invoked before execute shellspec inside of the docker container.
##### .shellspec-docker/post-test
Invoked after executed shellspec inside of the docker container.
### 3. Using ShellSpec image as parent image
Example
```Dockerfile
# Dockerfile
FROM shellspec/shellspec
RUN apk add --no-cache add-your-required-packages
COPY ./ /src
```
```sh
# Build and run at your project root
$ docker build -t your-project-name .
$ docker run -it your-project-name
```
### 4. Include ShellSpec into another image
Example
```Dockerfile
# Dockerfile
FROM buildpack-deps
RUN apt-get update && apt-get install -y add-your-required-packages
COPY --from=shellspec/shellspec-scratch /opt/shellspec /opt/shellspec
ENV PATH /opt/shellspec/:$PATH
WORKDIR /src
ENTRYPOINT [ "shellspec" ]
COPY ./ /src
```
```sh
# Build and run at your project root
$ docker build -t your-project-name .
$ docker run -it your-project-name
```
## Appendix
### How to build official ShellSpec docker image yourself
Example
```sh
contrib/build.sh .dockerhub/Dockerfile shellspec
contrib/build.sh .dockerhub/Dockerfile shellspec kcov
contrib/build.sh .dockerhub/Dockerfile.debian shellspec-debian
contrib/build.sh .dockerhub/Dockerfile.debian shellspec-debian kcov
contrib/build.sh .dockerhub/Dockerfile.scratch shellspec-scratch
```