First steps with Docker

In this guide, you'll go through the initial steps of installing Docker Desktop. By the end, you'll have Docker set up and ready for Memgraph Docker images.

Installing Docker Desktop

Find out how to install Docker Desktop on Windows and MacOS.

Windows

Check the prerequisites then follow the installation process.

Prerequisites

Ensure your system meets the following prerequisites.

Supported Windows versions

Use one of the following Windows operating systems:

• Windows 11 64-bit: Home, Pro, Enterprise or Education version 21H2 or higher.
• Windows 10 64-bit: Home, Pro, Enterprise or Education version 21H2 (build 19044) or higher.

WSL

Ensure you have the WSL 2 feature activated on Windows (opens in a new tab)

Hardware requirements

Ensure your machine meets the following criteria:

• 64-bit processor with Second Level Address Translation (SLAT).
• At least 4GB system RAM.
• BIOS-level hardware virtualization must be enabled.

Further details can be found in the official Docker documentation (opens in a new tab).

Installation process

MacOS

Check the prerequisites then follow the installation process.

Prerequisites

• Docker supports Docker Desktop on the most recent versions of macOS. That is, the current release of macOS and the previous two releases. As new major versions of macOS are made generally available, Docker stops supporting the oldest version and supports the newest version of macOS (in addition to the previous two releases).
• At least 4 GB of RAM.

Installation process

Verifying Docker Installation

To ensure that Docker has been successfully installed and is running on your system, follow the steps below:

docker --version

Docker version 24.0.6, build ed223bc

docker info

docker system info

Troubleshooting

If you encounter any errors or if Docker does not seem to be running:

• Ensure that the Docker Desktop application (for Mac and Windows) is running.
• On Linux, you might need to start the Docker service manually using a command like sudo service docker start or sudo systemctl start docker, depending on your Linux distribution.

Managing Docker Service on Windows using PowerShell

On Windows, Docker typically runs as a service via Docker Desktop. While Docker Desktop provides a user-friendly interface for managing Docker, there are instances where you might want to control the Docker service directly from the command line using PowerShell.

To open PowerShell as an administrator, right-click the Start button and select "Terminal (Admin)" or search for "PowerShell" in the start menu, right-click "Windows PowerShell", and select "Run as administrator".

Check the Status of the Docker Service

To verify the status of the Docker service, whether it's running or stopped, use:

Get-Service com.docker.service

This command will display the status of the Docker service.

Start the Docker Service

If Docker isn't running and you want to start it, use the following command:

net start com.docker.service

You should receive a message indicating that the Docker service has started successfully.

Stop the Docker Service

To stop the Docker service, use the following command:

net stop com.docker.service

You should receive a message indicating that the Docker service has stopped.

Work with Docker

If you are new to Docker, this guide will help you get a grasp of Docker and make it easier to accomplish tasks within Memgraph. After installing Docker, all commands are run from the command-line tool of your preference.

Download the Memgraph Docker image

You can think about downloading Memgraph Docker images as obtaining a blueprint for Memgraph, complete with all its core features. This image is your starting point. From it, you can launch a container, which acts as a live instance of Memgraph. All your interactions, queries, and transactions with Memgraph occur within this container. This ensures a consistent and isolated setting for all your database tasks. From a single image, you can spawn multiple containers. Each container functions as a distinct Memgraph instance.

Images are downloaded using the docker pull command followed by the name of the Docker image. All Memgraph Docker images are available at Memgraph's Docker Hub (opens in a new tab). There you will find exact Docker image tags you can download and use to install Memgraph with.

Run a Memgraph Docker image

All images are started using the docker run command followed by various flags, environment variables and configuration options.

The most common flags used while running Memgraph images are:

• publish ports: -p 3000:3000
• container name: --name memgraph
• set up configuration using configuration flags using the memgraph or memgraph-mage image

A docker run command can look like this:

docker run -p 7687:7687 [-p host_port:container_port] [--name container_name] [configuration] memgraph/image_name

