Docker Compose

If you define an application with Docker Compose, you can use that definition to run the application in CI, staging, or production environments. Here you can find docker-compose.yml files necessary to run memgraph-platform, memgraph-mage, and memgraph. You can also find Docker Compose configurations for Memgraph Platform versions up to 2.14.

Docker Compose for Memgraph Platform

The Docker Compose configuration for the Memgraph Platform is designed to facilitate a smooth and efficient setup process for developers by specifying the use of memgraph/memgraph-mage and memgraph/lab images. This setup ensures that all necessary services are properly configured to work together seamlessly, emphasizing ease of use and integration.

services:
  memgraph:
    image: memgraph/memgraph-mage:latest
    container_name: memgraph-mage
    ports:
      - "7687:7687"
      - "7444:7444"
    command: ["--log-level=TRACE"]
 
  lab:
    image: memgraph/lab:latest
    container_name: memgraph-lab
    ports:
      - "3000:3000"
    depends_on:
      - memgraph
    environment:
      - QUICK_CONNECT_MG_HOST=memgraph
      - QUICK_CONNECT_MG_PORT=7687

Key features

Memgraph MAGE: The core of the platform, the Memgraph database with included MAGE algorithms, is set up with ports 7687 for the Bolt protocol and 7444 for the optional HTTPS interface. The log level is set to TRACE to provide detailed output, which is invaluable for debugging and further development.
Memgraph Lab: A user-friendly visual interface that connects automatically to the Memgraph service using predefined environment variables. It is accessible through port 3000, offering an intuitive environment for query execution and data visualization.
Service Dependency: Configuration ensures that Memgraph Lab starts only after the Memgraph database service is fully operational, establishing a reliable service order and minimizing startup issues.

Configuration

This configuration is primarily optimized for development and testing environments. For production deployments, it's recommended to customize the configuration according to specific security and performance requirements.
In this Docker Compose file, the command directive is used to specify the configuration flags that should be set when the container starts. In this example, the specified command --log-level=TRACE sets the log level to TRACE. The --log-level=TRACE option in the Memgraph service enables detailed logging. This setting is adjustable to suit different phases of development and testing, providing flexibility in monitoring and troubleshooting.

💡

If you wish to set more than one configuration flag, use the following syntax:
command: ["--setting-name1=value1", "--setting-name2=value2"]

Docker Compose for Memgraph MAGE image

The Memgraph MAGE image contains:

Memgraph - the database that holds your data
MAGE - graph algorithms and modules library

services:
  memgraph-mage:
    image: "memgraph/memgraph-mage"
    volumes:
      - mg_lib:/var/lib/memgraph
      - mg_log:/var/log/memgraph
    ports:
      - "7687:7687"
      - "7444:7444"
    command: ["--log-level=TRACE"]
volumes:
  mg_lib:
  mg_log:
  mg_etc:

The port 7687 is used for communication with Memgraph via Bolt protocol, while the port 7444 is there so that you can see logs from Memgraph inside the Memgraph Lab application. We specified three useful volumes:

mg_lib - directory containing data that enables data persistency
mg_log - directory containing log files
mg_etc - directory containing the configuration file

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

We recommend using the command option to customize Memgraph's runtime flags instead of setting them through entrypoint. This approach enhances your flexibility and aligns with Docker best practices, allowing you to easily adjust your container's behavior without altering its foundational settings.

In the above example, you can see how to set --log-level to TRACE. Since the MAGE library is included in this image, you can use the available graph algorithms.

Docker Compose for Memgraph image

The Memgraph image contains the database that holds your data.

services:
  memgraph:
    image: "memgraph/memgraph"
    ports:
      - "7687:7687"
      - "7444:7444"
    volumes:
      - mg_lib:/var/lib/memgraph
      - mg_log:/var/log/memgraph
    command: ["--log-level=TRACE"]
volumes:
  mg_lib:
  mg_log:
  mg_etc:

mg_lib - directory containing data that enables data persistency
mg_log - directory containing log files
mg_etc - directory containing the configuration file

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

In the above example, you can see how to set --log-level to TRACE. Since this image doesn't have the MAGE library included, you won't be able to use graph algorithms.

Want to see applications built with Memgraph and Docker Compose? Check out Memgraph's Github (opens in a new tab) repositories.

Configuring user authentication in Docker Compose

When setting up Memgraph with Docker Compose, you can use environment variables MEMGRAPH_USER and MEMGRAPH_PASSWORD to create a new user if that username doesn't already exist.

💡

When working with MEMGRAPH_USER and MEMGRAPH_PASSWORD environmental variables, keep the following things in mind:

New User Creation: When MEMGRAPH_USER and MEMGRAPH_PASSWORD are set and the specified user does not exist, Memgraph creates this new user. However, these credentials must be manually entered each time when accessing Memgraph through Memgraph Lab.
Existing Users: If the username already exists and an incorrect password is provided via MEMGRAPH_PASSWORD, no changes will occur. The existing password remains unchanged, and you must use the original credentials to access Memgraph Lab.
Docker Compose Restarts: If Memgraph is restarted via Docker Compose without these environment variables being set, previously created users remain unaffected. You must manually enter the user credentials every time you access Memgraph Lab.

Below is an example of how to configure these environment variables in your docker-compose.yml file:

services:
  memgraph:
    image: memgraph/memgraph-mage:latest
    container_name: memgraph-mage
    ports:
      - "7687:7687"
      - "7444:7444"
    command: ["--log-level=TRACE"]
    environment:
      - MEMGRAPH_USER=testuser123
      - MEMGRAPH_PASSWORD=t123
 
  lab:
    image: memgraph/lab:latest
    container_name: memgraph-lab
    ports:
      - "3000:3000"
    depends_on:
      - memgraph
    environment:
      - QUICK_CONNECT_MG_HOST=memgraph
      - QUICK_CONNECT_MG_PORT=7687

⚠️

When specifying environment variables in Docker Compose, avoid spaces around the equals sign (=). Including spaces can cause the variables to be misinterpreted or ignored by Docker, leading to unexpected behavior.

Correct format:

environment:
  - MEMGRAPH_USER=testuser123
  - MEMGRAPH_PASSWORD=t123

Incorrect format (will not work):

environment:
  - MEMGRAPH_USER = testuser123
  - MEMGRAPH_PASSWORD = t123

Issues when running Memgraph and Lab within the same Docker compose

When running both Memgraph and Lab services within the same Docker Compose file, the QUICK_CONNECT_MG_HOST environment variable should be set to the name of the Memgraph database service as defined in your Docker Compose file. This allows the Lab service to correctly resolve and connect to the Memgraph service. Here's an example snippet for your docker-compose.yml:

services:
  memgraph:
    image: memgraph/memgraph
    ports:
      - "7687:7687"
  lab:
    image: memgraph/lab
    ports:
      - "3000:3000"
    environment:
      QUICK_CONNECT_MG_HOST: memgraph

In this configuration, QUICK_CONNECT_MG_HOST is set to memgraph, which is the service name of the Memgraph database within the Docker Compose network, enabling the direct communication between the Lab and Memgraph services. You can also use the QUICK_CONNECT_MG_PORT environment variable to specify the quick connect port number, e.g. QUICK_CONNECT_MG_PORT: 7688

Adding a health check

Including a health check in your Docker Compose configuration for Memgraph helps ensure that the container is not only up but also operational. Below is one possible approach to adding a health check to your docker-compose.yml for the Memgraph service:

services:
  memgraph:
    image: memgraph/memgraph-mage:latest
    container_name: memgraph-mage
    ports:
      - "7687:7687"
      - "7444:7444"
    healthcheck:
      test: ["CMD-SHELL", "echo 'RETURN 0;' | mgconsole || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 0s
    command: ["--log-level=TRACE"]

Here is what this healthcheck does:

test: The command echo 'RETURN 0;' | mgconsole || exit 1 runs within the shell to check the responsiveness of the Memgraph console. It's a simple command to verify that the database can process queries. If mgconsole fails to execute or returns a non-zero exit status, the health check fails.
interval: Specifies how often to run the health check. Here, it's set to every 10 seconds.
timeout: Sets the maximum time allowed for the health check to run. If the test command exceeds 5 seconds, the check is considered to have failed.
retries: Defines how many times the health check will retry upon failure before considering the service unhealthy. Here, it will try three times.
start_period: Sets the initialization period during which the health check command failures are considered to be setup failures rather than an unhealthy container. This is set to 0s, meaning it starts checking immediately at container start-up.

Docker Compose for Memgraph Platform image up to version 2.14

These instructions are listed here as a reference for legacy installations.

Starting with version 2.15, Memgraph Platform transitions to a multi-container application. This upgrade moves from a single Docker image to separate containers for Memgraph+MAGE and Memgraph Lab, utilizing Docker Compose for deployment and management.

Please note that the Memgraph Platform Docker image (opens in a new tab) is no longer being updated.

The memgraph-platform Docker image contains:

Memgraph database - the database that holds your data
Memgraph Lab - visual user interface for running queries and visualizing graph data
mgconsole - command-line interface for running queries
MAGE - graph algorithms and modules library

services:
  memgraph-platform:
    image: "memgraph/memgraph-platform"
    ports:
      - "7687:7687"
      - "3000:3000"
      - "7444:7444"
    volumes:
      - mg_lib:/var/lib/memgraph
      - mg_log:/var/log/memgraph
    env_file:
      - /path_to/.env  # Replace this with the actual path to your .env file
    entrypoint: ["/usr/bin/supervisord"]
volumes:
  mg_lib:
  mg_log:
  mg_etc:

and your .env file contains configuration flags you want to set:

MEMGRAPH="--log-level=TRACE"

The port 7687 is used for communication with Memgraph via Bolt protocol. The port 3000 is exposed because Memgraph Lab will be running as a web application on localhost:3000, while the port 7444 is there so that you can see logs from Memgraph inside Memgraph Lab. We specified three useful volumes:

mg_lib - directory containing data that enables data persistency
mg_log - directory containing log files
mg_etc - directory containing the configuration file

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

Configuration settings can be changed by setting the value of the MEMGRAPH environment variable. In the above example, you can see how to set --log-level to TRACE. Since Memgraph Platform is not a single service, the process manager supervisord (opens in a new tab) is used as the main running process in the entrypoint. The MAGE library is included in this image, so you can use the available graph algorithms.