Skip to content

Commit 8864acd

Browse files
bsideupbsideup
committed
Initial docs
1 parent 5fc3864 commit 8864acd

File tree

6 files changed

+256
-169
lines changed

6 files changed

+256
-169
lines changed

‎CONTRIBUTING.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Build with Maven
2+
3+
#### Prerequisites:
4+
5+
* Java min 1.8
6+
* Maven 3
7+
8+
Build and run integration tests as follows:
9+
10+
$ mvn clean install
11+
12+
If you do not have access to a Docker server or just want to execute the build quickly, you can run the build without the integration tests:
13+
14+
$ mvn clean install -DskipITs
15+
16+
By default the docker engine is using local UNIX sockets for communication with the docker CLI so docker-java
17+
client also uses UNIX domain sockets to connect to the docker daemon by default. To make the docker daemon listening on a TCP (http/https) port you have to configure it by setting the DOCKER_OPTS environment variable to something like the following:
18+
19+
DOCKER_OPTS="-H tcp://127.0.0.1:2375 -H unix:///var/run/docker.sock"
20+
21+
More details about setting up Docker Engine can be found in the official documentation: https://docs.docker.com/engine/admin/
22+
23+
To force docker-java to use TCP (http) configure the following (see [Configuration](https://github.com/docker-java/docker-java#configuration) for details):
24+
25+
DOCKER_HOST=tcp://127.0.0.1:2375
26+
27+
For secure tls (https) communication:
28+
29+
DOCKER_HOST=tcp://127.0.0.1:2376
30+
DOCKER_TLS_VERIFY=1
31+
DOCKER_CERT_PATH=/Users/marcus/.docker/machine/machines/docker-1.11.2
32+
33+
34+
# Code Design
35+
* Model is based on Objects and not primitives that allows nullify requests and have null values for data
36+
that wasn't provided by docker daemon.
37+
* For null safeness findbugs annotations are used.
38+
** Every method that may return `null` (and we are unsure in any fields as docker daemon may change something)
39+
should be annotated with `@CheckForNull` return qualifier from `javax.annotation` package.
40+
** Methods that can't return `null` must be annotated with `@Nonnull`.
41+
** The same for Arguments.
42+
** `@Nullable` must be used only for changing inherited (other typed) qualifier.
43+
* Setters in builder style must be prefixed with `withXX`.
44+
* All classes should provide `toString()` `equals()` and `hashCode()` defined methods.
45+
* Javadocs
46+
** Provide full information on field:
47+
*** For models define API version with `@since {@link RemoteApiVersion#VERSION_1_X}`.
48+
** getters/setters should refernce to field `@see #$field`.
49+
* If it is `Serializable` it shall have a `serialVersionUID` field. Unless code has shipped to users, the initial value of the `serialVersionUID` field shall be `1L`.
50+
51+
# Coding style
52+
* Some initial styling already enforced with checkstyle. Please aim for consistency with the existing code.
53+
54+
# Testing
55+
* Unit tests for serder (serialization-deserialization).
56+
* Integration tests for commands.
57+
* If model object has builders, then fill it with data and compare by `equals()` with expected response
58+
from docker daemon. If failed, then some fields mappings are wrong.

‎README.md‎

Lines changed: 1 addition & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -1,143 +1,9 @@
11
[![Join the chat at https://gitter.im/docker-java/docker-java](https://badges.gitter.im/docker-java/docker-java.svg)](https://gitter.im/docker-java/docker-java?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
22
[![Maven Central](https://img.shields.io/maven-central/v/com.github.docker-java/docker-java.svg)](https://mvnrepository.com/artifact/com.github.docker-java/docker-java)
3-
[![Bintray](https://api.bintray.com/packages/kostyasha/maven/com.github.docker-java%3Adocker-java/images/download.svg)](https://bintray.com/kostyasha/maven/com.github.docker-java%3Adocker-java/_latestVersion)
4-
[![Build Status](https://travis-ci.org/docker-java/docker-java.svg?branch=master)](https://travis-ci.org/docker-java/docker-java)
5-
[![Coverity Scan Build Status](https://scan.coverity.com/projects/9177/badge.svg?flat=1)](https://scan.coverity.com/projects/9177)
63
[![codecov.io](http://codecov.io/github/docker-java/docker-java/coverage.svg?branch=master)](http://codecov.io/github/docker-java/docker-java?branch=master)
74
[![License](http://img.shields.io/:license-apache-blue.svg?style=flat)](https://github.com/docker-java/docker-java/blob/master/LICENSE)
8-
9-
<!--[![Circle CI](https://circleci.com/gh/docker-java/docker-java.svg?style=svg)](https://circleci.com/gh/docker-java/docker-java)-->
105
# docker-java
116

127
Java API client for [Docker](http://docs.docker.io/ "Docker")
138

14-
[Changelog](https://github.com/docker-java/docker-java/blob/master/CHANGELOG.md)<br/>
15-
[Wiki](https://github.com/docker-java/docker-java/wiki)
16-
17-
## Build with Maven
18-
19-
###### Prerequisites:
20-
21-
* Java min 1.8
22-
* Maven 3
23-
24-
Build and run integration tests as follows:
25-
26-
$ mvn clean install
27-
28-
If you do not have access to a Docker server or just want to execute the build quickly, you can run the build without the integration tests:
29-
30-
$ mvn clean install -DskipITs
31-
32-
By default the docker engine is using local UNIX sockets for communication with the docker CLI so docker-java
33-
client also uses UNIX domain sockets to connect to the docker daemon by default. To make the docker daemon listening on a TCP (http/https) port you have to configure it by setting the DOCKER_OPTS environment variable to something like the following:
34-
35-
DOCKER_OPTS="-H tcp://127.0.0.1:2375 -H unix:///var/run/docker.sock"
36-
37-
More details about setting up Docker Engine can be found in the official documentation: https://docs.docker.com/engine/admin/
38-
39-
To force docker-java to use TCP (http) configure the following (see [Configuration](https://github.com/docker-java/docker-java#configuration) for details):
40-
41-
DOCKER_HOST=tcp://127.0.0.1:2375
42-
43-
For secure tls (https) communication:
44-
45-
DOCKER_HOST=tcp://127.0.0.1:2376
46-
DOCKER_TLS_VERIFY=1
47-
DOCKER_CERT_PATH=/Users/marcus/.docker/machine/machines/docker-1.11.2
48-
49-
### Latest release version
50-
[Maven repository modules](https://mvnrepository.com/artifact/com.github.docker-java)
51-
52-
Since 3.2.0 project provides 3 transports:
53-
- `docker-java-transport-jersey` (doesn't support streams)
54-
- `docker-java-transport-netty`
55-
- `docker-java-transport-okhttp`
56-
57-
For backward compatibility `docker-java` module keeping dependency only on jersey and netty transports.
58-
59-
<dependency>
60-
<groupId>com.github.docker-java</groupId>
61-
<artifactId>docker-java</artifactId>
62-
<!-- use latest version https://github.com/docker-java/docker-java/releases -->
63-
<version>3.X.Y</version>
64-
</dependency>
65-
66-
### Latest development version
67-
May contain new features while they are not released.
68-
69-
You can find the latest development version including javadoc and source files on [Sonatypes OSS repository](https://oss.sonatype.org/content/groups/public/com/github/docker-java/docker-java/).
70-
71-
<dependency>
72-
<groupId>com.github.docker-java</groupId>
73-
<artifactId>docker-java</artifactId>
74-
<version>3.X.Y-SNAPSHOT</version>
75-
</dependency>
76-
77-
78-
## Documentation
79-
80-
For code examples, please look at the [Wiki](https://github.com/docker-java/docker-java/wiki) or [Test cases](https://github.com/docker-java/docker-java/tree/master/docker-java/src/test/java/com/github/dockerjava/core/command "Test cases")
81-
82-
## Configuration
83-
84-
There are a couple of configuration items, all of which have sensible defaults:
85-
86-
* `DOCKER_HOST` The Docker Host URL, e.g. `tcp://localhost:2376` or `unix:///var/run/docker.sock`
87-
* `DOCKER_TLS_VERIFY` enable/disable TLS verification (switch between `http` and `https` protocol)
88-
* `DOCKER_CERT_PATH` Path to the certificates needed for TLS verification
89-
* `DOCKER_CONFIG` Path for additional docker configuration files (like `.dockercfg`)
90-
* `api.version` The API version, e.g. `1.23`.
91-
* `registry.url` Your registry's address.
92-
* `registry.username` Your registry username (required to push containers).
93-
* `registry.password` Your registry password.
94-
* `registry.email` Your registry email.
95-
96-
There are three ways to configure, in descending order of precedence:
97-
98-
#### Programmatic:
99-
In your application, e.g.
100-
101-
DockerClientConfig config = DefaultDockerClientConfig.createDefaultConfigBuilder()
102-
.withDockerHost("tcp://my-docker-host.tld:2376")
103-
.withDockerTlsVerify(true)
104-
.withDockerCertPath("/home/user/.docker/certs")
105-
.withDockerConfig("/home/user/.docker")
106-
.withApiVersion("1.30") // optional
107-
.withRegistryUrl("https://index.docker.io/v1/")
108-
.withRegistryUsername("dockeruser")
109-
.withRegistryPassword("ilovedocker")
110-
.withRegistryEmail("dockeruser@github.com")
111-
.build();
112-
DockerClient docker = DockerClientBuilder.getInstance(config).build();
113-
114-
#### Properties (docker-java.properties)
115-
116-
DOCKER_HOST=tcp://localhost:2376
117-
DOCKER_TLS_VERIFY=1
118-
DOCKER_CERT_PATH=/home/user/.docker/certs
119-
DOCKER_CONFIG=/home/user/.docker
120-
api.version=1.23
121-
registry.url=https://index.docker.io/v1/
122-
registry.username=dockeruser
123-
registry.password=ilovedocker
124-
registry.email=dockeruser@github.com
125-
126-
##### System Properties:
127-
128-
java -DDOCKER_HOST=tcp://localhost:2375 -Dregistry.username=dockeruser pkg.Main
129-
130-
##### System Environment
131-
132-
export DOCKER_HOST=tcp://localhost:2376
133-
export DOCKER_TLS_VERIFY=1
134-
export DOCKER_CERT_PATH=/home/user/.docker/certs
135-
export DOCKER_CONFIG=/home/user/.docker
136-
137-
##### File System
138-
139-
In `$HOME/.docker-java.properties`
140-
141-
##### Class Path
142-
143-
In the class path at `/docker-java.properties`
9+
# [Read the documentation here](docs/README.md)

‎docs/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
* [Getting Started](./getting_started.md)
2+
* [Available transports](./transports.md)

‎docs/devel.adoc‎

Lines changed: 0 additions & 34 deletions
This file was deleted.

‎docs/getting_started.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Getting Started
2+
3+
## Dependencies
4+
5+
To start using `docker-java` , you need to add at least two dependencies:
6+
1. `com.github.docker-java:docker-java-core` for the `DockerClient`
7+
1. one of `com.github.docker-java:docker-java-transport-*` to communicate with the Docker daemon. See [Available Transports](./transports.md) for more info.
8+
9+
The latest available version:
10+
[![Maven Central](https://img.shields.io/maven-central/v/com.github.docker-java/docker-java.svg)](https://mvnrepository.com/artifact/com.github.docker-java/docker-java)
11+
12+
13+
## Instantiating a `DockerClientConfig`
14+
15+
You will need an instance of `DockerClientConfig` to tell the library how to access Docker, which credentials to use to pull from Docker registries, etc etc.
16+
17+
The builder is available and allows you to configure every property of the client:
18+
```java
19+
DockerClientConfig standard = DefaultDockerClientConfig.createDefaultConfigBuilder().build();
20+
```
21+
22+
```java
23+
DockerClientConfig custom = DefaultDockerClientConfig.createDefaultConfigBuilder()
24+
.withDockerHost("tcp://docker.somewhere.tld:2376")
25+
.withDockerTlsVerify(true)
26+
.withDockerCertPath("/home/user/.docker")
27+
.withRegistryUsername(registryUser)
28+
.withRegistryPassword(registryPass)
29+
.withRegistryEmail(registryMail)
30+
.withRegistryUrl(registryUrl)
31+
.build();
32+
```
33+
34+
Here you can tune registry auth, DOCKER_HOST and other options.
35+
36+
There are a couple of configuration items, all of which have sensible defaults:
37+
38+
* `DOCKER_HOST` The Docker Host URL, e.g. `tcp://localhost:2376` or `unix:///var/run/docker.sock`
39+
* `DOCKER_TLS_VERIFY` enable/disable TLS verification (switch between `http` and `https` protocol)
40+
* `DOCKER_CERT_PATH` Path to the certificates needed for TLS verification
41+
* `DOCKER_CONFIG` Path for additional docker configuration files (like `.dockercfg`)
42+
* `api.version` The API version, e.g. `1.23`.
43+
* `registry.url` Your registry's address.
44+
* `registry.username` Your registry username (required to push containers).
45+
* `registry.password` Your registry password.
46+
* `registry.email` Your registry email.
47+
48+
There are three ways to configure, in descending order of precedence:
49+
50+
##### Properties (docker-java.properties)
51+
52+
DOCKER_HOST=tcp://localhost:2376
53+
DOCKER_TLS_VERIFY=1
54+
DOCKER_CERT_PATH=/home/user/.docker/certs
55+
DOCKER_CONFIG=/home/user/.docker
56+
api.version=1.23
57+
registry.url=https://index.docker.io/v1/
58+
registry.username=dockeruser
59+
registry.password=ilovedocker
60+
registry.email=dockeruser@github.com
61+
62+
##### System Properties:
63+
64+
java -DDOCKER_HOST=tcp://localhost:2375 -Dregistry.username=dockeruser pkg.Main
65+
66+
##### System Environment
67+
68+
export DOCKER_HOST=tcp://localhost:2376
69+
export DOCKER_TLS_VERIFY=1
70+
export DOCKER_CERT_PATH=/home/user/.docker/certs
71+
export DOCKER_CONFIG=/home/user/.docker
72+
73+
##### File System
74+
75+
In `$HOME/.docker-java.properties`
76+
77+
##### Class Path
78+
79+
In the class path at `/docker-java.properties`
80+
81+
### Jackson
82+
83+
Should you need to customize the Jackson's `ObjectMapper` used by `docker-java`, you can create your own `DockerClientConfig` and override `DockerClientConfig#getObjectMapper()`.
84+
85+
## Instantiating a `DockerHttpClient`
86+
Once you decided which transport to use, you will need to instantiate an HTTP client:
87+
```java
88+
DockerClientConfig config = ...;
89+
90+
DockerHttpClient httpClient = new ApacheDockerHttpClient.Builder()
91+
.dockerHost(config.getDockerHost())
92+
.sslConfig(config.getSSLConfig())
93+
.build();
94+
```
95+
96+
Please refer to selected transport's builder for other available configuration options (like timeouts).
97+
98+
Once you have an HTTP client, you can make raw requests to the Docker daemon directly:
99+
```java
100+
Request request = Request.builder()
101+
.method(Request.Method.GET)
102+
.path("/_ping")
103+
.build();
104+
105+
try (Response response = httpClient.execute(request)) {
106+
assertThat(response.getStatusCode(), equalTo(200));
107+
assertThat(IOUtils.toString(response.getBody()), equalTo("OK"));
108+
}
109+
```
110+
111+
## Instantiating a `DockerClient`
112+
113+
To get an instance of `DockerClient`, you need to pass both `DockerClientConfig` and `DockerHttpClient`:
114+
```java
115+
DockerClient dockerClient = DockerClientImpl.getInstance(config, httpClient);
116+
```
117+
118+
Once you have it, you can start executing Docker commands:
119+
```java
120+
dockerClient.pingCmd().exec();
121+
```

0 commit comments

Comments
 (0)