Category Archives: How To

Docker Tutorial – Getting started with Docker

This Docker Tutorial should help you get started with Docker.

  1. How to get a running Docker Machine on your computer
  2. How to create and manage Docker Images
  3. How to create and manage Docker containers
  4. How to delete Docker images and containers
  5. How to login to Docker Hub
  6. How to publish images to Docker Hub

You’ll learn how to start a Docker Machine on your PC, how to create images, how to create containers, and to cleanup your Docker Machine, login to Docker Hub, tag and publish images.

1. How to get a running Docker Machine on your computer

First thing you need to do before starting to manage images and containers is to have a Docker Machine up and running. For this tutorial I’m using Virtual Box for running the Docker Machine.

The next command creates a Docker Machine named dev. The command will check and download the required dependencies, create the VM, create a SSH key, start the VM and assign an IP and generate certificates.

docker-machine create --driver virtualbox dev

Running the above command is only needed the first time you create a Docker Machine. When you just need to start it you must run:

docker-machine start dev

After you have the Docker Machine running, you’ll be able to see the PORT and IP by running the next command. The printed result also contains a short command that you must run in order to set Docker Machine configuration in your environment.

docker-machine env dev

You must now set the environment with the Docker Machine configuration for the current terminal session by running:

eval $(docker-machine env dev)

That’s all for the first step. Starting a Docker Machine is quite easy.

In case you’re getting an IP allocation error, check out this article. It might help.

2. How to create and manage Docker Images

Now that we have the machine up and running we can list all the available images with:

docker images

In order to create a new image we must have a Dockerfile. I won’t get into how to create Dockerfile in this article but I’ll continue the tutorial using a base Nginx Dockerfile. Place this content in a file named Dockerfile

FROM nginx:latest
RUN nginx -v
EXPOSE 80
CMD ["bash", "-c", "nginx -g 'daemon off;'"]

Now you have a base Dockerfile and you can create an image from it by running:

docker build -t the_tag .

This command also requires that you have the Dockerfile in cwd. The dot from the end specifies that you are using a Dockerfile from the local directory. You can also build using a Dockerfile that’s not in the cwd by specifying the path to the Dockerfile:

docker build -f Dockerfile -t the_tag .

For both of the above commands you’ll see the following steps being executed:

Sending build context to Docker daemon 338.1MB
Step 1/4 : FROM nginx:latest
 ---> f68d6e55e065
Step 2/4 : RUN nginx -v
 ---> Using cache
 ---> 46c77d837d51
Step 3/4 : EXPOSE 80
 ---> Using cache
 ---> b31d714e67f1
Step 4/4 : CMD ["bash", "-c", "nginx -g 'daemon off;'"]
 ---> Using cache
 ---> c3f3bfb92c45
Successfully built c3f3bfb92c45
Successfully tagged the_tag:latest

If something goes wrong in any step the build will fail and the error will be printed. If you now run docker images again you’ll see:

REPOSITORY       TAG           IMAGE ID          CREATED             SIZE
the_tag          latest        c3f3bfb92c45      7 minutes ago       109MB

3. How to create and manage Docker containers

We now have a Docker image created and we’re ready to create and manage containers. You can list all available containers by running:

docker ps

Create a new container using the image we built by running:

docker run -d --name docker-nginx -p 80:80 the_tag

-d flag causes the container to run in detached mode
–name allows you to easily identify the container by setting a label
-p allows you to set publish the HOST:CONTAINER ports.

If you now run docker ps you’ll see something like this:

CONTAINER ID    IMAGE        COMMAND     CREATED          STATUS          PORTS                NAMES
c2e1bdcf12a0    image_tag    "bash -c"   3 seconds ago    Up 2 seconds    0.0.0.0:80->80/tcp   docker-nginx

You may now stop and delete this container by running:

docker stop c2e1bdcf12a0
docker rm c2e1bdcf12a0

4. How to delete Docker images and containers

In some articles I previously wrote I described how to keep your Docker Machine clean and how to delete certain images and containers or do a full cleanup.

Check out this article if you’re on OSX/Linux.

Check out this article if you’re using Windows.

5. How to login to Docker Hub

If you plan to publish your images to Docker Hub you’ll probably need to login.

docker login --username username@example.com --password THE_PASSWORD docker-hub.example.com:PORT

Be careful to specify the PORT. If you don’t, the authentication will work but publishing images will not find a token for the host.

6. How to publish images to Docker Hub

You’re now have an image and are authenticated to your Docker Hub. You can publish the image and make it available for others to use as well.

docker images # prints the hash
docker tag HASH docker-hub.example.com:443/<IMAGE_REPOSITORY_NAME>:0.0.1
docker push docker-hub.example.com:443/<IMAGE_REPOSITORY_NAME>

