## Installation

Memgraph is a 64-bit Linux compatible database management system. Currently,
the Memgraph binary is offered only as a [Docker](https://www.docker.com)
image based on Debian Stretch. Before proceeding with the installation, please
install the Docker engine on the system. Instructions how to install Docker
can be found on the
[official Docker website](https://docs.docker.com/engine/installation).
Memgraph Docker image was built with Docker version `1.12` and should be
compatible with all latter versions.

### Docker Import

After a successful download the Memgraph Docker image
can be imported into Docker:

```
docker load -i /path/to/memgraph-<version>-docker.tar.gz
```

### Image Configuration & Running Memgraph

Memgraph can be started by executing:

```
docker run -it -p 7687:7687 memgraph:<version>
```

The `-it` option enables displaying Memgraph's logs inside the current shell.
The `-p` option is used to specify the port on which Memgraph will listen for
requests. Memgraph uses the Bolt protocol for network communication, which
uses port `7687` by default. The `<version>` part are 3 numbers specifying the
version, e.g. `1.2.3`.

It is recommended to perform some additional Docker configuration. Memgraph is
currently an in-memory database management system, but it periodically stores
all data to the hard drive. These storages are referred to as *snapshots* and
are used for recovering data in case of a restart.

When starting Memgraph, a folder for snapshots needs to be created and mounted on the host file system.
This can be easily done using Docker's named volumes. For example:

```
# Run Memgraph.
docker run -p 7687:7687 -v mg_data:/var/lib/memgraph memgraph:<version>
```

The `-v` option will make a named volume directory called `mg_data` and
Memgraph will store snapshots there. Named volumes are usually found in
`/var/lib/docker/volumes`.

The same can be achieved for logs and configuration. All supported volumes
which can be mounted are:

  * `/var/lib/memgraph`, for storing snapshots;
  * `/var/log/memgraph`, for storing logs and
  * `/etc/memgraph`, for Memgraph configuration.

Another way to expose the configuration and data is to use a full path to some
directory on the system. In such a case, the directory first needs to be
created and allow docker image to write inside. For example, to create a
snapshots volume in the current directory:

```
# Create the snapshots folder on the host.
mkdir -m 777 mg_data
# Docker expects full path to the created folder.
FULL_OUTPUT_PATH=$PWD/mg_data
# Run Memgraph.
docker run -p 7687:7687 -v ${FULL_OUTPUT_PATH}:/var/lib/memgraph memgraph:<version>
```

In this example, `-v` mounts a host folder `$PWD/mg_data` to a path inside the Docker
container.

Other than setting the configuration, it is also recommended to run the Docker
container in the background. This is achieved with `-d` option. In such a
case, the name should be set for the running container, so that it can be
easily found and shut down when needed. For example:

```
# Run Memgraph.
docker run -p 7687:7687 -d --name <memgraph_docker_container_name> memgraph:<version>
```

### Memgraph Configuration Parameters

Memgraph can be configured with a number of command-line parameters.  The
parameters should be appended to the end of the `docker run` command in the
`--param-name=param-value` format.  Following is a list of available
parameters:

 Name  | Type | Default | Description
-------|------|:-------:|-------------
 --interface | string | "0.0.0.0" | Communication port on which to listen.
 --port | integer | 7687 | Communication port on which to listen.
 --num-workers | integer | CPU count[^1] |  Number of Memgraph worker threads.
 --log-file | string | "memgraph.log" | Path to where the log should be stored.
 --snapshot-cycle-sec | integer | 300 | Interval (seconds) between database snapshots.<br/>Value of -1 turns taking snapshots off.
 --snapshot-max-retained | integer | 3 | Number of retained snapshots.<br/>Value -1 means without limit.
 --snapshot-on-exit | bool | false | Make a snapshot when closing Memgraph.
 --snapshot-recover-on-startup | bool | false | Recover the database on startup using the last<br/>stored snapshot.
 --query-execution-time-sec | integer | 180 | Maximum allowed query execution time. <br/>Queries exceeding this limit will be aborted. Value of -1 means no limit.
 --memory-warning-threshold | integer | 1024 | Memory warning threshold, in MB. If Memgraph detects there is less available RAM available it will log a warning. Set to 0 to disable.
 --query-plan-cache | bool Cache generated query plans.
 --query-plan-cache-ttl | int | 60 | Time to live for cached query plans, in seconds.
 --query-cost-planner | bool | true | Use the cost-estimating query planner.

[^1]: Maximum number of concurrent executions on the current CPU.

To find more about how to execute queries on Memgraph please proceed to
[Quick Start](quick-start.md).

### Cleanup

Status and Memgraph's logging messages can be checked with:

```
docker ps -a
docker logs -f <memgraph_docker_container_name>
```


Memgraph and its Docker container can be stopped with:

```
docker stop <memgraph_docker_container_name>
```

After the container has stopped, it can be removed by
executing:

```
docker rm <memgraph_docker_container_name>
```