# First steps with Docker

This guide helps you set up [Docker Desktop](https://docs.docker.com/desktop/)
and run Memgraph using Docker images.

## Prerequisites

Before proceeding, ensure Docker Desktop is installed and running on your
system. You can download it from the [official Docker
website](https://www.docker.com/products/docker-desktop/).

**System requirements:**
- **Windows**: Windows 10/11 64-bit (version 21H2 or higher), WSL2 enabled,
  hardware virtualization turned on.
- **MacOS**: One of the three most recent macOS versions, with at least 4GB of
  RAM.
- **Linux**: Docker Engine installed (instructions vary per distribution).

### Verify Docker installation

To verify Docker is installed and running:
1. Open Terminal (or Command Prompt).
2. Run:

```
docker --version
docker info
```

You should see version details and system information. 

### Troubleshoot

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.

## Run Memgraph with Docker

This is a quickstart example to get Memgraph running in Docker. For a more detailed overview, visit the how to [install Memgraph with Docker](https://memgraph.com/docs/getting-started/install-memgraph/docker) documentation.

  
### Download the Memgraph Docker image
 

  Use the following command to download an image:
```
docker pull memgraph/memgraph
```

  or for Memgraph with MAGE:

```
docker pull memgraph/memgraph-mage
```

  All Memgraph Docker images are available at [Memgraph's Docker
  Hub](https://hub.docker.com/u/memgraph). There you will find exact Docker
  image tags you can download and use to install Memgraph with. 

  
### Run a container

  Start Memgraph using:

```
docker run -p 7687:7687 --name memgraph memgraph/memgraph
```

  Common flags:
  - `-p 7687:7687`: Publish Bolt protocol port.
  - `--name memgraph`: Give your container a friendly name.

  To run Memgraph MAGE with the port for logs exposed:
```
docker run -p 7687:7687 -p 7444:7444 --name memgraph-mage memgraph/memgraph-mage
```

  
### Run with configuration

  The simplest way to apply [configuration
  setting](https://memgraph.com/docs/database-management/configuration) during a single
  run, is to pass the configuration flag within the `docker run` command. 
  For more options, check detailed instructions on [how to change the configuration](https://memgraph.com/docs/database-management/configuration#changing-configuration). 

  Apply configurations inline, for example:
  
```
docker run -p 7687:7687 memgraph/memgraph --memory-limit=50 --log-level=TRACE
```
  
  

## Manage containers

### Stop a container

> **Info**
>
> Stopping a container does **not** delete it. For removal instructions, see
>   [Delete container](#delete-a-container).

To stop a running database instance, use the docker stop command. You’ll need
the container’s [ID](#get-docker-containers-id) or name:

You can stop multiple containers at once by listing them all in the command.

```
docker stop CONTAINER1_ID CONTAINER2_ID CONTAINER3_NAME
```

### Start a container

To restart a stopped container:

1. List all containers (including stopped ones):

```
docker ps -a
```

2. Start the container by ID or name:

```
docker start <CONTAINER_ID>
# or
docker start <CONTAINER_NAME>
```

### Delete a container

> **Warning**
>
> Deleting a container is permanent. Make sure to back up any important data
>   before proceeding.

Before deleting a container, ensure it’s stopped. Then use the docker rm command
with the container’s [ID](#get-docker-containers-id) or name:

```
docker rm <CONTAINER_ID>
# or
docker rm <CONTAINER_NAME>
```

To remove multiple containers at once:

```
docker rm CONTAINER1_ID CONTAINER2_ID CONTAINER3_NAME
```

### `docker run` vs `docker start`

While they might sound similar, `docker run` and `docker start` serve very
different purposes:

`docker run` — **create & start a new container**
- Initializes a new container from a specified image.
- Pulls the image from Docker Hub if it’s not available locally.
- Often used with custom settings, environment variables, ports, or volume
  mounts.
- Suitable when you're launching a container for the first time.

> **Info**
>
> **Note**: If you're using the `latest` tag, `docker run` will not
>   automatically fetch the newest image unless it’s missing locally. To ensure
>   you're using the most up-to-date version, run `docker pull <IMAGE>` before
>   `docker run`.

```
docker run [OPTIONS] IMAGE [COMMAND]
```

`docker start` — **restart an existing container**
- Reactivates a previously stopped container without changing its configuration.
- Does not create a new container.
- Useful for quickly resuming work with the same container state.

```
docker start <CONTAINER_ID or NAME>
```

**Key difference**: `docker run` creates a brand-new container. `docker start`
brings an existing one back to life.

## Inspect and access

### Get Docker container's ID

To list all running containers and get their IDs, use:

```
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 use either the full `CONTAINER ID` or a shortened version (e.g., `d44f`)
if it’s unique.

### Get Docker container's IP address

First, retrieve the container’s ID or name.

Then run:

```
docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' <CONTAINER_ID>
```

Example:

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

### Access the file system inside a container

To browse files inside a container, you’ll need its ID or name.
Run:

```
docker exec -it <CONTAINER_ID> bash
```

Once inside the container, you can use standard Linux commands:
- `ls` – list files and directories
- `cd <directory>` – change to a directory
- `cd ..` – go up one directory
- `cat <file>` – display file contents

## File management

### Copy files from a Docker container

To copy files from a container to your local machine:
1. First, ensure you know the container’s ID or name.
2. Navigate to the local directory where you want to save the file.
3. Use the following command:

```
docker cp <CONTAINER_ID>:<path_in_container> <local_destination>
```

**Example**: Copying a configuration file to the Desktop:

```
docker cp bb3de2634afe:/etc/memgraph/memgraph.conf memgraph.conf
```

This will save `memgraph.conf` in the current directory.

### Copy files to a Docker container

To copy a file from your local system into a container:
1. Know the container’s ID or name.
2. Be in the local directory where the file is located.
3. Use the command:
```
docker cp <local_file> <CONTAINER_ID>:<path_in_container>
```

**Example**: Replacing the configuration file inside the container:

```
docker cp memgraph.conf bb3de2634afe:/etc/memgraph/memgraph.conf
```

This will overwrite the file inside the container with your local version.