That’s it. The image is now on the hub.

How to clear Docker Machine on Linux

A few intensive hours building Docker containers quickly used up all the allocated space.

Deleting Docker images can be done using -f to force deletion of images that are used in other containers that remain.

docker images docker rmi <IMAGE_ID> -f 

Deleting Docker containers:

docker ps docker rm <CONTAINER_ID> 

Easy right?

What if you got tens of images? Still easy.

There are multiple ways of deleting Docker images depending on how they’re used.

The dangling images are not tagged and not used by any container. You can remove these images using (-f flag confirms the operation):

docker image prune -f

If you instead want to remove all images that are not referred in any container:

docker image prune -a

Cleaning containers is an easy task. You can clear only containers that are not running. The following command will stop all running containers:

docker container stop $(docker container ls -aq)

Now that we don’t have any running containers we can completely remove them using:

docker container rm $(docker container ls -aq)

Check this post and learn how to quickly delete Docker containers and images if you’re running on Windows.

How to generate X-WSSE Token using Java

Learn how to generate X-WSSE Token and how to authorize requests using X-WSSE header authentication.

If you’re not familiar with X-WSSE Token Authentication and why you should use it, go ahead and read this article that contains the basics of this type of authentication.

In this article I’ll describe how to generate a X-WSSE Token using Java.

import java.io.UnsupportedEncodingException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.Random;
import java.util.TimeZone;
import javax.xml.bind.DatatypeConverter;
 
public class xwsse {
 
    final protected static char[] hexArray = "0123456789abcdef".toCharArray();
 
    public static void main(String[] args) {
        String xwsse = getWsseHeader("CLIENT_ID", "CLIENT_SECRET");
        System.out.println(xwsse);
    }
 
    private static String getWsseHeader(String username, String secret) {
        String nonce = getNonce();
        String created = getUTCTimestamp();
        String digest = getPasswordDigest(nonce, created, secret);
 
        return String.format("UsernameToken Username=\"%s\", PasswordDigest=\"%s\", " + "Nonce=\"%s\", Created=\"%s\"", username, digest, nonce, created);
    }
 
    private static String getUTCTimestamp() {
        SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ");
        sdf.setTimeZone(TimeZone.getTimeZone("UTC"));
        return sdf.format(new Date());
    }
 
    private static String getNonce() {
        byte[] nonceBytes = new byte[16];
        new Random().nextBytes(nonceBytes);
        return bytesToHex(nonceBytes);
    }
 
    private static String getPasswordDigest(String nonce, String created, String secret) {
        String digest = "";
        try {
            MessageDigest messageDigest = MessageDigest.getInstance("SHA-256");
            messageDigest.reset();
            String hashedString = String.format("%s%s%s", nonce, created, secret);
            messageDigest.update(hashedString.getBytes("UTF-8"));
            String sha256Sum = bytesToHex(messageDigest.digest());
            digest = DatatypeConverter.printBase64Binary(sha256Sum.getBytes("UTF-8"));
        } catch(NoSuchAlgorithmException ex) {
            System.out.println("No SHA-256 algorithm found");
        } catch(UnsupportedEncodingException ex) {
            System.out.println("Unable to use UTF-8 encoding");
        }
        return digest;
    }
 
    private static String bytesToHex(byte[] bytes) {
        char[] hexChars = new char[bytes.length*2];
        for(int j=0; j<bytes.length; j++) {
            int v = bytes[j] & 0xFF;
            hexChars[j*2] = hexArray[v >>> 4];
            hexChars[j*2+1] = hexArray[v & 0x0F];
        }
        return new String(hexChars);
    }
 
}

That’s it. Check my other X-WSSE Articles and learn how to generate the token using other programming languages.

How to generate X-WSSE Token using Golang

Learn how to generate X-WSSE Token and how to authorize requests using X-WSSE header authentication.

If you’re not familiar with X-WSSE Token Authentication and why you should use it, go ahead and read this article that contains the basics of this type of authentication.

In this article I’ll describe how to generate a X-WSSE Token using Golang.

package main
 
import(
    "crypto/sha256"
    "crypto/md5"
    "encoding/base64"
    "encoding/hex"
    "fmt"
    "math/rand"
    "time"
    "strconv"
)
 