Publish ports

Ports are published in order to allow services outside the container to be able to connect to the container. When publishing ports, you need to define two ports separated by a colon. The left side port stands for the host port and the right side port is the container port.

The most common ports published while running Memgraph are:

• -p 7687:7687 - connection to the database instance (the Bolt protocol uses this port by default)
• -p 7444:7444 - connection to fetch log files from Memgraph Lab (only in version 2.0 and newer)

For example, if you are running two instances using the memgraph-mage image and you would run the first instance with:

docker run -p 7444:7444 -p 7687:7687 memgraph/memgraph-mage

Because ports 7444 and 7687are now taken, you need to change the left side ports (host ports):

docker run -p 7445:7444 -p 7688:7687 memgraph/memgraph-mage

Container name

Upon creation, each container gets an ID. You can find out the container ID by running the docker ps command, but you can also name the container using the --name flag. Defining a name can be a handy way to add meaning to a container. If you specify a name, you can use it when referencing the container within a Docker network.

Set up the configuration

If you want a certain configuration setting to be applied during a single run, you need to pass the configuration option within the docker run command instead of changing the configuration file.

When you are working with memgraph or memgraph-mage images, you should pass configuration options as arguments.

For example, if you want to limit memory usage for the whole instance to 50 MiB and set the log level to TRACE, pass the configuration argument like this:

docker run -p 7687:7687 memgraph/memgraph --memory-limit=50 --log-level=TRACE

Specify volumes

Specifying a volume syncs the specified directory inside the Docker container as a local directory. The -v flag is followed by the name of the local directory separated from the path of the volume in the container by a semicolon:

-v volume_name:volume_path

Named volumes handle data permissions so there shouldn't be any issue with data permissions.

Useful volumes you can specify while running Memgraph are:

• -v mg_lib:/var/lib/memgraph - directory containing data, enables data persistency
• -v mg_log:/var/log/memgraph - directory containing log files
• -v mg_etc:/etc/memgraph - directory containing the configuration file

The exact location of the local directories depends on your specific setup.

The configuration file can usually be found at /var/lib/docker/volumes/mg_etc/_data/memgraph.conf but you can also copy the file from the Docker container, modify it and copy it back into the container.

The logs will be saved to the mg_log volume, and the directories can usually be found in /var/lib/docker/volumes/, but you can also view them in the Memgraph Lab 2.0 (or newer) by publishing the port 7444.

Specify bind mounts

Bind mounts are local directories or files that can be modified by other processes other than Docker. Any changes made to these directories or files locally will be reflected inside the Docker container and vice-versa. Also, a bind mount will overwrite the content of the Docker container.

For example, if I have a Data directory on my C: disk, and I want to access it from inside the container at /usr/lib/memgraph/data, I would run Docker with the following -v flag.

docker run -p 7687:7687 -p 7444:7444 -v "C:/data":/usr/lib/memgraph/data memgraph/memgraph-mage

You can use bind mounts to transfer durability files such as snapshot or WAL files inside the container to restore data, or CSV files you will use to import data with CSV LOAD clause.

Bind mounts do not handle data permissions which could cause issues with permissions.

Stop container

Database instances are stopped by stopping the Docker container with the command docker stop. To stop a container you need to know the container's ID or name.

You can list all the containers you want to stop in one docker stop command:

docker stop CONTAINER1_ID CONTAINER2_ID CONTAINER3_NAME

Start container

If you want to start a stopped container, list them using the following command:

docker ps -a

Then start the container with:

docker start <CONTAINER_ID> 

or

docker start <CONTAINER_NAME> 

Delete container

To remove a Docker container, you first need to ensure that it's stopped. Once it's stopped, you can use the docker rm command. Like stopping a container, you'll need to know the container's ID or name to delete it.

Here's how you can delete a single container:

docker rm <CONTAINER_ID>

or

docker rm <CONTAINER_NAME>

If you want to remove multiple containers in one go, simply list them all in the docker rm command:

