From 449871bd0921decc8671bb1d084feb8d4ca70f79 Mon Sep 17 00:00:00 2001 From: Fabio Burzigotti <34456377+fabiobrz@users.noreply.github.com> Date: Wed, 15 Jan 2025 11:13:33 +0100 Subject: [PATCH] [issue-1344] - More fixes to the project documentation for 2.0.0 release (#1347) --- README.adoc | 2 +- docs/build-containers.adoc | 2 +- docs/compose.adoc | 21 +++++++++++++++------ docs/configuration.adoc | 19 ++----------------- docs/drone.adoc | 2 -- docs/enrichers.adoc | 2 +- docs/requirements.adoc | 19 +++++++++++-------- docs/restassured.adoc | 3 ++- docs/what-is-this.adoc | 2 +- 9 files changed, 34 insertions(+), 38 deletions(-) diff --git a/README.adoc b/README.adoc index b39e1946a..f3414735a 100644 --- a/README.adoc +++ b/README.adoc @@ -11,7 +11,7 @@ :toc: left WARNING: 2.0.0.Alpha1 breaks compatibility with previous versions as _boot2docker_ and _DockerMachine_ support has -been removed. This means that support for Windows and macOS is removed from 2.x. +been removed. This means that support for Windows and macOS or the Docker Machine usage is removed from 2.x. We're in the process of evaluating whether to add such support to the 2.x stream again, or to adopt different solutions. In such a case we'd probably release a 1.x version, which would still support such components. diff --git a/docs/build-containers.adoc b/docs/build-containers.adoc index 38a6bcd7c..cdedaf0d6 100644 --- a/docs/build-containers.adoc +++ b/docs/build-containers.adoc @@ -1,6 +1,6 @@ == Building containers -To build a container _Docker_ uses a file called `Dockerfile` http://docs.docker.com/reference/builder/. +To build a container _Docker_ uses a file called `Dockerfile` https://docs.docker.com/reference/dockerfile/. *Arquillian Cube* also supports building and running a container from a `Dockerfile`. To set that *Arquillian Cube* must build the container, the `image` property must be changed to `buildImage` and add the location of `Dockerfile`. diff --git a/docs/compose.adoc b/docs/compose.adoc index 2eb850290..a30c8af0a 100644 --- a/docs/compose.adoc +++ b/docs/compose.adoc @@ -1,15 +1,24 @@ [[docker-compose-format]] == Docker-Compose Format -Instead of using Arquillian Cube format, you can use Docker Compose format to define containers layout. This means that you can use the same Docker Compose file for running your tests with Arquillian Cube and without any change run `docker-compose up` command from terminal and get the same result. +Instead of using Arquillian Cube format, you can use https://docs.docker.com/reference/compose-file/[Docker Compose V2 format] +to define containers layout. +This means that you can use the same Docker Compose file for running your tests with Arquillian Cube, and without any +change run `docker-compose up` command from terminal and get the same result. -It is important to note that this is not a docker-compose implementation but only the docker-compose format. This means that for example you cannot execute some CLI commands of _docker-compose_ like start several instances of same service. +It is important to note that this is not a docker-compose implementation but only the docker-compose format. +This means that for example you cannot execute some CLI commands of _docker-compose_, like to start several instances of same service. -In case of some specific Arquillian Cube attributes like await strategy cannot be configured and the default values are going to be used. +Another limitation is that some specific Arquillian Cube attributes, like await strategy, cannot be configured and the +default values are used. -Moreover, there are some docker-compose commands that are not implemented yet due to restrictions on docker-java library. These commands are _pid_, _log_driver_ and _security_opt_. But they will be implemented as soon as docker-java library adds their support. +Moreover, there are some docker-compose commands that are not implemented yet due to restrictions on docker-java library. +These commands are _pid_, _log_driver_ and _security_opt_. +But they will be implemented as soon as docker-java library adds their support. -Last thing, in case you define a command that is not implemented in Arquillian Cube, this command will be ignored (no exception will be thrown), but a log line will be printed notifying this situation. Please it is really important that if this happens you open a bug so we can add support for them. Although this warning we will try to maintain aligned with the latest docker-compose format. +Last thing, in case you define a command that is not implemented in Arquillian Cube, this command will be ignored +(no exception will be thrown), but a log line will be printed notifying this situation. +Please it is really important that if this happens you open a bug, so we can add support for them. Let's see how you can rewrite previous HelloWorld example with Tomcat, using docker-compose format. @@ -95,4 +104,4 @@ For example in case of using Maven, your `pom.xml` should look like: Notice that you don't need to specify _definitionFormat_ since docker compose format is the default one. And that's all, you can now reuse your existing docker-compose files in Arquillian Cube too. -You can see the full example at: https://github.com/arquillian/arquillian-cube/tree/main/docker/ftest-docker-compose +You can see the full example at: https://github.com/arquillian/arquillian-cube/tree/main/docker/ftest-docker-compose-v2 diff --git a/docs/configuration.adoc b/docs/configuration.adoc index 97c45d79e..396766ad2 100644 --- a/docs/configuration.adoc +++ b/docs/configuration.adoc @@ -50,15 +50,6 @@ The following table summarizes the attributes that are currently supported: |certPath |Path where certificates are stored. If you are not using _https_ protocol this parameter is not required. This parameter accepts starting with ~ as home directory. -|machineName -|Sets the machine name in case you are using docker-machine to manage your docker host. This parameter is mandatory when using docker-machine with more than one running machine. In case of having only one docker machine running, it is not necessary to set it since it is auto resolved by cube. - -|machineDriver -|Sets the machine driver in case you are using _docker-machine_. This parameter is mandatory when docker-machine is not installed. - -|dockerMachineCustomPath -|Sets the custom location where _docker-machine_ will be downloaded. Default value: ~/.arquillian/machine. - |dockerInsideDockerResolution |Boolean to set if Cube should detect that tests are run inside an already started Docker container, so Docker containers started by Cube could be run using DinD (Docker Inside Docker) or DoD (docker On Docker). Basically it ignores any `SERVER_URI` properties and sets the `serverUri` to `unix:///var/run/docker.sock`. By default, its value is set to true. If you want to use an external dockerhost, then you need to set this property to false. @@ -91,9 +82,6 @@ as well. |certPath |DOCKER_CERT_PATH - -|machineName -|DOCKER_MACHINE_NAME |=== @@ -183,7 +171,7 @@ tomcat: # <1> <9> You can extend another configuration. Any top level element and it's children from the target container-id will be copied over to this configuration, unless they have been defined here already. <10> You can use `manual` to indicate that this container is going to be started or in the test manually using `CubeController` or started by an extension. This attribute is ingorned in case of arquillian containers (none autostart containers) or in case of a linked container that comes from a none manual container. <11> Kills the container instead of stopping it normally. By default, it is set to false, so that containers are stopped. -<12> Alternate hostname for use with the builtin DNS for https://docs.docker.com/engine/userguide/networking/#user-defined-networks[docker'suser defined networks]. +<12> Alternate hostname for use with the builtin DNS for https://docs.docker.com/engine/network/#user-defined-networks[docker'suser defined networks]. As we've seen in the basic example the definition of the Arquillian Cube scenarios are described in `dockerContainers` property. But if you want you can avoid using this property by simply creating a file called `cube` in the root of the classpath of your project. @@ -520,7 +508,7 @@ STARTORCONNECTANDLEAVE:: it is exactly the same of _STARTORCONNECT_ but if conta === Before Stop Events -Sometimes when the tests has finished and container is stopped you want to inspect some data like container console or getting a file from the container to manual inspecting. +Sometimes when the tests have finished and container is stopped you want to inspect some data like container console or getting a file from the container to manual inspecting. In these cases you can configure each container to copy console log or copy a file/s from container to local machine just before container is stopped. Or if your need is more specific, you can provide a custom implementation @@ -636,7 +624,4 @@ This parameter is not mandatory and in case you don't set it, _Arquillian Cube_ |=== |Linux |unix:///var/run/docker.sock - -|Docker Machine -|tcp://dockerHost:2376 |=== diff --git a/docs/drone.adoc b/docs/drone.adoc index 6d34f36f8..6d7a71468 100644 --- a/docs/drone.adoc +++ b/docs/drone.adoc @@ -82,11 +82,9 @@ Configure the Cube extension: .arquillian.xml ---- - dev docker-compose.yml ---- -<1> In case of using more than one docker machine instance, you need to set it manually. And finally among `cube` dependencies, add the `drone`, `selenium` and `cube-drone` dependencies. diff --git a/docs/enrichers.adoc b/docs/enrichers.adoc index 409bc08a5..25fc51b83 100644 --- a/docs/enrichers.adoc +++ b/docs/enrichers.adoc @@ -307,7 +307,7 @@ Suppose you have a _Docker Container_ configuration like: <1> Note that the exposed port is the 8081. Then in theory you should configure the remote _Tomcat_ adapter to port 8081 on your _arquillian.xml_ file. -But let's say that you are using that remote adapter for a remote local machine _Tomcat_ (outside _Docker_) too, and is configured to use 8080 port. +But let's say that you are using that remote adapter for a remote local _Tomcat_ (outside _Docker_) too, and is configured to use 8080 port. [source, xml] .arquillian.xml diff --git a/docs/requirements.adoc b/docs/requirements.adoc index 5e1a2eb69..8c1c2f809 100644 --- a/docs/requirements.adoc +++ b/docs/requirements.adoc @@ -80,7 +80,7 @@ whether _just_ an environment variable or a system property ar set. === Example with OpenShift 4 -The `openshift` module also defines an annotation for checking the environment against a given docker machine existence. +The `openshift` module also defines an annotation for checking the environment against an OpenShift 4 cluster existence. [source, java] ---- @@ -131,14 +131,17 @@ And the implementation logic: public class DockerRequirement implements Requirement { @Override - public void check(RequiresDockerMachine context) throws UnsatisfiedRequirementException { - String name = context.name(); - if (name != null && !name.isEmpty()) { - String installedVersion = getDockerVersion(); - - if (!name.equals(installedVersion)) { - throw new UnsatisfiedRequirementException("Docker version not specified."); // <1> + public void check(RequiresDocker context) throws UnsatisfiedRequirementException { + try { + Map config = resolver.resolve(new HashMap()); + String serverUrl = config.get(CubeDockerConfiguration.DOCKER_URI); + if (Strings.isNullOrEmpty(serverUrl)) { + throw new UnsatisfiedRequirementException("Could not resolve the docker server url."); // <1> + } else if (!isDockerRunning(serverUrl)) { + throw new UnsatisfiedRequirementException("No server is running on url:[" + serverUrl + "]."); } + } catch (ExecutionException e) { + throw new UnsatisfiedRequirementException("Cannot execute docker command."); } } } diff --git a/docs/restassured.adoc b/docs/restassured.adoc index 3c5081055..88c291fd5 100644 --- a/docs/restassured.adoc +++ b/docs/restassured.adoc @@ -37,7 +37,8 @@ spec = new RequestSpecBuilder() Previous approach works but it has some problems: * You need to repeat the same configuration properties in all tests you want to use Rest-Assured with Docker. -* Requires some development interference of the developer, if it is running in docker machine needs to set one _ip_ which might change in the future, or if running on native linux must be changed to _localhost_. +* Requires some development interference of the developer, if it is running in docker machine one _ip_ must be set which might change in the future, + or changed to _localhost_ if running on native linux. * Any change on Rest-Assured configuration properties would make all tests fails. To fix these problems, you can use Arquillian Cube Docker RestAssured integration which creates a `RequestSpecBuilder` diff --git a/docs/what-is-this.adoc b/docs/what-is-this.adoc index 456639f67..e7b533bae 100644 --- a/docs/what-is-this.adoc +++ b/docs/what-is-this.adoc @@ -22,7 +22,7 @@ _Kubernetes_ and _OpenShift_ versions, but we had to take some decisions about d capacity reasons: - *Arquillian Cube 2.0.0 does not support execution on _Windows_ and _macOS_ machines anymore*, since the *Boot2Docker* -and *Docker machine* integrations have been removed, due to deprecation. + integration has been removed, and it no longer supports *Docker Machine* integration, due to deprecation. We're aware this might be an issue in some cases, and we're open to community discussion about any options that could help mitigate the consequences, like temporarily resuming the integration in a sustaining branch. Feel free to