Get Started with Docker

This document provides step-by-step instructions on how to pull the latest TigerGraph Docker image to your host machine. You can follow the sections in sequence to set up the TigerGraph Docker environment.

The Docker image version of TigerGraph is for personal or R&D use and not for production use. It is preconfigured with a default username and password and so is not a secure environment until you change the password. It is not covered by our Support Policy. https://www.tigergraph.com/support-policy/

The latest TigerGraph Docker image includes the following content:

The latest version of TigerGraph
Linux packages:
- openssh-server
- git
- wget
- curl
- emac
- vim
- jq
- tar
Tutorial material
- GSQL 101
- GSQL 102
The latest GSQL open-source graph algorithm library

This follow-along video shows the whole setup process:

1. Install Docker Desktop

Follow the steps below to install Docker Desktop on your machine and configure it with sufficient resources for TigerGraph:

Install Docker on your OS:
- To install Docker for macOS, follow this video: Install Docker on Mac
  
  TigerGraph on Docker is not supported for ARM processors, including M1 Macs.
- To install Docker for Linux, follow these instructions:
  - Centos: https://docs.docker.com/install/linux/docker-ce/centos/
  - Ubuntu: https://docs.docker.com/install/linux/docker-ce/ubuntu/
- To install Docker for Windows OS, follow this video: https://www.youtube.com/watch?v=ymlWt1MqURY
Configure Docker Desktop with sufficient resources:
- Recommended: 4 cores and 16GB memory
- Minimum: 2 cores and 10GB memory
- Click the Docker Desktop icon, click Preferences >> Resources, drag the CPU and Memory sliders to the desired configuration, save and restart Docker Desktop

2. Prepare a shared folder for your container

Open a shell on your host machine and create or select a directory for sharing data between your host machine and Docker container and grant read, write, execute permission to the folder. This allows you to easily upload make files accessible to your Docker container. For example, to create a folder called data in Linux:

$ mkdir data
$ chmod 777 data

You can map the data folder to a folder under the Docker container, which allows you to share files between your host OS and Docker OS.

For example, if you mount the host OS folder ~/data to the docker folder /home/tigergraph/mydata, then anything you put on ~/data will be visible in the docker container under /home/tigergraph/mydata, and vice versa.

3. Run the TigerGraph Docker image as a daemon

Run the following command to pull the TigerGraph Docker image, bind ports, map a shared data folder, and start a container from the image:

$ docker run -d \ (1)
    -p 14022:22 \ (2)
    -p 9000:9000 \ (2)
    -p 14240:14240 \ (2)
    --name tigergraph \ (3)
    --ulimit nofile=1000000:1000000 \ (4)
    -v ~/data:/home/tigergraph/mydata \ (5)
    -v tg-data:/home/tigergraph \ (6)
    -t \ (7)
    tigergraph/tigergraph:latest (8)

1	`-d`: make the container run in the background.
2	`-p`: map Docker port 22 to the host OS port 14022, 9000 to host OS 9000, and 14240 to host OS 14240.
3	`--name`: name the container tigergraph.
4	`--ulimit`: set the `ulimit` (the number of open file descriptors per process) to 1 million.
5	`-v`: mount the host OS `~/data` folder to the Docker `/home/tigergraph/mydata` folder using the -v option. If you are using Windows, change the above ~/data to something using the Windows file system convention. For example, `c:\data`
6	`-v`: mounts a volume called `tg-data` to your container. If the volume doesn’t exist, Docker creates it automatically. This allows you to retain the data from your container. The next time you start up a new container with the same volume, all your changes are preserved.
7	`-t`: allocate a pseudo terminal.
8	`tigergraph/tigergraph:latest`: download the latest Docker image from the TigerGraph Docker registry URL tigergraph/tigergraph. Replace "latest" with a specific version number if a dedicated version of TigerGraph is to be used. For example, if you want to get the 3.0.5 version, the URL should be: `tigergraph/tigergraph:3.0.5`.

If you use Windows and have write permission issues with the above command, try the following command instead (this command does not map the shared folder on your host machine to your container) :

$ docker run -d -p 14022:22 -p 9000:9000 -p 14240:14240 --name tigergraph --ulimit nofile=1000000:1000000 -t tigergraph/tigergraph:latest

4. Connect to your container (via SSH or `docker exec`)

After launching the container, you can use SSH to connect to your container:

Verify that the container is running. You should see a row that describes the running container after running the command below:
```
$ docker ps | grep tigergraph
```
Use ssh to open a shell to the container. At the prompt, enter tigergraph as the password. Note that we have mapped the host 14022 port to the container’s 22 port (the ssh default port), so on the host we use ssh to connect to port 14022.
```
$ ssh -p 14022 tigergraph@localhost
```

You can also access your TigerGraph container via docker exec with the following command:

$ docker exec -it $(docker ps | grep tigergraph | awk '{print $1}') /bin/sh

5. Secure TigerGraph

Your TigerGraph image is preconfigured with a Linux user called tigergraph and a database superuser called tigergraph. Both have the default password tigergraph. If you do not change this, anyone with access to your database or docker container will be able to read and modify it.

Change the password of the Linux user tigergraph.
Change the password of the database user called tigergraph:
```
$ gsql ALTER PASSWORD tigergraph
```
For additional TigerGraph security settings, see Security.

Please follow best practices for securing and hardening the docker container especially when installing in a shared environment.

6. Start TigerGraph

After connecting to the container via ssh, inside the container, start all TigerGraph services with the following command (which may take up to one minute):
```
$ gadmin start all
```
Run the gsql command as shown below to start the GSQL shell. If you are new to TigerGraph, you can run the GSQL 101 tutorial now.
```
$ gsql
GSQL >
```
Start GraphStudio, TigerGraph’s visual IDE, by visiting http://localhost:14240

in a browser on your host OS.

7. Operation Commands Cheat Sheet

After you start Docker Desktop, use the commands below to stop and restart the container:
```
  $ docker container stop tigergraph
  $ docker container start tigergraph
```
Start the TigerGraph service within the container:
```
  $ gadmin start all
  $ gadmin stop  all
```
ssh to the container. Note: if localhost is not recognized, remove the localhost entry from ~/.ssh/known_hosts
```
  $ sed -i.bak '/localhost/d' ~/.ssh/known_hosts
  $ ssh -p 14022 tigergraph@localhost
```

Linux users can access the container through its ip address directly:

  $ docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' tigergraph
  $ vssh tigergraph@<container_ip_address>

Default user: tigergraph
Default password: tigergraph
After running gadmin start, you can go to GraphStudio. Open a browser on your host OS and access GraphStudio at the following URL:
```
  http://localhost:14240
```
Check the version of GSQL:
```
$ gsql version
```