docker rm CONTAINER1_ID CONTAINER2_ID CONTAINER3_NAME

Retrieve a Docker container ID

Run the following command:

docker ps

You should get an output similar to this:

CONTAINER ID   IMAGE                    COMMAND                  CREATED         STATUS         PORTS                                            NAMES
d44f049fef87   memgraph/memgraph-mage   "/usr/lib/memgraph/m…"   8 seconds ago   Up 6 seconds   0.0.0.0:7444->7444/tcp, 0.0.0.0:7687->7687/tcp   musing_pasteur

You can shorten this ID to 4 letters if the ID remains unique, for example, 45fa.

Retrieve a Docker container IP address

To retrieve the Docker container IP address, first, you need to retrieve its ID or use its name.

Then run the following command if the container ID is 9397623cd87e.

docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' 9397623cd87e

Browse files inside a Docker container

To browse files inside a Docker container, first, you need to retrieve its ID or use its name.

Then run the following command if the container ID is 9397623cd87e:

docker exec -it 9397623cd87e bash

To navigate through the container, use the following commands:

• ls - list all the directories and files
• cd <directory> - enter a directory
• cd .. - leave the directory
• cat <file> - list the content of a file

You don't have to write file and directory names in full, once you write enough letters to have a unique string, press the <TAB> key.

Copy files from and to a Docker container

To copy files from and to the Docker container, first, you need to retrieve its ID or use its name.

First, place yourself in the local directory where you want to copy the file.

To copy the file from the container to your current directory use the following command:

docker cp <CONTAINER ID>:<path_in_container> <local_file_name>

Be sure to replace the <CONTAINER ID> parameter.

The example below will copy the configuration file to the user's Desktop:

C:\Users\Vlasta\Desktop>docker cp bb3de2634afe:/etc/memgraph/memgraph.conf memgraph.conf

To copy the file from your current directory to the container use the following command:

docker cp  <local_file_name> <CONTAINER ID>:<path_in_container>

Be sure to replace the <CONTAINER ID> parameter.

The example below will replace the configuration file with the one from the user's Desktop:

C:\Users\Vlasta\Desktop>docker cp memgraph.conf bb3de2634afe:/etc/memgraph/memgraph.conf

Difference Between docker run and docker start

The commands docker run and docker start may seem similar, but they are quite different. Each command serves a specific purpose:

• docker run: This command is used for creating and launching a new container from a Docker image. When executing docker run, Docker first searches for the specified image in the local repository. If the image is not found locally, Docker fetches it from Docker Hub. Once the image is obtained, Docker creates a new container from this image and initiates it. This command is used for setting up a new container instance with various configurations.

• docker start: This command is used for restarting an existing, previously stopped container. Containers may be stopped using the docker stop command or may exit naturally. When a container is stopped, its state is preserved, allowing docker start to reactivate the container with all its prior settings intact. This command is used for reactivating a container without repeating the initial setup and initialization process required by docker run. It's important to note that docker start is applicable only to containers that have already been created and stopped; it cannot be used to create a new container.

Containers and data persistence

When you're working with Docker, it's essential to understand how data is handled in containers.

Your data is safe: Even if you stop a container using the docker stop command or if it crashes unexpectedly, the data and changes inside that container are retained. So, when you restart the stopped container, you'll find everything just as you left it.

However, there are a few things to keep in mind:

• Deleting a container: If you deliberately delete a container using commands like docker rm, the changes and data within that container will be lost unless you've saved them in Docker volumes or bind mounts.

• Using volumes: To ensure long-term data safety and for scenarios where you might delete containers but want to retain their data, Docker provides a feature called volumes. Volumes allow you to store data outside the container, ensuring it remains safe and accessible even if the container is removed.

In short, while working with containers, always remember: stopping isn't deleting. Your data stays intact when a container is merely stopped. If you're planning to remove containers but wish to keep the data, ensure you've set up Docker volumes prior to running the container.