{"id":18589402,"url":"https://github.com/pmorie/go-sti","last_synced_at":"2025-04-10T15:31:03.520Z","repository":{"id":14436962,"uuid":"17148356","full_name":"pmorie/go-sti","owner":"pmorie","description":null,"archived":false,"fork":false,"pushed_at":"2014-05-01T14:47:54.000Z","size":1062,"stargazers_count":6,"open_issues_count":1,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-24T22:51:19.376Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"Onegini/cordova-plugin-inappbrowser","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pmorie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-02-24T19:45:37.000Z","updated_at":"2018-04-20T15:55:41.000Z","dependencies_parsed_at":"2022-09-08T08:11:11.896Z","dependency_job_id":null,"html_url":"https://github.com/pmorie/go-sti","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmorie%2Fgo-sti","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmorie%2Fgo-sti/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmorie%2Fgo-sti/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmorie%2Fgo-sti/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pmorie","download_url":"https://codeload.github.com/pmorie/go-sti/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248243452,"owners_count":21071054,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T00:51:57.150Z","updated_at":"2025-04-10T15:31:03.121Z","avatar_url":"https://github.com/pmorie.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"go-sti\n======\n\nSource-to-images (`sti`) is a tool for building reproducable Docker images.  `sti`\nproduces ready-to-run images by injecting a user source into a docker image and \u003ci\u003epreparing\u003c/i\u003e\na new Docker image which incorporates the base image and built source, and is ready to use\nwith `docker run`.  `sti` supports:\n\n1. Incremental builds which re-use previously downloaded dependencies, previously built\n   artifacts, etc\n1. Build on one image, deploy on another with extended builds\n\nInterested in learning more?  Read on!\n\n### Philosophy\n\n1. Simplify the process of application source + base image -\u003e usable image for most use cases (the 80%)\n2. Define and implement a workflow for incremental build that eventually uses only docker primitives\n3. Develop tooling that can assist in verifying that two different base images result in the same\n   \"docker run\" outcome for the same input\n4. Use native docker primitives to accomplish this - map out useful improvements to docker that\n   benefit all image builders\n\n### Anatomy of a source image\n\nBuilding source images is as easy as implementing two scripts.  `sti` expects the\nfollowing scripts in `/usr/bin`:\n\n1. `prepare` : This script is responsible for building and/or deploying the source\n1. `run`: This script is responsible for running the deployed source\n\n### Build methodologies\n\n`sti` implements two methodologies for building Docker images.  The first will be familiar to anyone\nwho's built their own Docker image before - it's just `docker build`.  When building this way, `sti`\ngenerates a Dockerfile and calls `docker build` to produce the output image:\n\n1. `sti` generates a `Dockerfile` to describe the output image:\n    1. Based on the build image\n    1. Adds the application source at `/usr/src` in the container\n    1. Calls `/usr/bin/prepare` in the container\n    1. Sets the image's default command to `/usr/bin/run`\n1. `sti` calls `docker build` to produce the output image\n\n`sti` also supports building images with `docker run`.  When building this way, the workflow is:\n\n1. `sti` creates a container based on the build image. with:\n    1. The application source bind-mounted to `/usr/src`\n    1. The build artifacts bind-mounted to `/usr/artifacts` (if applicable - see incremental builds)\n    1. Runs the build image's `/usr/bin/prepare` script\n1. `sti` starts the container and waits for it to finish running\n1. `sti` commits the container, setting the CMD for the output image to be `/usr/bin/run`\n\nThe build methodology is controlled by the `-m` option, and defaults to `build`.  To build with\n`docker run`, use `-m run`.\n\n### Basic (`--clean`) builds\n\n`sti` accepts the following inputs to do a build:\n\n1. Application source: this can be source code, zipped source, a binary, etc\n1. Build image: the basis for the new image to build\n1. Application image tag: the tag to use for the newly created application image\n\nThe basic build process is as follows:\n\n1. `sti` pulls the build image if it is not already present on the system\n1. `sti` builds the new image from the supplied build image and source, tagging the output image\n   with the supplied tag\n\n### Incremental builds\n\n`sti` automatically detects:\n\n1. Whether a source image is compatible with incremental building\n1. Whether an incremental build can be formed when an image is compatible\n\nIf the source image is compatible, a prior build already exists, and the `--clean` option is not used,\nthe workflow is as follows:\n\n1. `sti` creates a new docker container from the prior build image, with a volume in `/usr/artifacts`\n1. `sti` runs `/usr/bin/save-artifacts` in this container - this script is responsible for copying\n   the build artifacts into `/usr/artifacts`.\n1. `sti` builds the new output image using the selected build methodology:\n    1. The artifacts from the previous build will be in `/usr/artifacts` during the build\n    1. The build image's `/usr/bin/prepare` script is responsible for detecting and using the build\n       artifacts\n\nNote the invocation of the `save-artifacts` script; this script is responsible for moving build\ndependencies to `/usr/artifacts`\n\n### Extended builds\n\nExtended builds allow you to execute your build on a build image, then deploy it on a different\nruntime image. The workflow for extended builds is as follows:\n\n1. `sti` looks for the previous build image for the tag, `\u003ctag\u003e-build`.\n1. If that image exists:\n    1. `sti` creates a container from this image and runs `/usr/bin/save-artifacts` in it\n1. `sti` creates a build container from the build image with a volume at `/usr/build`\n   and bind-mounts in the artifacts from the prior build, if applicable\n1. `sti` runs `/usr/bin/prepare` in the build container - this script is responsible for\n   populating `/usr/build` with the result of the build\n1. `sti` builds the output image with the selected build methodology:\n    1. The base image will be the runtime image\n    1. The output of the source build step will be in `/usr/src` during the build\n    1. The runtime image's `/usr/bin/prepare` script is responsible for being able to deploy the\n       artifact in `/usr/src`\n1. If the docker build succeeds, the build container is tagged as `\u003ctag\u003e-build`\n\nYou might have noticed that the above workflow describes something like an incremental build.\nThis behavior can be disabled with the `--clean` option.\n\n### Getting started\n\n#### Dependencies\n\n1. [Docker](http://www.docker.io)\n1. [Go](http://golang.org/)\n\n#### Installation\n\n\tgo get github.com/pmorie/go-sti/sti\n\n#### Example\n\nYou can start using sti right away with the following test sources and publicly available images:\n\n    sti build git://github.com/pmorie/simple-ruby pmorie/centos-ruby2 test-ruby-app\n    docker run -rm -i -p :9292 -t test-ruby-app\n\n    sti build git://github.com/pmorie/simple-ruby pmorie/ubuntu-buildpack test-foreman-app \\\n    -e 'BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-ruby.git'\n    docker run -rm -i -p :5000 -t test-foreman-app\n\n    sti build git://github.com/pmorie/simple-html pmorie/fedora-mock test-html-app\n    docker run -rm -i -p :8080 -t sti_app\n\n\n### Validating a source image\n\n    sti validate BUILD_IMAGE_TAG [flags]\n\n    Available Flags:\n         --debug=false: Enable debugging output\n     -I, --incremental=false: Validate for an incremental build\n     -R, --runtime=\"\": Set the runtime image to use\n     -U, --url=\"unix:///var/run/docker.sock\": Set the url of the docker socket to use\n\n\nYou can validate that an image is usable as a sti source image as follows:\n\n\tsti validate BUILD_IMAGE_TAG\n\nThe `--incremental` option to enables validation for incremental builds:\n\n    sti validate BUILD_IMAGE_TAG --incremental\n\nAdd the `-R` option to additionally validate a runtime image for extended builds:\n\n    sti validate BUILD_IMAGE_TAG -R RUNTIME_IMAGE_TAG\n\nWhen specifying a runtime image with `sti validate`, the build image is automatically validated for\nincremental builds.\n\n### Building a deployable image with sti\n\n    sti build SOURCE BUILD_IMAGE APP_IMAGE_TAG [flags]\n\n    Available Flags:\n         --clean=false: Perform a clean build\n         --debug=false: Enable debugging output\n         --dir=\"tempdir\": Directory where generated Dockerfiles and other support scripts are created\n     -e, --env=\"\": Specify an environment var NAME=VALUE,NAME2=VALUE2,...\n     -R, --runtime=\"\": Set the runtime image to use\n     -U, --url=\"unix:///var/run/docker.sock\": Set the url of the docker socket to use\n\n\nThe most basic `sti build` uses a single build image:\n\n    sti build SOURCE BUILD_IMAGE_TAG APP_IMAGE_TAG\n\nIf the build is successful, the built image will be tagged with `APP_IMAGE_TAG`.\n\nIf the build image is compatible with incremental builds, `sti build` will look for an image tagged\nwith `APP_IMAGE_TAG`.  If an image is present with that tag, `sti build` will save the build\nartifacts from that image and add them to the build container at `/usr/artifacts` so an image's\n`/usr/bin/prepare` script can restore them before building the source.\n\nWhen using an image that supports incremental builds, you can do a clean build with `--clean`:\n\n    sti build SOURCE BUILD_IMAGE_TAG APP_IMAGE_TAG --clean\n\nExtended builds allow you to use distinct images for building your sources and deploying them. Use\nthe `-R` option perform an extended build targeting a runtime image:\n\n    sti build SOURCE BUILD_IMAGE_TAG APP_IMAGE_TAG -R RUNTIME_IMAGE_TAG\n\nWhen specifying a runtime image, the build image must be compatible with incremental builds.\n`sti build` will look for an image tagged with `\u003cAPP_IMAGE_TAG\u003e-build`.  If an image is present with\nthat tag, `sti build` will save the build artifacts from that image and add them to the build\ncontainer at `/usr/artifacts` so the build image's `/usr/bin/prepare` script can restore them before\nbuilding the source.  The build image's `/usr/bin/prepare` script is responsible for populating\n`/usr/build` with an artifact to be deployed into the runtime container.\n\nAfter performing the build, a new runtime image is created based on the image tagged with\n`RUNTIME_IMAGE_TAG` with the output of the build in `/usr/src`.  The runtime image's\n`/usr/bin/prepare` script is responsible for detecting and deploying the artifact.  If the build is\nsuccessful, two images are tagged:\n\n1. The build image is tagged with `\u003cAPP_IMAGE_TAG\u003e-build`\n1. The prepared image incorporating the deployed build is tagged with `APP_IMAGE_TAG`\n\nYou can do a clean extended build with `--clean`:\n\n    sti build SOURCE_DIR BUILD_IMAGE_TAG APP_IMAGE_TAG -R RUNTIME_IMAGE_TAG --clean\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmorie%2Fgo-sti","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpmorie%2Fgo-sti","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmorie%2Fgo-sti/lists"}