Docker basics for Intercom

Although the goal of the Intercom Docker SDKs is to get you interacting with our API more quickly, it is a good idea to go over some Docker basics.

This will help you understand how we are using Docker at Intercom and, more importantly, what you are doing when downloading images and running them in a container. If you have already messed around with Docker and feel confident you know enough to get up and running with our Docker images then you can head straight to our Intercom Docker SDK page and get started.

If the only thing you take out of this whirlwind introduction to Docker is an understanding of what an image and a container is then you should have enough context to get started with the Intercom Docker SDKs. There are some other concepts that would help but they are the garnish to the main course that is images and containers.

Images

Images are the basic building block of the Docker ecosystem. There are the static, never changing entity from which everything else originates. In programming terms they are the class and then anything that is created from their template or blueprint is an instance.

We've created images for some of our SDKs which you can download. We have pushed them to Docker Hub which is the Docker equivalent of GitHub. From Docker Hub you can download and run the images we have created. There are a lot of words there so here's a nice visual version that may help explain Docker images better than words.

Containers

Containers are where it starts to get interesting. To continue our programming analogy, containers are the the running instances of an image. Remember, the image is the class and then the container is the instance of that class. You can also say that the image runs "in" a container.

When you want to use a Docker image you need to download it and run it (you can do both in one step but more of that later). When you run it a container is created from that image and the image is loaded into that container.

Depending on how you use the container you can either get it to execute an action or use it interactively or many other ways. For the Intercom Docker SDKs you can mostly use them interactively to run code to interact with our APIs. Again here are more pictures that show how images and containers interact.

Launching Intercom Docker SDK containers

Now that we know the difference between an image and a container, let's look at how we create and run a Docker container. All you have to do to use our Docker containers is to simply run them, which tells your Docker program to look for an image, download it from Docker Hub if it is not found locally and then create a container and load the image into it. Docker break down the run command in more detail in the link below:

docs.docker.com

Learn about images and containers

Example Intercom Docker command

Let's look at an example command we will use to start up one of the SDK containers:

docker run --env PAT="<ACCESS TOKEN>" -it --rm --name <YOUR CONTAINER NAME> intercom/sdk-images:<TAG>

docker run

Tells the Docker program to look for an image in order to create a container and load the image into that container. If it does not find the image locally then it will download one from Docker Hub if it exists.

--env

This parameter allows you to set an environment variable in the container. This is very convenient for us since it means we can use it to set things like your access token, which we can then access as an environment variable within any code we are running in the container. This saves us some setup steps once we are running in the container.

--it

This drops us into an interactive bash shell. In this shell you can run commands and program and generally interact with the API. Its the easiest way to use our Docker SDKs.

--rm

This parameter tells Docker to immediately remove the container when you have stopped using it. This is usually when you exit the container or stop the container. This is good but it can be dangerous – anything you save in your container then it will be lost after you exit it.

If you want to keep your container you should not use this option so you can restart or re-attach to a container you were already working on. You just need to remember to delete these containers when you are finished. Otherwise, you could keep creating new ones when you do a Docker run.

--name

This parameter assigns a name to your container. This is useful for letting you differentiate between your different containers afterwards.

Other useful commands

docker images

List all your Docker images. When you run an image, Docker will download it if it is not stored locally. If there are dependencies then you will also download other images. You should keep an eye on this list and delete the images when you no longer need them.

docker ps -a

List all the containers regardless of their state. Your containers can be in running or stopped state. Running ps without the '-a' parameter will return the list of running containers. As with images, you will want to keep an eye on your containers and delete them as you no longer need them.

Alternatively, as noted above, you can also launch your containers and specify that they are automatically deleted once you exit them.

docker start/stop/attach

Docker containers can exist in different states. You may want to do some work in a container over a period of time. In this case you can launch your container, do you work and then stop it.

You can start it and attach to your container when you want to pick up where you were at a later date. Remember to not use the '--rm' parameter when launching a container if you want to be able to stop and start containers.

docker rm

Delete the specified container from your machine.

docker rmi

Delete the specified image from your machine.