github.com/nak3/source-to-image@v1.1.10-0.20180319140719-2ed55639898d/README.md (about) 1 # Source-To-Image (S2I) 2 3 ## Overview 4 5 [![Go Report Card](https://goreportcard.com/badge/github.com/openshift/source-to-image)](https://goreportcard.com/report/github.com/openshift/source-to-image) 6 [![GoDoc](https://godoc.org/github.com/openshift/source-to-image?status.png)](https://godoc.org/github.com/openshift/source-to-image) 7 [![Travis](https://travis-ci.org/openshift/source-to-image.svg?branch=master)](https://travis-ci.org/openshift/source-to-image) 8 [![License](https://img.shields.io/github/license/openshift/source-to-image.svg)](https://www.apache.org/licenses/LICENSE-2.0.html) 9 10 Source-to-Image (S2I) is a toolkit and workflow for building reproducible Docker images from source code. S2I produces 11 ready-to-run images by injecting source code into a Docker container and letting the container prepare that source code for execution. By creating self-assembling **builder images**, you can version and control your build environments exactly like you use Docker images to version your runtime environments. 12 13 For a deep dive on S2I you can view [this presentation](https://www.youtube.com/watch?v=flI6zx9wH6M). 14 15 Want to try it right now? Download the [latest release](https://github.com/openshift/source-to-image/releases/latest) and run: 16 17 $ s2i build https://github.com/openshift/django-ex centos/python-35-centos7 hello-python 18 $ docker run -p 8080:8080 hello-python 19 20 Now browse to http://localhost:8080 to see the running application. 21 22 You've just built and run a new Docker application image from source code in a git repository, no Dockerfile necessary. 23 24 ### How Source-to-Image works 25 26 For a dynamic language like Ruby, the build-time and run-time environments are typically the same. Starting with a **builder image** that describes this environment - with Ruby, Bundler, Rake, Apache, GCC, and other packages needed to set up and run a Ruby application installed - source-to-image performs the following steps: 27 28 1. Start a container from the builder image with the application source injected into a known directory 29 1. The container process transforms that source code into the appropriate runnable setup - in this case, by installing dependencies with Bundler and moving the source code into a directory where Apache has been preconfigured to look for the Ruby `config.ru` file. 30 1. Commit the new container and set the image entrypoint to be a script (provided by the builder image) that will start Apache to host the Ruby application. 31 32 For compiled languages like C, C++, Go, or Java, the dependencies necessary for compilation might dramatically outweigh the size of the actual runtime artifacts. To keep runtime images slim, S2I enables a multiple-step build processes, where a binary artifact such as an executable or Java WAR file is created in the first builder image, extracted, and injected into a second runtime image that simply places the executable in the correct location for execution. 33 34 For example, to create a reproducible build pipeline for Tomcat (the popular Java webserver) and Maven: 35 36 1. Create a builder image containing OpenJDK and Tomcat that expects to have a WAR file injected 37 2. Create a second image that layers on top of the first image Maven and any other standard dependencies, and expects to have a Maven project injected 38 3. Invoke source-to-image using the Java application source and the Maven image to create the desired application WAR 39 4. Invoke source-to-image a second time using the WAR file from the previous step and the initial Tomcat image to create the runtime image 40 41 By placing our build logic inside of images, and by combining the images into multiple steps, we can keep our runtime environment close to our build environment (same JDK, same Tomcat JARs) without requiring build tools to be deployed to production. 42 43 ## Goals 44 45 ### Reproducibility 46 Allow build environments to be tightly versioned by encapsulating them within a Docker image and defining a simple interface (injected source code) for callers. Reproducible builds are a key requirement to enabling security updates and continuous integration in containerized infrastructure, and builder images help ensure repeatability as well as the ability to swap runtimes. 47 48 ### Flexibility 49 Any existing build system that can run on Linux can be run inside of a container, and each individual builder can also be part of a larger pipeline. In addition, the scripts that process the application source code can be injected into the builder image, allowing authors to adapt existing images to enable source handling. 50 51 ### Speed 52 Instead of building multiple layers in a single Dockerfile, S2I encourages authors to represent an application in a single image layer. This saves time during creation and deployment, and allows for better control over the output of the final image. 53 54 ### Security 55 Dockerfiles are run without many of the normal operational controls of containers, usually running as root and having access to the container network. S2I can be used to control what permissions and privileges are available to the builder image since the build is launched in a single container. In concert with platforms like OpenShift, source-to-image can enable admins to tightly control what privileges developers have at build time. 56 57 58 ## Anatomy of a builder image 59 60 Creating builder images is easy. `s2i` looks for you to supply the following scripts to use with an 61 image: 62 63 1. `assemble` - builds and/or deploys the source 64 1. `run`- runs the assembled artifacts 65 1. `save-artifacts` (optional) - captures the artifacts from a previous build into the next incremental build 66 1. `usage` (optional) - displays builder image usage information 67 68 Additionally for the best user experience and optimized `s2i` operation we suggest images 69 to have `/bin/sh` and `tar` commands available. 70 71 See [a practical tutorial on how to create a builder image](examples/nginx-centos7/README.md) and read [a detailed description of the requirements and scripts along with examples of builder images](docs/builder_image.md). 72 73 ## Build workflow 74 75 The `s2i build` workflow is: 76 77 1. `s2i` creates a container based on the build image and passes it a tar file that contains: 78 1. The application source in `src`, excluding any files selected by `.s2iignore` 79 1. The build artifacts in `artifacts` (if applicable - see [incremental builds](#incremental-builds)) 80 1. `s2i` sets the environment variables from `.s2i/environment` (optional) 81 1. `s2i` starts the container and runs its `assemble` script 82 1. `s2i` waits for the container to finish 83 1. `s2i` commits the container, setting the CMD for the output image to be the `run` script and tagging the image with the name provided. 84 85 Filtering the contents of the source tree is possible if the user supplies a 86 `.s2iignore` file in the root directory of the source repository, where `.s2iignore` contains regular 87 expressions that capture the set of files and directories you want filtered from the image s2i produces. 88 89 Specifically: 90 91 1. Specify one rule per line, with each line terminating in `\n`. 92 1. Filepaths are appended to the absolute path of the root of the source tree (either the local directory supplied, or the target destination of the clone of the remote source repository s2i creates). 93 1. Wildcards and globbing (file name expansion) leverage Go's `filepath.Match` and `filepath.Glob` functions. 94 1. Search is not recursive. Subdirectory paths must be specified (though wildcards and regular expressions can be used in the subdirectory specifications). 95 1. If the first character is the `#` character, the line is treated as a comment. 96 1. If the first character is the `!`, the rule is an exception rule, and can undo candidates selected for filtering by prior rules (but only prior rules). 97 98 Here are some examples to help illustrate: 99 100 With specifying subdirectories, the `*/temp*` rule prevents the filtering of any files starting with `temp` that are in any subdirectory that is immediately (or one level) below the root directory. 101 And the `*/*/temp*` rule prevents the filtering of any files starting with `temp` that are in any subdirectory that is two levels below the root directory. 102 103 Next, to illustrate exception rules, first consider the following example snippet of a `.s2iignore` file: 104 105 106 ``` 107 *.md 108 !README.md 109 ``` 110 111 112 With this exception rule example, README.md will not be filtered, and remain in the image s2i produces. However, with this snippet: 113 114 115 ``` 116 !README.md 117 *.md 118 ``` 119 120 121 `README.md`, if filtered by any prior rules, but then put back in by `!README.md`, would be filtered, and not part of the resulting image s2i produces. Since `*.md` follows `!README.md`, `*.md` takes precedence. 122 123 Users can also set extra environment variables in the application source code. 124 They are passed to the build, and the `assemble` script consumes them. All 125 environment variables are also present in the output application image. These 126 variables are defined in the `.s2i/environment` file inside the application sources. 127 The format of this file is a simple key-value, for example: 128 129 ``` 130 FOO=bar 131 ``` 132 133 In this case, the value of `FOO` environment variable will be set to `bar`. 134 135 ## Using ONBUILD images 136 137 In case you want to use one of the official Docker language stack images for 138 your build you don't have do anything extra. S2I is capable of recognizing the 139 Docker image with [ONBUILD](https://docs.docker.com/engine/reference/builder/#/onbuild) instructions and choosing the OnBuild strategy. This 140 strategy will trigger all ONBUILD instructions and execute the assemble script 141 (if it exists) as the last instruction. 142 143 Since the ONBUILD images usually don't provide any entrypoint, in order to use 144 this build strategy you will have to provide one. You can either include the 'run', 145 'start' or 'execute' script in your application source root folder or you can 146 specify a valid S2I script URL and the 'run' script will be fetched and set as 147 an entrypoint in that case. 148 149 ### Incremental builds 150 151 `s2i` automatically detects: 152 153 * Whether a builder image is compatible with incremental building 154 * Whether a previous image exists, with the same name as the output name for this build 155 156 If a `save-artifacts` script exists, a prior image already exists, and the `--incremental=true` option is used, the workflow is as follows: 157 158 1. `s2i` creates a new Docker container from the prior build image 159 1. `s2i` runs `save-artifacts` in this container - this script is responsible for streaming out 160 a tar of the artifacts to stdout 161 1. `s2i` builds the new output image: 162 1. The artifacts from the previous build will be in the `artifacts` directory of the tar 163 passed to the build 164 1. The build image's `assemble` script is responsible for detecting and using the build 165 artifacts 166 167 **NOTE**: The `save-artifacts` script is responsible for streaming out dependencies in a tar file. 168 169 170 ## Dependencies 171 172 1. [docker](https://docker.com) >= 1.6 173 1. [Go](https://golang.org/dl/) >= 1.7.1 174 1. (optional) [Git](https://git-scm.com/) 175 176 ## Installation 177 178 ##### Using `go get` 179 180 You can install the s2i binary using `go get` which will download the source-to-image code into your `$GOPATH`, build the s2i binary, and install it into your `$GOPATH/bin`. 181 182 ```$ go get github.com/openshift/source-to-image/cmd/s2i``` 183 184 ##### For Mac 185 186 You can either follow the installation instructions for Linux (and use the darwin-amd64 link) or you can just install source-to-image with Homebrew: 187 188 ```$ brew install source-to-image``` 189 190 ##### For Linux 191 192 Go to the [releases](https://github.com/openshift/source-to-image/releases/latest) page and download the correct distribution for your machine. Choose either the linux-386 or the linux-amd64 links for 32 and 64-bit, respectively. 193 194 Unpack the downloaded tar with 195 196 ```$ tar -xvf release.tar.gz```. 197 198 You should now see an executable called s2i. Either add the location of s2i to your PATH environment variable, or move it to a pre-existing directory in your PATH. 199 For example, 200 201 ```# cp /path/to/s2i /usr/local/bin``` 202 203 will work with most setups. 204 205 ##### For Windows 206 207 Download the latest [64-bit Windows release](https://github.com/openshift/source-to-image/releases/latest). 208 Extract the zip file through a file browser. Add the extracted directory to your PATH. You can now use 209 s2i from the command line. 210 211 Note: We have had some reports of Windows Defender falsely alerting reporting that the Windows binaries 212 contain "Trojan:Win32/Azden.A!cl". This appears to be a common false alert for other applications as well. 213 214 ##### From source 215 216 Assuming Go and Docker are installed and configured, execute the following commands: 217 218 ``` 219 $ go get github.com/openshift/source-to-image 220 $ cd ${GOPATH}/src/github.com/openshift/source-to-image 221 $ export PATH=$PATH:${GOPATH}/src/github.com/openshift/source-to-image/_output/local/bin/linux/amd64/ 222 $ hack/build-go.sh 223 ``` 224 225 ## Security 226 227 Since the `s2i` command uses the Docker client library, it has to run in the same 228 security context as the `docker` command. For some systems, it is enough to add 229 yourself into the 'docker' group to be able to work with Docker as 'non-root'. 230 In the latest versions of Fedora/RHEL, it is recommended to use the `sudo` command 231 as this way is more auditable and secure. 232 233 If you are using the `sudo docker` command already, then you will have to also use 234 `sudo s2i` to give S2I permission to work with Docker directly. 235 236 Be aware that being a member of the 'docker' group effectively grants root access, 237 as described [here](https://github.com/docker/docker/issues/9976). 238 239 ## Getting Started 240 241 You can start using `s2i` right away (see [releases](https://github.com/openshift/source-to-image/releases)) 242 with the following test sources and publicly available images: 243 244 ``` 245 $ s2i build https://github.com/openshift/ruby-hello-world centos/ruby-23-centos7 test-ruby-app 246 $ docker run --rm -i -p :8080 -t test-ruby-app 247 ``` 248 249 ``` 250 $ s2i build --ref=10.x --context-dir=helloworld https://github.com/wildfly/quickstart openshift/wildfly-101-centos7 test-jee-app 251 $ docker run --rm -i -p 8080:8080 -t test-jee-app 252 ``` 253 254 Want to know more? Read the following resources: 255 256 * [Descriptions and examples of the S2I commands](docs/cli.md) 257 * [Instructions for using builder images](docs/user_guide.md) 258 * [Guidance for S2I builder image creators](docs/builder_image.md) 259 * [Using a non-builder image for the base of the application image](docs/runtime_image.md) 260 * [Troubleshooting and debugging S2I problems](docs/debugging-s2i.md)