First steps with Docker

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

Download Docker Desktop installer

Navigate to the Docker Desktop web page (opens in a new tab) and select the installer suitable for Windows.

Execute the installer

Locate the downloaded .exe file and double-click to begin the installation process.

Configure installation settings

During installation:

  • Opt for WSL 2 based installation instead of Hyper-V.
  • Choose to add a desktop shortcut for easier access.

Installer Options

Launch Docker Desktop

After installation, you can open Docker Desktop by clicking on the newly created icon on your desktop or by searching for it in the Start menu.

Accept Docker’s Terms and Conditions

Prior to using Docker Desktop, go through the terms and conditions. If you agree, proceed by accepting them.

Terms and Conditions

Determine your usage scenario

Docker will prompt questions about your intended usage. Answer accordingly to tailor Docker's settings and recommendations to your needs.

Post-installation Steps

After successful installation, you'll be presented with Docker Desktop’s user interface.

Docker Desktop UI

Navigate to Docker's settings. Based on your specified usage scenario, verify if Docker is set to start on system boot and adjust this settings.

Docker Settings

If Docker Desktop is configured not to launch on system startup, you will have to start it manually every time you want to use it.

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

Download Docker Desktop installer

Navigate to the Docker Desktop web page (opens in a new tab) and select the installer suitable for MacOS and the chip you have.

Execute the installer

Locate the downloaded file, double click it and drag and drop the Docker application to the Applications folder to begin the installation process.

Launch Docker Desktop

After installation, you can open Docker Desktop by clicking on the newly created icon by searching for it in the Applications folder or Launchpad and agree to open it.

Accept Docker’s Terms and Conditions

Prior to using Docker Desktop, go through the terms and conditions. If you agree, proceed by accepting them.

Determine your usage scenario

From the installation window, select Use recommended settings (Requires password). This let's Docker Desktop automatically set the necessary configuration settings.

Post-installation Steps

After successful installation, you'll be presented with Docker Desktop’s user interface.

Navigate to Docker's settings. Based on your specified usage scenario, verify if Docker is set to start on system boot and adjust this settings.

Docker Settings

If Docker Desktop is configured not to launch on system startup, you will have to start it manually every time you want to use it.

Verifying Docker Installation

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

Open the Command Line or Terminal

  • Windows: Press Windows + R, type cmd, and hit Enter.
  • Mac: Press Command + Space, type terminal, and hit Enter.
  • Linux: Depending on the distribution, you can use shortcuts like Ctrl + Alt + T or access the terminal from the application menu.

Verify Docker Version

Run the following command:

docker --version

It should display the version of Docker installed on your machine. For example:

Docker version 24.0.6, build ed223bc

Check Docker Details

For more detailed information about the Docker installation, you can use:

docker info

This command provides a comprehensive overview of your Docker setup, including the number of containers running, paused, and stopped, as well as other system information.

Ensure Docker Daemon is Running

To check that the Docker daemon (background service) is running, execute:

docker system info

If Docker is running correctly, this command will return system-wide information. If not, you may receive an error indicating that Docker is not running.

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. We encourage you to use Memgraph Platform as it includes everything you might need while making the best of Memgraph. Besides the database, it also includes all the tools you might need to analyze your data, such as command-line interface mgconsole, web interface Memgraph Lab and a complete set of algorithms within a MAGE library.

To download the latest Memgraph Platform image, run:

docker pull memgraph/memgraph-platform

All Memgraph Docker images are availble 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.

Architecture of Docker container running Memgraph

The picture below shows the architecture of the Memgraph Docker ecosystem.

Memgraph offers various Docker images, each consisting of different components

  • memgraph-platform includes Memgraph database, mgconsole, MAGE and Memgraph Lab
  • memgraph-mage includes Memgraph database, mgconsole and MAGE
  • memgraph includes Memgraph database and mgconsole

If you're new to Memgraph or you're in a developing stage, we recommend using the memgraph-platform image as it includes all the tools you might need to analyze your data. Once you're ready to go to production you can choose to use the memgraph-mage Docker image that includes the database and the graph library, or run the database only, using the memgraph image.

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 environment variables in the case of the memgraph-platform image, or 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 3000:3000 - connection to the Memgraph Lab application when running Memgraph Platform
  • -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-platform image and you want to connect to both instances using the Memgraph Lab in-browser application, you would run the first instance with:

docker run -p 7444:7444 -p 3000:3000 memgraph/memgraph-platform

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

docker run -p 7445:7444 -p 3001:3000 memgraph/memgraph-platform

To connect to the first instance, you should open Memgraph Lab in your browser at localhost:3000, but the second instance is reachable at localhost:3001.

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.

If you are working with the memgraph-platform image, you should pass configuration options with environment variables.

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 like this:

docker run -p 7687:7687 -p 3000:3000 -p 7444:7444 -e MEMGRAPH="--memory-limit=50 --log-level=TRACE" memgraph/memgraph-platform

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 -p 3000:3000  -v "C:/data":/usr/lib/memgraph/data memgraph/memgraph-platform

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

Stopping the container isn't the same thing as deleting it.

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

⚠️

Deleting a container will permanently remove it from your system. Ensure you have backed up any important data before proceeding.

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
45fa0f86f826   memgraph/memgraph-platform   "/bin/sh -c '/usr/bi…"   21 hours ago   Up 21 hours   0.0.0.0:3000->3000/tcp, 0.0.0.0:7444->7444/tcp, 0.0.0.0:7687->7687/tcp   admiring_almeida

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.