github.com/nak3/source-to-image@v1.1.10-0.20180319140719-2ed55639898d/docs/cli.md (about) 1 # s2i command line interface 2 3 This document describes thoroughly all `s2i` subcommands and flags with explanation 4 of their purpose as well as an example usage. 5 6 Currently `s2i` has five subcommands, each of which will be described in the 7 following sections of this document: 8 9 * [create](#s2i-create) 10 * [build](#s2i-build) 11 * [rebuild](#s2i-rebuild) 12 * [usage](#s2i-usage) 13 * [version](#s2i-version) 14 * [help](#s2i-help) 15 16 Before diving into each of the aforementioned commands, let's have a closer look 17 at common flags that can be used with all of the subcommands. 18 19 | Name | Description | 20 |:-------------------------- |:--------------------------------------------------------| 21 | `-h (--help)` | Display help for the specified command | 22 | `--loglevel` | Set the level of log output (0-5) (see [Log levels](#log-levels))| 23 | `-U (--url)` | URL of the Docker socket to use (default: `unix:///var/run/docker.sock`) | 24 25 #### Log levels 26 27 There are six log levels: 28 * Level `0` - produces output from containers running `assemble` and `assemble-runtime` scripts and all encountered errors 29 * Level `1` - produces basic information about the executed process 30 * Level `2` - produces very detailed information about the executed process 31 * Level `3` - produces very detailed information about the executed process, along with listing tar contents 32 * Level `4` - currently produces same information as level `3` 33 * Level `5` - produces very detailed information about the executed process, lists tar contents, Docker Registry credentials, and copied source files 34 35 **NOTE**: All of the commands and flags are case sensitive! 36 37 # s2i create 38 39 The `s2i create` command is responsible for bootstrapping a new S2I enabled 40 image repository. This command will generate a skeleton `.s2i` directory and 41 populate it with sample S2I scripts you can start hacking on. 42 43 Usage: 44 45 ``` 46 $ s2i create <image name> <destination directory> 47 ``` 48 49 # s2i build 50 51 The `s2i build` command is responsible for building the Docker image by combining 52 the specified builder image and sources. The resulting image will be named according 53 to the tag parameter. 54 55 Usage: 56 ``` 57 $ s2i build <source location> <builder image> [<tag>] [flags] 58 ``` 59 The build command parameters are defined as follows: 60 61 1. `source location` - the URL of a Git repository or a local path to the source code 62 1. `builder image` - the Docker image to be used in building the final image 63 1. `tag` - the name of the final Docker image (if provided) 64 65 If the build image is compatible with incremental builds, `s2i build` will look for 66 an image tagged with the same name. If an image is present with that tag and a 67 `save-artifacts` script is present in the scripts directory, `s2i build` will save the build artifacts from 68 that image and add them to the tar streamed to the container into `/artifacts`. 69 70 #### Build flags 71 72 | Name | Description | 73 |:-------------------------- |:--------------------------------------------------------| 74 | `--callback-url` | URL to be invoked after a build (see [Callback URL](#callback-url)) | 75 | `-c (--copy)` | Use local file system copy instead of git cloning the source url (allows for inclusion of empty directories and uncommitted files) | 76 | `-d (--destination)` | Location where the scripts and sources will be placed prior doing build (see [S2I Scripts](https://github.com/openshift/source-to-image/blob/master/docs/builder_image.md#s2i-scripts)) | 77 | `--dockercfg-path` | The path to the Docker configuration file | 78 | `--incremental` | Try to perform an incremental build | 79 | `-e (--env)` | Environment variable to be passed to the builder eg. `NAME=VALUE` | 80 | `-E (--environment-file)` | Specify the path to the file with environment | 81 | `--exclude` | Regular expression for selecting files from the source tree to exclude from the build, where the default excludes the '.git' directory (see https://golang.org/pkg/regexp for syntax, but note that \"\" will be interpreted as allow all files and exclude no files) | 82 | `-p (--pull-policy)` | Specify when to pull the builder image (`always`, `never` or `if-not-present`. Defaults to `if-not-present`) | 83 | `--run` | Launch the resulting image after a successful build. All output from the image is being printed to help determine image's validity. In case of a long running image you will have to Ctrl-C to exit both s2i and the running container. (defaults to false) | 84 | `-r (--ref)` | A branch/tag that the build should use instead of MASTER (applies only to Git source) | 85 | `--rm` | Remove the previous image during incremental builds | 86 | `--save-temp-dir` | Save the working directory used for fetching scripts and sources | 87 | `--context-dir` | Specify the directory containing your application (if not located within the root path) | 88 | `-s (--scripts-url)` | URL of S2I scripts (see [S2I Scripts](https://github.com/openshift/source-to-image/blob/master/docs/builder_image.md#s2i-scripts)) | 89 | `--ignore-submodules` | Ignore all git submodules when cloning application repository. (defaults to false)| 90 | `-q (--quiet)` | Operate quietly, suppressing all non-error output | 91 | `-i (--inject)` | Inject the content of the specified directory into the path in the container that runs the assemble script | 92 | `-v (--volume)` | Bind mounts a local directory into the container that runs the assemble script| 93 | `--runtime-image` | Image that will be used as the base for the runtime image (see [How to use a non-builder image for the final application image](https://github.com/openshift/source-to-image/blob/master/docs/runtime_image.md)) | 94 | `-a (--runtime-artifact)` | Specify a file or directory to be copied from the builder to the runtime image (see [How to use a non-builder image for the final application image](https://github.com/openshift/source-to-image/blob/master/docs/runtime_image.md)) | 95 96 #### Context directory 97 98 In the case where your application resides in a directory other than your repository root 99 folder, you can specify that directory using the `--context-dir` parameter. The 100 specified directory will be used as your application root folder. 101 102 #### Injecting directories to build 103 104 If you want to inject files that should only be available during the build (ie 105 when the assemble script is invoked), you can specify the directories from which 106 the files will be copied into the container that runs the assemble script. To do 107 so you can invoke S2I as follows: 108 109 ```console 110 $ s2i build --inject /mydir:/container/dir file://source builder-image output-image 111 ``` 112 113 In this case the content of the `/mydir` directory will get copied into 114 `/container/dir` inside the container which runs the assemble script. 115 After the `assemble` script finishes, all files copied will be truncated and thus 116 not available in the output image. The files are truncated instead of deleted 117 because the user under which we run the container with the assemble script might not 118 have permissions to delete files in the destination directory (eg. `/etc/ssl`). 119 120 You can also specify multiple directories, for example: `--inject /dir1:/container/dir1 --inject /dir2:container/dir2`. 121 122 You can use this feature to provide SSL certificates, private configuration 123 files which contains credentials, etc. 124 125 #### Callback URL 126 127 Upon completion (or failure) of a build, `s2i` can execute a HTTP POST to a URL with information 128 about the build: 129 130 * `success` - flag indicating the result of the build process (`true` or `false`) 131 * `labels` - labels of the resulting image 132 133 Example: data posted will be in the form: 134 ``` 135 { 136 "success": true, 137 "labels": { 138 "io.k8s.display-name": "my-app", 139 "io.openshift.s2i.build.image": "builder-image:latest", 140 ... 141 } 142 } 143 ``` 144 145 #### Example Usage 146 147 Build a Ruby application from a Git source, using the official `ruby-23-centos7` builder 148 image, the resulting image will be named `ruby-app`: 149 150 ``` 151 $ s2i build https://github.com/openshift/ruby-hello-world openshift/ruby-23-centos7 ruby-app 152 ``` 153 154 Build a Node.js application from a local directory, using a local image, the resulting 155 image will be named `nodejs-app`: 156 157 ``` 158 $ s2i build /home/user/nodejs-app local-nodejs-builder nodejs-app 159 ``` 160 161 In case of building from the local directory, the sources will be copied into 162 the builder images using plain filesystem copy if the Git binary is not 163 available. In that case the output image will not have the Git specific labels. 164 Use this method only for development or local testing. 165 166 **NOTE**: All your changes have to be committed by `git` in order to build them with S2I. 167 168 Build a Java application from a Git source, using the official `openshift/wildfly-101-centos7` 169 builder image but overriding the scripts URL from local directory. The resulting 170 image will be named `java-app`: 171 172 ``` 173 $ s2i build --scripts-url=file://s2iscripts --ref=7.1.x --context-dir=kitchensink https://github.com/jboss-developer/jboss-eap-quickstarts openshift/wildfly-101-centos7 java-app 174 ``` 175 176 Build a Ruby application from a Git source, specifying `ref`, and using the official 177 `ruby-23-centos7` builder image. The resulting image will be named `ruby-app`: 178 179 ``` 180 $ s2i build --ref=my-branch https://github.com/openshift/ruby-hello-world openshift/ruby-23-centos7 ruby-app 181 ``` 182 183 ***NOTE:*** If the ref is invalid or not present in the source repository then the build will fail. 184 185 Build a Ruby application from a Git source, overriding the scripts URL from a local directory, 186 and specifying the scripts and sources be placed in `/opt` directory: 187 188 ``` 189 $ s2i build --scripts-url=file://s2iscripts --destination=/opt https://github.com/openshift/ruby-hello-world openshift/ruby-23-centos7 ruby-app 190 ``` 191 192 # s2i rebuild 193 194 The `s2i rebuild` command is used to rebuild an image already built using S2I, 195 or the image that contains the required S2I labels. 196 The rebuild will read the S2I labels and automatically set the builder image, 197 source repository and other configuration options used to build the previous 198 image according to the stored labels values. 199 200 Optionally, you can set the new image name as a second argument to the rebuild 201 command. 202 203 Usage: 204 205 ``` 206 $ s2i rebuild <image name> [<new-tag-name>] 207 ``` 208 209 210 # s2i usage 211 212 The `s2i usage` command starts a container and runs the `usage` script which prints 213 information about the builder image. This command expects `builder image` name as 214 the only parameter. 215 216 Usage: 217 ``` 218 $ s2i usage <builder image> [flags] 219 ``` 220 221 #### Usage flags 222 223 | Name | Description | 224 |:-------------------------- |:--------------------------------------------------------| 225 | `-d (--destination)` | Location where the scripts and sources will be placed prior invoking usage (see [S2I Scripts](https://github.com/openshift/source-to-image/blob/master/docs/builder_image.md#s2i-scripts))| 226 | `-e (--env)` | Environment variable passed to the builder eg. `NAME=VALUE`) | 227 | `-p (--pull-policy)` | Specify when to pull the builder image (`always`, `never` or `if-not-present`) | 228 | `--save-temp-dir` | Save the working directory used for fetching scripts and sources | 229 | `-s (--scripts-url)` | URL of S2I scripts (see [Scripts URL](https://github.com/openshift/source-to-image/blob/master/docs/builder_image.md#s2i-scripts))| 230 231 #### Example Usage 232 233 Print the official `ruby-23-centos7` builder image usage: 234 ``` 235 $ s2i usage openshift/ruby-23-centos7 236 ``` 237 238 239 # s2i version 240 241 The `s2i version` command prints the version of S2I currently installed. 242 243 244 # s2i help 245 246 The `s2i help` command prints help either for the `s2i` itself or for the specified 247 subcommand. 248 249 ### Example Usage 250 251 Print the help page for the build command: 252 ``` 253 $ s2i help build 254 ``` 255 256 ***Note:*** You can also accomplish this with: 257 ``` 258 $ s2i build --help 259 ```