func getWsseHeader(username string, secret string) string {
    created := time.Now().Format(time.RFC3339)
    m := md5.New()
    m.Write([]byte(strconv.FormatFloat(rand.Float64(), 'f', 6, 64)))
    nonce := hex.EncodeToString(m.Sum(nil));
    text := (nonce + created + secret)
    h := sha256.New()
    h.Write([]byte(text))
    sha256 := hex.EncodeToString(h.Sum(nil))
    passwordDigest := base64.StdEncoding.EncodeToString([]byte(sha256))
    return string("UsernameToken Username=\"" + username + "\", PasswordDigest=\"" + passwordDigest + "\", Nonce=\"" + nonce + "\", Created=\"" + created + "\"")
}
 
func main() {
    rand.Seed(time.Now().UnixNano())
    var xwsse = getWsseHeader("CLIENT_ID", "CLIENT_SECRET");
    fmt.Println(xwsse);
}

That’s it. Check my other X-WSSE Articles and learn how to generate the token using other programming languages.

How to generate X-WSSE Token using Ruby

Learn how to generate X-WSSE Token and how to authorize requests using X-WSSE header authentication.

If you’re not familiar with X-WSSE Token Authentication and why you should use it, go ahead and read this article that contains the basics of this type of authentication.

In this article I’ll describe how to generate a X-WSSE Token using Ruby.

require 'time'
require 'base64'
require 'digest'
 
def getWsseHeader(username, secret)
    nonce = Digest::MD5.hexdigest(rand.to_s)
    created=Time.now.utc.iso8601
    passwordDigest=Base64.strict_encode64(Digest::SHA256.hexdigest(nonce+created+secret)).strip
    header='UsernameToken '+"Username=\"#{username}\", "+"PasswordDigest=\"#{passwordDigest}\", "+"Nonce=\"#{nonce}\", "+"Created=\"#{created}\""
    return header
end
 
xwsse = getWsseHeader("CLIENT_ID", "CLIENT_SECRET");
print xwsse

That’s it. Check my other X-WSSE Articles and learn how to generate the token using other programming languages.

How to generate X-WSSE Token using Python

Learn how to generate X-WSSE Token and how to authorize requests using X-WSSE header authentication.

If you’re not familiar with X-WSSE Token Authentication and why you should use it, go ahead and read this article that contains the basics of this type of authentication.

In this article I’ll describe how to generate a X-WSSE Token using Python.

import datetime
import hashlib
import random
import base64
 
def getWsseHeader(username, secret):
    created = datetime.datetime.utcnow().isoformat();
    nonce = hashlib.md5(str(random.getrandbits(128)).encode('utf-8')).hexdigest()
    digest = "".join((nonce, created, secret))
    digest = hashlib.sha256(digest.encode('utf-8')).hexdigest()
    digest = base64.b64encode(digest.encode("utf-8")).decode('utf-8')
    return ('UsernameToken Username="{username}", '
            'PasswordDigest="{digest}", Nonce="{nonce}", '
            'Created="{created}"').format(username=username,
                                        digest=digest,
                                        nonce=nonce,
                                        created=created)
 
xwsse = getWsseHeader("CLIENT_ID", "CLIENT_SECRET");
print(xwsse)

That’s it. Check my other X-WSSE Articles and learn how to generate the token using other programming languages.

How to generate X-WSSE Token using PHP

Learn how to generate X-WSSE Token and how to authorize requests using X-WSSE header authentication.

If you’re not familiar with X-WSSE Token Authentication and why you should use it, go ahead and read this article that contains the basics of this type of authentication.

In this article I’ll describe how to generate a X-WSSE Token using PHP.

function getWsseHeader($username, $secret) {
 
    $nonce = md5(rand());
    $created  = date('c');
    $digest   = base64_encode(hash('sha256', $nonce . $created . $secret, false));
 
    $wsseHeader = sprintf(
        'UsernameToken Username="%s", PasswordDigest="%s", Nonce="%s", Created="%s"',
        $username,
        $digest,
        $nonce,
        $created
    );
 
    return $wsseHeader;
 
}
 
$xwsse = getWsseHeader("CLIENT_ID", "CLIENT_SECRET");
echo $xwsse;

That’s it. Check my other X-WSSE Articles and learn how to generate the token using other programming languages.

How to generate X-WSSE Token using NodeJS

Learn how to generate X-WSSE Token and how to authorize requests using X-WSSE header authentication.

If you’re not familiar with X-WSSE Token Authentication and why you should use it, go ahead and read this article that contains the basics of this type of authentication.

In this article I’ll describe how to generate a X-WSSE Token using NodeJS.

const crypto = require('crypto');
 
function getWsseHeader(username, secret) {
 
    const nonce = crypto.randomBytes(16).toString('hex');
    const created = new Date().toISOString();
    const hash = crypto.createHash('sha256').update(nonce + created + secret, 'utf-8').digest('hex');
    const digest = Buffer.from(hash).toString('base64');
     
    return `UsernameToken Username="${username}", PasswordDigest="${digest}", Nonce="${nonce}", Created="${created}"`;
 
}
 
