Tuesday 18 April 2017

Docker crib sheet

Here are a list of commands that are useful for docker, docker-machine and docker-compose

Listings

// See what docker containers are running
> docker ps

// See which images exist
> docker images
> docker image ls

// See which networks exist (usually created as part of docker-compose)
> docker network ls

// See which volumes exist
> docker volume ls

Removing Images and Containers

// List the images and then remove one using the image id
> docker rmi <image_id>

// List the containers and remove one using the container id
> docker rm <container_id>

// Remove a volume
> docker volume rm <volume_id>

// Remove a network
> docker network rm <network_id>

Starting and stopping

// Start a particular image and routing 1234 on localhost to 5678 on the docker image.  For a web application you'll need to expose the application server port such as 8080 eg -p 8080:8080
// After running this it'll show up on a docker ps as a container running this image
> docker run -p 1234:5678 <image_id>

// Start an image in 'detached' mode to keep the output quiet
> docker run -d -p 1234:5678 <image_id>

// View the logs of the docker container running a particular image
> docker logs <container_id>

// Stop a particular container
> docker stop <container_id>

// Attach a shell to a running docker container
> docker exec -it <container_id> "/bin/bash"

// Start with an environment variable
> docker run -d -e MY_ENVIRONMENT_VAR=bob <image_id>

Other useful commands

// See what resources are currently being used
> docker stats

// Grab the logs from a docker machine
> dockers logs <container_id> > output.log

// Copy a file from a docker image to the local machine
> docker cp <container_id>:<container file path> <local path>
> docker cp ab34d4532e78:/tmp/log.txt ./

docker-machine

// Useful where the host machine doesn't support natively such as anything pre windows 10

// Get the ip of the docker-machine, usually 192.168.99.100
> docker-machine ip

Friday 7 April 2017

Swagger UI ReST Documentation

Where SOAP gives a clear contract between the client and service, ReST services do not.  This means that the documentation is even more important to allow correct use of the service for the client.  Swagger allows the ReST endpoints to be documented as annotations within the code so that it is easier to write and maintain.

Maven Dependencies

Add the two dependencies below to use swagger and enable the swagger ui.

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.6.1</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.6.1</version>
    </dependency>


Spring Integration

With Spring annotation driven configuration this process is easy.  Create a class and annotate it with @Configuration so that spring uses it.  Additionally use @EnableSwagger2 to make sure that swagger is enabled.


@Configuration
@EnableSwagger2
public class SwaggerConfiguration
{
    /**
     * Add to the swagger documentation
     *
     * @return The {@link Docket} class with api information and config
     */
    @Bean
    public Docket getApiDocumentation()
    {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Project ReST Service")
                .apiInfo(new ApiInfoBuilder()
                        .title("My Service")
                        .description("My service which does lots of interesting things.")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}


With spring boot the situation isn't really any different to that above accept that the @EnableSwagger2 can be put on the same class as a the @SpringBootApplication annotation or left exactly as it is above.

Swagger Annotations

In addition to the annotation to enable swagger (@EnableSwagger2) the other main annotations to use are,

@Api - this can be used on a controller to describe the overall behaviour
@ApiOperation - put this on the methods in the controller to describe what they do
@ApiParam - used to describe the particular parameter that is passed to a controller method

A full list of annotations can be found here https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X