{"id":13415912,"url":"https://github.com/cisco/elsy","last_synced_at":"2025-04-30T00:12:35.328Z","repository":{"id":44920615,"uuid":"67536560","full_name":"cisco/elsy","owner":"cisco","description":"An opinionated, multi-language, build tool based on Docker and Docker Compose","archived":false,"fork":false,"pushed_at":"2022-01-18T13:38:49.000Z","size":558,"stargazers_count":80,"open_issues_count":13,"forks_count":22,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-30T00:12:27.392Z","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":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cisco.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-09-06T18:40:47.000Z","updated_at":"2025-02-21T07:04:24.000Z","dependencies_parsed_at":"2022-09-10T18:50:20.638Z","dependency_job_id":null,"html_url":"https://github.com/cisco/elsy","commit_stats":null,"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisco%2Felsy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisco%2Felsy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisco%2Felsy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisco%2Felsy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cisco","download_url":"https://codeload.github.com/cisco/elsy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251602831,"owners_count":21615969,"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-07-30T21:00:52.967Z","updated_at":"2025-04-30T00:12:35.307Z","avatar_url":"https://github.com/cisco.png","language":"Go","readme":"# elsy\n\n[![Build Status](https://travis-ci.org/cisco/elsy.svg?branch=master)](https://travis-ci.org/cisco/elsy)\n\nelsy (also known as lc, which is what the binary is called) is an opinionated,\nmulti-language, build-tool based on\n[Docker](https://github.com/docker/docker) and [Docker\nCompose](https://github.com/docker/compose). It allows organizations to\nimplement a consistent build workflow across many different repos, spanning a\nwide array of programming languages.\n\nelsy will not replace your favorite build tool, it is simply a thin wrapper that:\n\n- provides a consistent development workflow across all repos using elsy\n- provides the ability to fully test Docker images from a blackbox perspective\n- reduces local-dev tool requirements to the bare minimum, regardless of programming\nlanguage (i.e., you only need to install Docker, Compose, and elsy)\n- ensures consistent builds regardless of environment (i.e., fixes the \"works on\nmy machine\" problem since the repo defines its exact dependency requirements)\n\nWith elsy, it is possible to build, test, and publish a repo from scratch with just:\n\n```\ngit clone \u003crepo\u003e\ncd repo\nlc ci\n```\n\n## Getting Started\n\n**Prerequisites:** elsy requires both Docker and Docker Compose.\n\nFollow the below steps to install elsy:\n\n```\n## choose platform (darwin or linux) and versions (see releases page)\nPLATFORM=darwin\nVERSION=1.7.0\n\n## install binary for your system\ncurl -fL -o /usr/local/bin/lc https://github.com/cisco/elsy/releases/download/v$VERSION/lc-$PLATFORM-amd64-v$VERSION\nchmod +x /usr/local/bin/lc\n```\n\nAs of version v2.1.0 of Elsy, you can upgrade to the latest verison by running\n```\nlc system upgrade\n```\n\nPrevious versions require repeating the installation steps to manually download and\ninstall the binary.\n\nSee the [Using elsy in a Project](docs/configuringlcrepo.md) document for\ninfo on how to setup a repo to use elsy.\n\n## The Lifecycle\nAt its core, elsy is an implementation of a build lifecycle that generalizes to\nany repo producing a software artifact. Running `lc ci` will execute the\nfull build lifecycle inside a repo, it is made up of the stages defined in the\nfollowing sub-sections. `lc ci` operates in a fail-fast mode, so if any stage\nfails, the following stage will not be run.\n\nSee the [examples folder](./examples/README.md) for concrete examples of this\nlifecycle in action.\n\nSee [elsy Best Practices](docs/bestpractices.md) for guidance on how to use elsy\nfor typical development workflows.\n\n### lc teardown\nRunning `lc teardown` simply tells elsy to clean up any state that might be left\nover from a previous build.\n\n### lc bootstrap\nRunning `lc bootstrap` will setup a new repo and make sure all dependencies\n(e.g., docker images, external software libs) are downloaded and built. Thanks\nto Docker caching, this step is only time-intensive the first time it is run.\n\nIf present, bootstrap will call the repo's docker-compose `installdependencies`\nservice that will execute repo-specific command(s) to install external\nlibraries. See the `docker-compose.yml` file inside the elsy repo itself for an\nexample of this.\n\n### lc clean\nRunning `lc clean` will ensure artifacts from previous builds are removed. Typically,\nthis service is used before starting a new build. This is analogous to running\n`mvn clean` before running `mvn package`, for example. The `mvn`, `lein`, `make`,\nand `sbt` templates all define `clean` services, so if the project uses one of those,\nno additional work is required.\n\nThe difference between `clean` and `teardown`, which both\nperform similar actions, is that `teardown` only disposes of containers, whereas\n`clean` can remove artifacts from the local disk.\n\n### lc test\nRunning `lc test` will execute the repo's docker-compose `test` service, which will\nexecute repo-specific command(s) to run all unit and integration tests for the\ncode in that repo.\n\n### lc package\n\nRunning `lc package` will do two things. First it will execute the repo's (optional)\ndocker-compose `package` service, which will execute repo-specific command(s) for packaging\nthe repo's code into the final artifact. Second, if a `Dockerfile` is found in\nthe root of the repo, elsy will build that `Dockerfile` into a new Docker image that\nis ready for final testing and publishing.\n\nNote, when run on its own, `lc package` will also run `lc test` to\nensure you are packaging working code, you can prevent this by using the\n`--skip-tests` flag.\n\nWhen using elsy with Docker 1.11.1 and higher, `lc package` will apply the following\nimage labels during build time:\n\n- `com.elsy.metadata.git-commit=\u003cgit-commit\u003e` - The git commit that the image was\nbuilt from. The value of `\u003cgit-commit\u003e` is taken from the `GIT_COMMIT` env var\n(it is up to your  build system to populate this env var).\n\n### lc blackbox-test\nThis is where the real power of docker-based development comes into play.\n\nRunning `lc blackbox-test` will execute the repo's docker-compose\n`blackbox-test` service to run repo-specifc logic for testing the final\nartifact of the repo. This means that it is possible to test the real container\nbefore releasing it to production.\n\nFor example, if the repo is producing a Docker-based microservice that uses a Mysql\ndatabase, the `blackbox-test` service will:\n\n1. stand up the microservice container that was just packaged during `lc package`\n1. stand up a mysql container (and initialize the schema) for the microservice to use\n1. execute API-level tests against the microservice container to ensure it is\nfunctioning correctly with the database\n\nNote, when run on its own, `lc blackbox-test` will also run `lc package` to\nensure you  are testing the latest code, you can prevent this by using the\n`--skip-package` flag.\n\nYou can also run the blackbox tests by running `lc bbtest`.\n\nAt the end of the blackbox-test run, regardless of the outcome, all associated\ncontainers will be torn down. If you wish to leave them up, pass the\n`--keep-containers` option.\n\n### lc publish\nRunning `lc publish` does two things: First it will execute the repo's\n(optional) docker-compose `publish` service that will run repo-specific\ncommand(s) for publishing an artifact. This custom service is typically used for\nrepos that do not produce Docker images.\n\nSecond, if a Docker image was created during the `lc package` phase, elsy will\ncorrectly tag and publish that image to the registry defined in the `lc.yml`\nfile.\n\n`lc publish` uses the following rules when deciding what to publish:\n\n**For running the custom publish service:**\n\n- elsy will only run the custom publish service on branches with the pattern of:\n`origin/master` or `origin/release/\u003cname\u003e`, or on a valid elsy release git tag.\n\n**For tagging Docker images:**\n\n- If the git branch is `origin/master`, elsy will apply the tag `latest` to the\ndocker image.\n- If the git branch is `origin/release/\u003cname\u003e` elsy will apply the tag `\u003cname\u003e`\n- If the git branch is `origin/feature/\u003cname\u003e`, elsy will apply the tag\n`snapshot.feature.\u003cname\u003e` to the docker image.\n- If the git branch is `origin/\u003cname\u003e`, elsy will apply the tag `snapshot.\u003cname\u003e`\n- If a git tag exists and it is a valid elsy release tag, elsy will use that tag as\nthe docker image tag.\n\nIf you have defined a custom `publish` service in your `docker-compose.yml`, elsy\nwill pass the service an env var called `LC_PUBLISH_DOCKER_TAG` that contains\nthe tag elsy will use for the docker image, you just need to delcare the env\nvar like so:\n\n```\npublish:\n  image: busybox\n  environment:\n    - LC_PUBLISH_DOCKER_TAG\n  command: echo custom publish of tag $LC_PUBLISH_DOCKER_TAG\n```\n\n**Valid Git Relase Tag:**\n\nelsy currently considers a valid git release tag to be any tag following the\nschema:\n\n`vX.Y.Z[-Q]`\n\nWhere `X`, `Y` and `Z` are integers representing the Major, Minor, and Patch\nversion (respectively) and `Q` is an optional string qualifier. In the future we\nplan to make this schema configurable.\n\n### lc run\n\nRunning `lc run` will run a specific service that is contained in the `docker-compose.yml` file.\nThis is equivalent to `lc dc run ...`.\n\n## elsy Templates\n\nThe elsy lifecycle manifests itself in subtly different ways depending on the\nunderlying build tool. elsy ships with a small set of pre-baked templates (e.g.,\nmvn, sbt) that define a sensible default lifecycle for the build tool\nencapsulated by the template.\n\nSee the [elsy templates](./docs/templates.md) documentation for more information\non using templates.\n\n## Improving elsy Performance\n\nSee the [Improving Performance](docs/improving-performance.md) doc.\n\n## Contributing\n\nSee the [Contributing to elsy](docs/contributing.md) document.\n","funding_links":[],"categories":["Container Operations","Go","others"],"sub_categories":["Container Composition"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcisco%2Felsy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcisco%2Felsy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcisco%2Felsy/lists"}