> For the complete documentation index, see [llms.txt](https://protocol-labs.gitbook.io/testground/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://protocol-labs.gitbook.io/testground/master/builder-library/docker-generic.md).

# docker:generic

## Background

Sometimes the default builder behaviors just aren't flexible enough to do what you want. For those situations, we have the `docker:generic` builder. Linking and SDK replacement features in the other builders are missing here. To use this builder, you must provide your own Dockerfile and specify all the appropriate build activities yourself. 

## Features

* Produces docker containers which can run on docker-powered runners.
* Supports any programming language
* Add assets, files, or whole applications
* highly customizable
* Docker arguments in plans `manifest.toml`file or command-line flags.

## Non-features

* No automatic SDK linkage
* No language-specific features i.e. module dependency management.

## Usage

1. Place a Dockerfile inside the plan directory.
2. While writing your Dockerfile, you must recognize that the root of the docker build context is one directory higher than the plan. This is the way your plan is packaged when it is sent to the Testground daemon. The directory structure actually includes the plan and the SDK.
3. With this directory structure in mind, the builder will construct the container using the equivalent of this command: `docker build -f buildctx/plan/Dockerfile buildctx`. Keep that in mind as you consider which paths to use in the Dockerfile. Paths should be rooted in the build context directory.
4. An example which uses docker arguments and adds additional files can be seen [here](https://github.com/testground/testground/tree/master/plans/example).

```
buildctx/
├── plan                          <- Your plan is always in a /plan directory
│   ├── Dockerfile                <- Your provided Dockerfile
│   └── your...                   <- program files, {c, go, rs, py, java, etc}
|   └── program...
|   └── files...
└── sdk                           <- sdk code which comes with --link-sdk flag
    └── sdk-go (or another one)
```

## Running the example

This example runs a  test case which depends on an additional file being added to the image - something that would not be easy to do using the `docker:go` builder. Have a look at the `Dockerfile` and the `manifest.toml` files to see how this is constructed.

```
testground plan import --from $GOPATH/src/github.com/testground/testground/plans/example
testground run single --builder docker:generic \
                --runner local:docker \
                --plan example \
                --testcase artifact \
                --wait
```

## Are you using `docker:generic`?

If you are using this, we think that's awesome! Maybe there are cool features which we should add to our other builders or interesting additions we haven't considered. We want to hear about it! Open an issue with us on Github and let us know what you're up to!

* Are you using an unsupported language?
* Are you testing with frameworks that aren't easily achievable using the other language-specific builders? (I'm looking at you, headless web browsers!)
* Are there any bugs in the other builders you are circumventing? Definitely let us know if this is the case.

## Learn More

Interested in how this works? All the Testground builders can be seen [here](https://github.com/testground/testground/tree/master/pkg/build)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://protocol-labs.gitbook.io/testground/master/builder-library/docker-generic.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.