const xwsse = getWsseHeader('CLIENT_ID', 'CLIENT_SECRET');
console.log(xwsse);

That’s it. Check my other X-WSSE Articles and learn how to generate the token using other programming languages.

What is X-WSSE Token Authentication and how does it work

Learn the basics of X-WSSE Token Authentication and how to authorize requests using X-WSSE header authentication.

X-WSSE Token Authentication can be used to authenticate backend-to-backend integrations using client_id and client_secret properties. The main benefit of this type of authentication is that the client_secret value never leaves the backend of the integrating client, and that each token, even if lost, is only valid for 5 minutes.

The X-WSSE Token is a string with the following format, usually a single HTTP header line which is broke down into multiple lines for easier readability:

X-WSSE: UsernameToken
Username="USERNAME",PasswordDigest="ASDFbasEHAPRo395MBANgoaiERJGJHSOSLGUsernameToken Username="68037425-fa69-49da-8715-fa393dc55471", PasswordDigest="OWRkZGRjMjk3ZjhiOGFhZmMzNGIzMjAwMWIyNmNjY2JkMTM2M2E5OGFlMGM2ZDI3OGIzZmQ5ZDAwY2RiODMzZg==", Nonce="ee2e8c783398782fd63af15141a1cb62", Created="2019-03-14T16:17:24.211Z"==",Nonce="b35f7341829e35d89851497a82894f",Created="2019-03-20T12:10:20Z"

I’ll briefly describe each component of the X-WSSE Token:

X-WSSE

The name of the HTTP header that must be present in order to authorize the request.

UsernameToken

Value represents the authentication method of the use X-WSSE Token. Currently X-WSSE only supports UsernameToken type of authentication.

Username

The client_id property that you should generate for each integration of X-WSSE Token.

PasswordDigest

Field specifies the hashed token that will authorize the reuqest. For each request a new hash must be generated. Check my other posts and learn how to generate the X-WSSE Token using different server-side programming languages

Computing the Password Digest

Computing the password digest involves 5 simple steps:

  1. Generate random 16 byte Nonce formatted as 32 hexadecimal characters.
  2. Retrieve the current timestamp in ISO8601 format.
  3. The properties nonce, timestamp, secret should be concatenated in this order.
  4. Compute the SHA256 hash value of the string from #3 and convert it to hexadecimal format
  5. Encode the value from #5 in BASE64 and obtain the PasswordDigest

Nonce

Random value with the purpose to make your request unique so it cannot be replicated by unknown parties. This string is always 16 bytes long and should be represented as a 32 characters long hexadecimal value.

Created

This field contains the current UTC, GMT, ZULU timestamp (YYYY-MM-DDTHH:MM:SS) according to the ISO8601 format. e.g. 2018-05-20T12:51:45+01:00

Now you know what is a X-WSSE Token and the purpose of each of its components so let’s go to the Implementation. Check my other X-WSSE articles and learn more.


LibGDX send HTTP request

Check out Lines Galaxy Android game to view the results in action.

Most common ways to communicate between your mobile app to your backend servers are HTTP Requests and Websockets.

In this article I’ll describe how you can create, send and process a HTTP Request to backend servers from your LibGDX application. In this example I will demonstrate how to send a basic POST request.

First step is to prepare the request payload:

Map<String, String> parameters = new HashMap<String, String>();

parameters.put("token", "<TOKEN>");
parameters.put("some_value", 1234);

final Json json = new Json();
json.setTypeName(null);
json.setOutputType(JsonWriter.OutputType.json);
json.setUsePrototypes(false);
String requestJson = json.toJson(parameters);

Second step is to create an instance of the HTTP Agent:

Net.HttpRequest request = new Net.HttpRequest(Net.HttpMethods.POST);
request.setUrl("http://example.com/");
request.setContent(requestJson);

And finally, after we set the desired server url and prepared the payload, we can send the request and attach the callback listeners

Gdx.net.sendHttpRequest(request, new Net.HttpResponseListener() {
    public void handleHttpResponse(Net.HttpResponse httpResponse) {
        HttpStatus status = httpResponse.getStatus();
        if(status.getStatusCode() == 200) {
            String responseJson = httpResponse.getResultAsString();
        } else {
            // error :(
        }
    }
    public void failed(Throwable t) {
        String error = t.getMessage();
    }
    public void cancelled() {
        // request aborded
    }
});

And that’s it. ou can just copy the above code and send LibGDX HTTP Request. You can dig further by reading the official docs: HttpResponseListener, HttpRequest.

Check out Lines Galaxy Android game to view the results in action.