# Installation and deployment

Memgraph Lab can be installed in multiple ways, depending on your preferred
environment:

| Environment          | Description                                                                                                                        | Configurable | Recommended for                                       |
|----------------------|------------------------------------------------------------------------------------------------------------------------------------|:------------:|------------------------------------------------|
| 🖥️ [Desktop application](#install-memgraph-lab-desktop-application) | Available on Windows, macOS or Linux.                                                                                           | ❌           | Local development and testing.                  |
| 🐳 [Docker](#install-memgraph-lab-with-docker)                  | Run Memgraph Lab in a containerized environment.                                                                                | ✅           | Consistency and isolation in CI/CD pipelines or shared environments. |
| 🌐 [Public shared](https://lab.memgraph.com/)                     | Access the public shared Lab web application without installation if you have a public Memgraph database instance.                            | ❌           | Quick evaluations and convenience.              |

> **Warning**
>
> **It is recommended to run Memgraph Lab with Docker**. Some Enterprise features
> are not available in the desktop or public shared version of Memgraph Lab, but
> all Enterprise features are fully supported in the Docker environment. For the
> detailed comparison, refer to the [Features
> documentation](https://memgraph.com/docs/memgraph-lab/features).

In addition to learning how to install Memgraph Lab, this documentation also
covers how to [customize various settings](#custom-installation-settings) to
better suit your environment or deployment needs and explains [storage and
browser behavior](#storage-and-browser-behavior).

## Install Memgraph Lab desktop application

### Run Memgraph

Memgraph Lab requires a [running Memgraph database instance](https://memgraph.com/docs/getting-started).

If you installed Memgraph using Docker, ensure that ports `7687`, used for
instance connections (`-p 7687:7687`), and `7444`, used for logs (`-p
7444:7444`), are exposed.

### Download and install Memgraph Lab

Visit the [Download Hub](https://memgraph.com/download/#individual) and download
the Memgraph Lab desktop application. You can install Memgraph Lab by
double-clicking the downloaded installer and following the instructions.

If you downloaded Memgraph Lab on Linux, execute:

```
sudo dpkg -i MemgraphLab-x.x.x.deb
```

> **Info**
>
> If you encounter a security warning while installing
> Memgraph Lab on **Windows**, click on **More info** and verify that Memgraph is
> listed as the Publisher by clicking on **Run anyway**.

### Connect to Memgraph

Once you've started Memgraph and installed Memgraph Lab, you can
[connect](https://memgraph.com/docs/memgraph-lab/getting-started/connection-types) to your running Memgraph instance
through Memgraph Lab.

## Install Memgraph Lab with Docker

Running Memgraph Lab in a Docker container provides a convenient and isolated
environment for managing graph data. Follow these steps to get started:

### Run Memgraph

Memgraph Lab requires a [running Memgraph database instance](https://memgraph.com/docs/getting-started).

If you installed Memgraph using Docker, ensure that ports `7687`, used for
instance connections (`-p 7687:7687`), and `7444`, used for logs (`-p
7444:7444`), are exposed.

### Pull the Memgraph Lab Docker image

Before running Memgraph Lab, ensure that you have
[Docker](https://www.docker.com/) installed. Then, pull the latest Memgraph Lab
image using the following command:

```
docker pull memgraph/lab:latest
```

### Start the container

To start Memgraph Lab in a Docker container, run:

```
docker run -d -p 3000:3000 --name lab memgraph/lab
```

Once the container is up you can access Memgraph Lab on
`localhost:3000`.

> **Info**
>
> When running Memgraph Lab with Docker or Docker Compose, you can
> [configure it using the environment variables](https://memgraph.com/docs/memgraph-lab/configuration).

### Connect to Memgraph

Once you've started Memgraph and installed Memgraph Lab, you can
[connect](https://memgraph.com/docs/memgraph-lab/getting-started/connection-types) to your running Memgraph instance
through Memgraph Lab.

## Update Memgraph Lab

To get the latest features and improvements, update Memgraph Lab to the newest
version. When Lab starts with a newer version, it will automatically run upgrade
migrations on the data stored in the browser or desktop app storage. Note that
downgrade migrations are not supported, so reverting to an older version after
upgrading may result in data incompatibility.

**Desktop application**

Visit the [Memgraph Download Hub](https://memgraph.com/download), select your
  operating system, and download the latest Memgraph Lab installer. Install it
  over the existing version by following the same installation steps as for a
  fresh install.

**Docker**

Pull the latest Memgraph Lab Docker image and start a new container:

```
docker pull memgraph/lab:latest
```

  Then start the container:

```
docker run -d -p 3000:3000 --name lab memgraph/lab
```

## Custom installation settings

When deploying Memgraph Lab, you might need to customize certain settings to
better align with your environment or deployment requirements. This section
covers how to configure Memgraph Lab with a [custom base
path](#custom-base-path) and use [custom SSL
certificates](#custom-ssl-certificate) for secure communication. These settings
are especially useful when integrating Memgraph Lab with a reverse proxy or
securing your application with SSL.

For further customization, refer to the
[Configuration](https://memgraph.com/docs/memgraph-lab/configuration) documentation to learn how to
configure Memgraph Lab using environment variables.

### Custom base path

Starting from the version `2.19.0`, Memgraph Lab allows you to set up Memgraph
Lab with a custom base path for the web application when running it in Docker.
This configuration is especially beneficial when using a reverse proxy like
NGINX to manage access to multiple applications.

#### Configure the base path

To use this feature, you can define the environment variable `BASE_PATH` when
starting Memgraph Lab. For example, you can set `BASE_PATH` to `/mylab`, and
Memgraph Lab will be accessible at that base path (e.g. `localhost:3000/mylab`).

When running Memgraph Lab in Docker, specify the `BASE_PATH` environment
variable. For example:

> **Info**
>
> Starting with version 3.7.0, Memgraph Lab base paths support additional symbols
> such as `.`, `@`, and `~`, in addition to the already supported alphanumeric
> characters, hyphens (`-`), and underscores (`_`). This allows for more flexible
> and expressive URLs.

```
docker run -e BASE_PATH=mylab -p 3000:3000 memgraph/lab
```

This starts Memgraph Lab on port 3000 and sets the base path to `/mylab`.

#### Configure NGINX for reverse proxy

Here is an example nginx.conf for redirecting requests to Memgraph Lab:

```
# nginx.conf
events {}

http {
  server {
    listen 8080;

    location /mylab/ {
      proxy_pass http://localhost:3000/mylab/;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;

      # WebSocket specific headers
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "upgrade";
    }
  }
}
```

Explanation of key configurations:
- **`location`**: This should match the base path. In the example above, base path
  is `/mylab`, and location is `/mylab/`.
- **`proxy_pass`**: This should match the Memgraph Lab host and include the same
  base path as defined in `BASE_PATH`. In the example above, the base path is
  `/mylab`, and proxy_pass is `http://localhost:3000/mylab/`.
- **WebSocket headers**: These headers ensure WebSocket communication, such as the
  Logs feature in the Lab UI, works correctly. Include `proxy_http_version 1.1`,
  `proxy_set_header Upgrade` and `proxy_set_header Connection "upgrade"`.

> **Note**
>
> Special Note for Docker Networking: If both Memgraph Lab and the NGINX
> server are running on the same machine, but you access them using Docker,
> you can use `host.docker.internal` in proxy_pass instead of `localhost`.
>
> For example:
>
> ```
proxy_pass http://host.docker.internal:3000/mylab/;
```

#### Access Memgraph Lab

After configuring the above settings, Memgraph Lab will be
accessible via the reverse proxy at:

```
http://<nginx-server-address>:8080/mylab/
```

Replace `<nginx-server-address>` with the actual address of your
NGINX server.

### Custom SSL certificate

Memgraph Lab supports using custom SSL certificates, ensuring secure communication over HTTPS. To set up
SSL on Memgraph Lab you will need to configure a Dockerfile using a valid SSL certificate.

#### Generate SSL certificates

There are various options to generate SSL certificates. Check out the steps on
how to do that with OpenSSL and Let's Encrypt.

##### OpenSSL

[OpenSSL](https://github.com/openssl/openssl) is a widely used tool for
generating SSL certificates. You can create a self-signed certificate using the
following commands:

1. Generate a private key:
```bash
  openssl genrsa -out key.pem 2048
```

2. Generate a self-signed certificate:
```bash
  openssl req -new -x509 -key key.pem -out cert.pem -days 365
```

However, this option has an expiration date and is not signed by a publicly trusted
[certificate authority](https://en.wikipedia.org/wiki/Certificate_authority), which means
you will most likely receive a security warning from your browser while using it.

##### Let's Encrypt

[Let's Encrypt](https://letsencrypt.org/) is a free, automated, and open certificate authority
that provides SSL certificates. You can use tools like Certbot to obtain and install certificates.
To use Let's Encrypt:

1. Install Certbot.
2. Run Certbot to obtain your certificates:
```bash
  sudo certbot certonly --standalone -d yourdomain.com
```

This will generate your SSL certificate and key, typically located in
`/etc/letsencrypt/live/yourdomain.com/`.

#### Dockerfile setup

To run Memgraph Lab with custom SSL certificates, you need to create a
Dockerfile that specifies how to build the Docker image with your certificates.

You will need to set the `SSL_CERT_PATH` and `SSL_KEY_PATH` environment variables
to override the default `./ssl/` path used by Lab running in the container to
determine the SSL certificate location. After that, you should copy your certificates
(located in the `ssl` folder at the same location as your `Dockerfile`, for example)
into the container at the specified path.

> **Info**
>
> **Password-protected key**: If the private key was generated with password
> encryption, make sure to set `SSL_PASSPHRASE` to the corresponding passphrase.
>
> You will see the following error if the key is encrypted but no passphrase
> is provided:
>
> ```
SSL configuration failed: error:1C800064:Provider routines::bad decrypt
```

### Example Dockerfile

```docker
FROM memgraph/lab:latest

# Environment variables
ENV SSL_IS_ENABLED=true
ENV SSL_CERT_PATH=./myssl/cert.pem
ENV SSL_KEY_PATH=./myssl/key.pem

# COPY source_on_your_machine destination_in_container
COPY ssl/ ./myssl/

EXPOSE 3000
```

### Build and run the Docker container

1. **Create the SSL Directory**: Make sure your SSL certificate and key are placed
in a directory specified as `COPY` source in your Dockerfile.

2. **Build the Docker Image**: Run the following command to build your Docker image:
   `docker build -t memgraph-lab-ssl .`

3. **Run the Docker Container**: Start the container using the following command:
   `docker run -p 3000:3000 memgraph-lab-ssl`

4. **Access Memgraph Lab**: You can now access Memgraph Lab in your web browser at
`https://localhost:3000`. Ensure to configure your browser to trust the self-signed
certificate if you are using one.

## Storage and browser behavior

Memgraph Lab stores your data locally, which means access to saved queries,
styles, and collections depends on your browser or app setup. Understanding how
this works helps avoid unexpected data loss or confusion.

### Local storage and browser dependency

To ensure you can always access your collections and styles, it's important to
use the same browser and user profile.

The data associated with your setting, including saved queries, run history,
collection configurations, and styles, is stored directly in your browser's
storage (local storage and IndexedDB) or within the Memgraph Lab desktop app's
storage. This storage approach links your query collections and other objects to
your current browser profile or the specific installation of the Memgraph Lab
desktop app.

Because of this setup, keep the following in mind:
- Use the same browser and user profile to retain access to your data.
- Saved data doesn’t transfer between browsers (e.g., Chrome to Firefox).
- Data isn’t visible in private/incognito mode and will be lost after the
  session ends.
- Each browser profile has its own storage and doesn't share data with others.

### Clipboard access

If you're having trouble using `Ctrl + V` for copy-paste actions in Memgraph Lab
over HTTP, it's likely related to security protocols implemented by your web
browser. To avoid this you can allow clipboard access for specific
unsecured domains, but be
cautious as this lowers browser security.

Here's how you can do it in Chrome:
1. Go to `chrome://flags/#unsafely-treat-insecure-origin-as-secure`.
2. Enter the unsecured domain URL in "Insecure origins treated as secure".
3. Enable the setting and restart Chrome.

Use this method only for trusted sites due to the security implications.