{"id":13416538,"url":"https://github.com/Tapad/sbt-docker-compose","last_synced_at":"2025-03-15T00:31:05.899Z","repository":{"id":141754230,"uuid":"50211751","full_name":"Tapad/sbt-docker-compose","owner":"Tapad","description":"Integrates Docker Compose functionality into sbt (archived as unmaintained)","archived":true,"fork":false,"pushed_at":"2022-09-23T21:25:44.000Z","size":741,"stargazers_count":177,"open_issues_count":18,"forks_count":36,"subscribers_count":54,"default_branch":"master","last_synced_at":"2024-07-31T21:57:11.336Z","etag":null,"topics":["docker","docker-compose","sbt","sbt-docker-compose","sbt-plugin","scala","scalatest"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tapad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-01-22T22:34:54.000Z","updated_at":"2024-05-29T12:11:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"139303b9-1e0c-4d12-8884-20a14b08238b","html_url":"https://github.com/Tapad/sbt-docker-compose","commit_stats":null,"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tapad%2Fsbt-docker-compose","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tapad%2Fsbt-docker-compose/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tapad%2Fsbt-docker-compose/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tapad%2Fsbt-docker-compose/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tapad","download_url":"https://codeload.github.com/Tapad/sbt-docker-compose/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243667696,"owners_count":20328032,"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":["docker","docker-compose","sbt","sbt-docker-compose","sbt-plugin","scala","scalatest"],"created_at":"2024-07-30T21:01:00.416Z","updated_at":"2025-03-15T00:31:05.892Z","avatar_url":"https://github.com/Tapad.png","language":"Scala","readme":"sbt-docker-compose\n==================\n\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.tapad/sbt-docker-compose/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.tapad/sbt-docker-compose)\n\nAbout\n-----\nsbt-docker-compose is an sbt plugin that integrates the functionality of [Docker Compose](https://docs.docker.com/compose/) \ndirectly into the sbt build environment. This allows you to make code changes and with one sbt command start up a local \nrunning instance of your latest changes connected to all of its dependencies for live testing and debugging. This plugin \nis designed to be extended to allow for instances to be launched in non-local environments such as AWS and Mesos.\n\n![Alt text](/screenshots/dockerComposeUp.png?raw=true \"dockerComposeUp output\")\n\nPrerequisites\n-------------\nYou must have [Docker](https://docs.docker.com/engine/installation/) and \n[Docker-Compose](https://docs.docker.com/compose/install/) installed.\n\nSteps to Enable and Configure sbt-docker-compose\n------------------------------------------------\n\n1) Add the sbt-docker-compose plugin to your projects plugins.sbt file:\n   ```\n   addSbtPlugin(\"com.tapad\" % \"sbt-docker-compose\" % \"1.0.35\")\n   ``` \n   sbt-docker-compose is an auto-plugin which requires that sbt version 0.13.5+ or sbt version 1.0.0+ be used.\n   \n2) Enable the plugin on the sbt projects you would like to test:\n   ```\n   enablePlugins(DockerComposePlugin)\n   ``` \n\n3) Configure your sbt project(s) to build Docker images by setting the 'dockerImageCreationTask':\n \n  - The [sbt-docker](https://github.com/marcuslonnberg/sbt-docker) plugin can be used by setting:\n    ```\n    dockerImageCreationTask := docker.value\n    ```\n    \n  - The [sbt-native-packager](https://github.com/sbt/sbt-native-packager) plugin can be used by setting:\n    ```\n    dockerImageCreationTask := (publishLocal in Docker).value\n    ```\n   See the [basic-native-packager](examples/basic-native-packager) example for more details.\n   \n4) Define a [docker-compose.yml](https://docs.docker.com/compose/compose-file/) file which describes your component, \nits dependent images and the links between them. This path to this file can be explicitly defined or by default the\nplugin will attempt to locate it in one of three places with the precedence order:\n   \n   - The 'resources' directory of the project as defined by the sbt 'resourceDirectory' setting.\n   \n   - A 'docker' directory off of the root of the project.\n   \n   - In the root of the project directory.\n\n5) Optional: There are a number of optional Keys that can be set as well if you want to override the default settings:\n   ```\n    composeContainerPauseBeforeTestSeconds := //Delay between containers start and test execution, seconds. Default is 0 seconds - no delay\n    composeFile := // Specify the full path to the Compose File to use to create your test instance. It defaults to docker-compose.yml in your resources folder.   \n    composeServiceName := // Specify the name of the service in the Docker Compose file being tested. This setting prevents the service image from being pull down from the Docker Registry. It defaults to the sbt Project name.\n    composeServiceVersionTask := // The version to tag locally built images with in the docker-compose file. This defaults to the 'version' SettingKey.\n    composeNoBuild := // True if a Docker Compose file is to be started without building any images and only using ones that already exist in the Docker Registry. This defaults to False.\n    composeRemoveContainersOnShutdown := // True if a Docker Compose should remove containers when shutting down the compose instance. This defaults to True.\n    composeRemoveNetworkOnShutdown := // True if a Docker Compose should remove the network it created when shutting down the compose instance. This defaults to True.\n    composeContainerStartTimeoutSeconds := // The amount of time in seconds to wait for the containers in a Docker Compose instance to start. Defaults to 500 seconds.\n    composeRemoveTempFileOnShutdown := // True if a Docker Compose should remove the post Custom Tag processed Compose File on shutdown. This defaults to True.\n    dockerMachineName := // If running on OSX the name of the Docker Machine Virtual machine being used. If not overridden it is set to 'default'\n    dockerImageCreationTask := // The sbt task used to create a Docker image. For sbt-docker this should be set to 'docker.value' for the sbt-native-packager this should be set to '(publishLocal in Docker).value'.\n    suppressColorFormatting := // True to suppress all color formatting in the output from the plugin. This defaults to the value of the 'sbt.log.noformat' property. If you are using `sbt-extras`, the use of the command line switch `-no-colors` will set this to True.\n    testTagsToExecute := // Set of ScalaTest Tags to execute when dockerComposeTest is run. Separate multiple tags by a comma. It defaults to executing all tests.\n    testExecutionArgs := // Additional ScalaTest Runner argument options to pass into the test runner. For example, this can be used for the generation of test reports.\n    testExecutionExtraConfigTask := // An sbt task that returns a Map[String,String] of variables to pass into the ScalaTest Runner ConfigMap (in addition to standard service/port mappings).\n    testDependenciesClasspath := // The path to all managed and unmanaged Test and Compile dependencies. This path needs to include the ScalaTest Jar for the tests to execute. This defaults to all managedClasspath and unmanagedClasspath in the Test and fullClasspath in the Compile Scope.\n    testCasesJar := // The path to the Jar file containing the tests to execute. This defaults to the Jar file with the tests from the current sbt project.\n    testCasesPackageTask := // The sbt Task to package the test cases used when running 'dockerComposeTest'. This defaults to the 'packageBin' task in the 'Test' Scope.\n    testPassUseSpecs2 := // True if Specs2 is to be used to execute the test pass. This defaults to False and ScalaTest is used.\n    testPassUseCucumber := // True if cucumber is to be used to execute the test pass. This defaults to False and ScalaTest is used.\n    variablesForSubstitution := // A Map[String,String] of variables to substitute in your docker-compose file. These are substituted substituted by the plugin and not using environment variables.\n    variablesForSubstitutionTask := // An sbt task that returns a Map[String,String] of variables to substitute in your docker-compose file. These are substituted by the plugin and not using environment variables.\n   ```\nThere are several sample projects showing how to configure sbt-docker-compose that can be found in the [**examples**](examples) folder.\n\nTo Start a Docker Compose Instance for Testing / Debugging\n----------------------------------------------------------\n1) To start a new instance from the project with the Plugin enabled run:\n   ```\n   dockerComposeUp\n   ``` \n    \n   To use locally built images for all services defined in the Docker Compose file instead of pulling from the Docker \n   Registry use the following command:\n   ```\n   dockerComposeUp skipPull\n   ``` \n    \n    \n   By default before starting a Docker Compose instance a new Docker image will be built with your latest code changes.\n   If you know you didn't make any code changes and do not want to build a new image use the 'skipBuild' argument:\n   ```\n   dockerComposeUp skipBuild\n   ``` \n    \n   You can start multiple compose instances on the same project as the plugin generates a unique name for each instance.\n   \n   When making frequent code changes on your local machine it is often useful to temporarily have the external ports remain the same. \n   Use the '-useStaticPorts' argument to enable this functionality:\n   \n   ```\n    dockerComposeUp -useStaticPorts\n    \n    E.g. A port mapping of \"0:3306\" defined in the Compose file would be treated as \"3306:3306\" if this argument is supplied.\n   ``` \n         \n2) To shutdown all instances started from the current project with the Plugin enabled run:\n   ```\n    dockerComposeStop\n   ```   \n   To shutdown a specific instance regardless of the sbt project it belongs to run:\n   ```  \n    dockerComposeStop \u003cunique instance id\u003e\n   ```\n3) To restart a particular instance from the project with the Plugin enabled run:\n   ```\n    dockerComposeRestart \u003cunique instance id\u003e\n   ```  \n   You can also supply the 'skipPull', 'skipBuild' or '-useStaticPorts' argument as you would for the 'dockerComposeUp' command:\n   ```   \n   dockerComposeRestart \u003cunique instance id\u003e [skipPull or skipBuild] [-useStaticPorts]\n   ```    \n   If there is only one running instance from the current sbt project the Instance Id is not required:\n   ```   \n    dockerComposeRestart\n   ```   \n   If there is no running instances from the current sbt project this command will start a new instance from the project.\n       \n4) To display the service connection information for each running Docker Compose instance run:\n   ```\n    dockerComposeInstances\n   ```   \nInstance information is persisted in a temporary file so that it will be available between restarts of an sbt session.\n\n5) You can use tab completion to list out all of the arguments for each command shown above.\n\nTo Execute ScalaTest Test Cases Against a Running Instance\n----------------------------------------------------------\nThe sbt-docker-compose plugin provides the ability to run a suite of ScalaTest test cases against a Docker Compose instance.\nThe dynamically assigned host and port information are passed into each test case via the \nScalaTest [ConfigMap](http://doc.scalatest.org/2.0/index.html#org.scalatest.ConfigMap).\n\nThe key into the map is the \"serviceName:containerPort\" (e.g. \"basic:8080\") that is statically defined in the Docker Compose file and it \nwill return \"host:hostPort\" which is the Docker Compose generated and exposed endpoint that can be connected to at runtime\nfor testing. There is also the key \"serviceName:containerId\" (e.g. \"basic:containerId\") which maps to the docker container id.\n\nThe same ConfigMap key/value pairs are also available in the underlying JVM as system properties. For example,\nSystem.getProperty(\"serviceName:containerPort\"), which is useful when the application uses system properties to set configuration\nduring boot, which is a common pattern in Play Framework using TypeSafe's ConfigFactory.\n\nSee the [**basic-with-tests**](examples/basic-with-tests) example for more details.\n\nBy default all tests will be executed, however you can also [Tag](http://www.scalatest.org/user_guide/tagging_your_tests)\ntest cases and indicate to the plugin to only execute those tests:\n   ``` \n    testTagsToExecute := \"DockerComposeTag\"\n   ```\n1) To start a new DockerCompose instance, run your tests and then shut it down run:\n   ```\n    dockerComposeTest\n   ```    \n2) To run your test cases against an already running instance execute:\n   ```\n    dockerComposeTest \u003cinstance id\u003e\n   ```    \n3) To override the sbt setting 'testTagsToExecute' when starting a test pass provide a comma separated list of tags to\nthe \"-tags\" argument:\n   ```\n    dockerComposeTest -tags:\u003ctag1,tag2\u003e\n   ```    \n   \n   If running dockerComposeTest from outside of sbt you will need to quote the input so that the parameters are properly interpreted:\n   ```\n    sbt 'dockerComposeTest -tags:\u003ctag1,tag2\u003e'\n   ```    \n      \n4) To attach a debugger during test case execution provide a port number to the \"-debug\" argument. This will suspend the\ntests from running until you attach a debugger to the specified port. For example:\n   ```\n    dockerComposeTest \u003cinstance id\u003e -debug:\u003cdebug port\u003e\n   ```    \n**Note:** The test pass is started using the using the 'java' process that exists on your command line PATH to launch the\n[ScalaTest Test Runner](http://www.scalatest.org/user_guide/using_the_runner). For this to work the classpath of your\nproject needs to be built with the version of scala used by the project. If this is not configured correctly you may see\nan issue with the Test Runner failing to load classes.\n\nThere is also support for running [Specs2](https://etorreborre.github.io/specs2/) test cases. For these tests only the \nJVM system properties will be available for accessing information about the Docker Compose instance under test.\n\nSee the [**basic-with-tests-specs2**](examples/basic-with-tests-specs2) example for more details.\n\nDocker Compose File Custom Tags\n-------------------------------\nCustom tags are a feature of the sbt-docker-compose plugin that add the ability to pre-process the contents of the \ndocker-compose.yml file and make modifications to it before using it to start your instance. There are two custom tags \nfor images that this plugin supports: \"\\\u003clocalBuild\\\u003e\" and \"\\\u003cskipPull\\\u003e\". Support for additional tags can be added by \noverriding the \"processCustomTags\" method.\n\n1) Define \"\\\u003cskipPull\\\u003e\" on a set of particular images in the docker-compose file that you want to use a local copy of \ninstead of pulling the latest available from the Docker Registry.\n   ```\n    image: yourregistry.com/service:1.0.0\u003cskipPull\u003e\n   ```   \n2) Define \"\\\u003clocalBuild\\\u003e\" to launch the locally built version of the image instead of pulling from the public Docker \nRegistry. This is how associated images from multi-project builds should be tagged. \nSee the [**multi-project**](examples/multi-project) example.\n   ```   \n    image: service:latest\u003clocalBuild\u003e\n   ```    \nInstance Connection Information\n-------------------------------\nAfter launching an instance with a dockerComposeUp command a table like the one below will be output with the set of endpoints \nthat can be used to connect to the instance. The 'Host:Port' column contains the endpoints that are externally exposed.\n   ```\n    +---------+----------------------+-------------+--------------+----------------+--------------+---------+\n    | Service | Host:Port            | Tag Version | Image Source | Container Port | Container Id | IsDebug |\n    +=========+======================+=============+==============+================+==============+=========+\n    | sample1 | 192.168.99.100:32973 | latest      | build        | 5005           | 0a43860a47a8 | YES     |\n    | sample2 | 192.168.99.100:32974 | latest      | build        | 5005           | 54803f8a6938 | YES     |\n    +---------+----------------------+-------------+--------------+----------------+--------------+---------+\n   ```\nThe 'Image Source' column can be one of the following values:\n\n1) **defined**: The image tag is hardcoded in the compose file. For example:\n   ```\n    image: service:latest\n    \n    image: yourregistry.com/service:1:0:0\n   ```\n2) **build**: The image was built when starting the topology instance or the image is tagged as \"\\\u003clocalBuild\\\u003e\" and \nbeing used in a muti-project sbt compose-file. \n   ```\n    image: service:latest\u003clocalBuild\u003e\n   ```    \n3) **cache**: The locally cached version of the image is being used even if there may be a new version in the Docker \nRegistry. This is the result of \"\\\u003cskipPull\\\u003e\" being defined on a particular image or being passed to dockerComposeUp.\n   ```\n    image: service:latest\u003cskipPull\u003e\n   ```   \nEach running instance will also output the commands that can be used to:\n\n1) **Stop the running instance.** For example:\n   ```    \n    dockerComposeStop 449342\n   ```\n2) **Open a command shell to the container instance:**\n   ```\n    docker exec -it \u003cContainer Id\u003e bash\n   ```\n3) **View the standard out logging from the instance:**\n   ``` \n    docker-compose -p 449342 -f /tmp/compose-updated4937097142223953047.yml logs\n   ```\n4) **Execute test cases against the running instance:**\n   ``` \n    dockerComposeTest \u003cInstance Id\u003e\n   ```   \n                                                                                                          \nDebugging\n---------\nTo debug a Docker Compose Java process edit your docker-compose.yml file to set the JAVA_TOOL_OPTIONS environment variable.\nIn the ports section you will also need to expose the port value defined in the \"address=\" parameter.\n   ```\n    environment:\n        JAVA_TOOL_OPTIONS: -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005\n    ports:\n        - \"0:5005\"\n   ```\nOnce the container is started you can to attach to it remotely. The instance connection table will mark 'YES' in the 'IsDebug'\ncolumn for any exposed ports that can be attached to with the debugger. \nSee the [basic](examples/basic-with-tests/docker/docker-compose.yml) example for a project configured with debugging enabled.\n\nSee the test case execution section above for information on how to attach a debugger to running test cases.\n\nExamples\n--------\nIn the [**examples**](examples) folder there are six different projects showing different uses for the \nsbt-docker-compose plugin.\n\n1) [**basic-with-tests**](examples/basic-with-tests): This project outlines a very basic example of how to enable the\nplugin on a simple application that will echo back \"Hello, World!\". The examples also shows how to create a ScalaTest \ntest case that can run against the dynamically assigned endpoints. From sbt run the following to compile the code, \nbuild a Docker image and launch a Docker Compose instance.\n   ```\n    dockerComposeUp\n   ```   \nRun the following to execute a test case against the running instance:\n   ```\n    dockerComposeTest \u003cInstance Id\u003e\n   ```\nRun the following to start a new instance, run tests and shutdown the instance:\n   ```\n    dockerComposeTest\n   ```\nNote how this example project shows how the testExecutionArgs setting can be used to create an html test pass report by\nby providing additional ScalaTest Runner defined [arguments](http://www.scalatest.org/user_guide/using_the_runner).\n   ```\n    //Specify that an html report should be created for the test pass\n    testExecutionArgs := \"-h target/htmldir\"\n   ```\n2) [**basic-native-packager**](examples/basic-native-packager): This project outlines a very basic example of how to\nenable the plugin on a simple application. From sbt run the following to compile the code, build a Docker image and \nlaunch a Docker Compose instance. In this example the sbt-native-packager is used to build the Docker image instead of \nsbt-docker.\n   ```\n    dockerComposeUp\n   ```\n3) [**no-build**](examples/no-build): This project shows how sbt-docker-compose can be used to launch instances of \nimages that are already published and do not need to be built locally. This example uses the official Redis image \nfrom Docker Hub. Once the instance is started Redis will be available on the displayed \"Host:Port\". The port is\ndynamically assigned so that multiple instances can be started.\n   ```\n    dockerComposeUp\n   ```\n4) [**multi-project**](examples/multi-project): This project shows how more advanced multi-project builds are supported.\nFrom sbt you can build the Docker image and launch a running instance of a single project by executing:\n   ```\n    project sample1\n    dockerComposeUp\n   ```    \nHowever, from the root \"multi-project\" you can run the following to build new Docker images for both sub projects and \nlaunch a running instance that consists of both images:\n   ```\n    project multi-project\n    dockerComposeUp\n   ```   \nNote how the docker-compose.yml file for the root project tags each image with \"\\\u003clocalBuild\\\u003e\". This allows dockerComposeUp \nto know that these images should not be updated from the Docker Registry.\n\n5) [**basic-variable-substitution**](examples/basic-variable-substitution): This project demonstrates how you can re-use your \nexisting docker-compose.yml with [variable substitution](https://docs.docker.com/compose/compose-file/#variable-substitution) \nusing sbt-docker-compose.  Instead of passing your variables as environment variables you can define them in your build.sbt \nprogrammatically.\n\nbuild.sbt:\n   ```\n    variablesForSubstitution := Map(\"SOURCE_PORT\" -\u003e \"5555\")\n    \n    or\n    \n    variablesForSubstitutionTask := { /* code */ Map(\"SOURCE_PORT\" -\u003e \"5555\") }\n   ```    \ndocker-compose.yml:\n   ```\n    basic:\n      image: basic:1.0.0\n      environment:\n        JAVA_TOOL_OPTIONS: -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005\n      ports:\n        - \"${SOURCE_PORT}:5005\"\n   ```\n6) [**basic-with-tests-integration**](examples/basic-with-tests-integration): This project shows how to change the default sbt Scope of the\ntests being executed from 'Test' to 'IntegrationTest' when 'dockerComposeTest' is run.\n\n7) [**basic-with-tests-spec2**](examples/basic-with-tests-specs2): This project shows how to execute Specs2 based test cases via the 'specs2.files' runner\nby setting the following property in build.sbt:\n\n   ```\n    testPassUseSpecs2 := true\n   ```\n   \nAdditionally, you can override the default Specs2 file runner properties as follows:\n\n   ```\n    testExecutionExtraConfigTask := Map(\"filesrunner.verbose\" -\u003e \"true\")\n   ```\n\n8) [**basic-with-tests-cucumber**](examples/basic-with-tests-cucumber): This project shows how to execute cucumber based test cases \nby setting the following property in build.sbt:\n\n   ```\n    testPassUseCucumber := true\n   ```\n\n\nCurrently Unsupported Docker Compose Fields\n-------------------------------------------\n1) \"build:\" - All docker compose services need to specify an \"image:\" field.\n\n2) \"container_name:\" - To allow for multi-instance support container names need to be dynamically provided by the plugin\n instead of being explicitly defined.\n\n3) \"extends:\" - All docker services must be defined in a single docker compose yml file.\n\nOther\n-----\nTesting of sbt-docker-compose has been performed starting with docker-compose version: 1.5.1\n","funding_links":[],"categories":["Development with Docker","Dev Tools"],"sub_categories":["API Client"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTapad%2Fsbt-docker-compose","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTapad%2Fsbt-docker-compose","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTapad%2Fsbt-docker-compose/lists"}