# 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`](#docker-compose-for-memgraph-platform),
[`memgraph-mage`](#docker-compose-for-memgraph-mage-image), and
[`memgraph`](#docker-compose-for-memgraph-image). You can also find
Docker Compose configurations for [Memgraph Platform versions up to
2.14](#docker-compose-for-memgraph-platform-image-up-to-version-214).

## 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.

```yaml
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. 

> **Note**
>
> If you wish to set more than one configuration flag, use the following syntax: 

> `command: ["--setting-name1=value1", "--setting-name2=value2"]`

- [Read more about configuration settings](https://memgraph.com/docs/configuration/configuration-settings)

## Docker Compose for Memgraph MAGE image

The **Memgraph MAGE** image contains:

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

```yaml
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](https://memgraph.com/docs/database-management/configuration) 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.

```yaml
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:
```

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](https://memgraph.com/docs/database-management/configuration) 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 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](https://github.com/memgraph) 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.

> **Note**
>
> 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:

```yaml
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
```

> **Warning**
>
> 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`:

```yaml
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:

```yaml
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

> **Info**
>
> 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](https://hub.docker.com/r/memgraph/memgraph-platform) is no longer being
> updated.

The `memgraph-platform` Docker image contains:

- **Memgraph database** - the database that holds your data
- **[Memgraph Lab](https://memgraph.com/docs/data-visualization)** - visual user interface for running
  queries and visualizing graph data
- **[mgconsole](https://memgraph.com/docs/getting-started/cli)** - command-line interface for running
  queries
- **[MAGE](https://memgraph.com/docs/advanced-algorithms)** - graph algorithms and modules library

```yaml
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](https://memgraph.com/docs/database-management/configuration) 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`](https://docs.docker.com/config/containers/multi-service_container/)
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.