> For the complete documentation index, see [llms.txt](https://dockgispy.gitbook.io/dockgispy/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dockgispy.gitbook.io/dockgispy/how-to-run-dockgispy-image.md).

# How to Run Dockgispy Image

With the understanding that you have now, you are well-equipped to run the Dockgispy docker image.\
Before you proceed, you need to be aware of two methods of running docker images, which are:

1. Pulling the image before running the image as a container
2. Running the image, which pulls the image automatically and runs the image as a container. Dockgispy can also be run with the above methods, given that it is a docker image. Both methods will be demonstrated below:

   **1. Pulling the image before running the image as a container**

   Pulling the image before running it as a container. You can either pull the image with a tag, this will pull the largest image tag by default, or you can pull with a tag.

   * Pulling without a tag: This pulls the largest image tag by default. The command to pull the image without a tag is shown below

     ```sh
     docker pull idowuilekura/dockgispy
     ```
   * Pulling the image with a tag of your choice. The command to pull the image with your specified tag is shown below

     ````
      ```sh
      docker pull idowuilekura/dockgispy:your_tag_name
      ```
     ````

#### Running the Pulled Docker Image

Once you have pulled the image, you need to run it with this command and specify an optional argument, which is the volume and port mapping.

* The `-v` command is needed to map the directory on the docker container with that on your local system. This ensures that you can store your work or operation (such as, files created or notebook created) on the container to your local system. If you do not provide the option, tasks will be lost once the container shuts down. The working directory on the container is `app`. Hence, to map a directory with the name `work_dir` on your local system to the `app`, you need to do path\_to\_work\_dir:app e.g `./work_dir:app` for a relative path or pass the absolute path with `/home/pc/app:app` - The `-p` is a docker command that maps the port on your system to that of the running container. You need to map any available port to port 8888 on the container. Jupyterlab and JupyterNotebook listen on port 8888 in the container. If you do not map the port on your system to that on the container, you will not be able to access the running instance of JupyterLab or Notebook in the container.

  To run the image you pulled without a tag, use the command below:

  ```
    docker run idowuilekura/dockgis -v  path_to_your_folder:app -p port_number:8888
    
  ```

  To run the image you pulled with a tag, use the command below:

  ```
    docker run idowuilekura/dockgispy:prefered_tag -v path_to_your_folder:app -p port_number:8888
  ```

**2. Running the image without pulling the image**

To run the image without first pulling the image, you can use the below command, and add the tag attribute if you want to automatically pull and run a particular image. `docker run idowuilekura/dockgispy -v path_to_your_folder:app -p port_number:8888`

#### Running the Image with Docker-Compose

A much easier method of running the image is through a docker-compose file, which automates running the docker image.\
Below is a sample docker-compose file to run the smallest dockgispy image. If you are unfamiliar with docker-compose, read more about it [here](https://www.freecodecamp.org/news/what-is-docker-compose-how-to-use-it/).

To specify the environment variable, you can uncomment or remove the hash key behind the environment and the `-IDE_SET=lab`. If you wish to set the development environment, to a notebook you can use `IDE_SET=notebook` Copy the content below, into a file with the name `docker-compose.yaml` and save it.

```
services:
  app:
    image: dockgispy:smallest
    container_name: dockgispycont
    # environment:
    #   - IDE_SET=lab
    ports:
      - "8000:8888"
    volumes:
      - ./app:/app
```

Once the file has been saved, you can start the container with this command `docker compose up`. The `docker compose up` command automatically pulls the image if it doesn't exist and runs the image.

**Note**: *Ensure you run the command in the terminal that matches the directory where the file is saved.*

**Video Demonstration of Running the Image** 

Follow, the steps below if you wish to watch a video on how to run the images with or without docker-compose

* Without Docker-compose

<https://github.com/user-attachments/assets/9127f8f6-4147-4ea9-8c42-d9cf5ec4e5e2>

* With Docker-compose

  <https://github.com/user-attachments/assets/878d5ede-e1c9-4580-82ff-9f56a58dfc09>