.. _install-on-macosx:

Mac OS X
--------

This section describes how to install, start, stop, and upgrade the Driverless AI Docker image on Mac OS X. Note that this uses regular Docker and not NVIDIA Docker.

**Note**: Support for GPUs and MOJOs is not available on Mac OS X.

The installation steps assume that you have a license key for Driverless AI. For information on how to obtain a license key for Driverless AI, visit https://h2o.ai/o/try-driverless-ai/. Once obtained, you will be prompted to paste the license key into the Driverless AI UI when you first log in, or you can save it as a .sig file and place it in the \license folder that you will create during the installation process.

**Caution**:  

- This is an extremely memory-constrained environment for experimental purposes only. Stick to small datasets! For serious use, please use Linux.
- Be aware that there are known performance issues with Docker for Mac. More information is available here: https://docs.docker.com/docker-for-mac/osxfs/#technology.

Environment
~~~~~~~~~~~

+-----------------------+---------------+---------+-----------------+
| Operating System      | GPU Support?  | Min Mem | Suitable for    |
+=======================+===============+=========+=================+
| Mac OS X              | No            | 16 GB   | Experimentation |
+-----------------------+---------------+---------+-----------------+

Installing Driverless AI
~~~~~~~~~~~~~~~~~~~~~~~~

1. Retrieve the Driverless AI Docker image from https://www.h2o.ai/download/. 

2. Download and run Docker for Mac from https://docs.docker.com/docker-for-mac/install.

3. Adjust the amount of memory given to Docker to be at least 10 GB. Driverless AI won't run at all with less than 10 GB of memory. You can optionally adjust the number of CPUs given to Docker. You will find the controls by clicking on (Docker Whale)->Preferences->Advanced as shown in the following screenshots. (Don't forget to Apply the changes after setting the desired memory value.)

.. image:: ../images/macosx_docker_menu_bar.png
   :align: center

.. image:: ../images/macosx_docker_advanced_preferences.png
   :align: center
   :height: 507
   :width: 382

4. On the File Sharing tab, verify that your macOS directories (and their subdirectories) can be bind mounted into Docker containers. More information is available here: https://docs.docker.com/docker-for-mac/osxfs/#namespaces.

.. image:: ../images/macosx_docker_filesharing.png
   :align: center
   :scale: 40%

5. Set up a directory for the version of Driverless AI within the Terminal: 

 .. code-block:: bash
    :substitutions:

    mkdir |VERSION-dir|

6. With Docker running, open a Terminal and move the downloaded Driverless AI image to your new directory.

7. Change directories to the new directory, then load the image using the following command:

 .. code-block:: bash
    :substitutions:

    cd |VERSION-dir|
    docker load < dai-docker-ubi8-x86_64-|VERSION-long|.tar.gz

8. Set up the data, log, license, and tmp directories (within the new Driverless AI directory):

 .. code-block:: bash

    mkdir data
    mkdir log
    mkdir license
    mkdir tmp


9. Optionally copy data into the **data** directory on the host. The data will be visible inside the Docker container at **/data**. You can also upload data after starting Driverless AI. 

10. Run ``docker images`` to find the image tag.

11. Start the Driverless AI Docker image (still within the new Driverless AI directory). **Replace TAG below with the image tag.** Note that GPU support will not be available. Note that from version 1.10 DAI docker image runs with internal ``tini`` that is equivalent to using ``--init`` from docker, if both are enabled in the launch command, tini prints a (harmless) warning message.

 We recommend ``--shm-size=2g --cap-add=SYS_NICE --ulimit nofile=131071:131071 --ulimit nproc=16384:16384`` in docker launch command. But if user plans to build :ref:`image auto model <image-model>` extensively, then ``--shm-size=4g`` is recommended for Driverless AI docker command.

 .. code-block:: bash
    :substitutions:

    docker run \
      --pid=host \
      --rm \
      --shm-size=2g --cap-add=SYS_NICE --ulimit nofile=131071:131071 --ulimit nproc=16384:16384 \
      -u `id -u`:`id -g` \
      -p 12345:12345 \
      -v `pwd`/data:/data \
      -v `pwd`/log:/log \
      -v `pwd`/license:/license \
      -v `pwd`/tmp:/tmp \
      h2oai/dai-ubi8-x86_64:|tag|

12. Connect to Driverless AI with your browser at http://localhost:12345.

Stopping the Docker Image
~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: stop-docker.rst

Upgrading the Docker Image
~~~~~~~~~~~~~~~~~~~~~~~~~~

This section provides instructions for upgrading Driverless AI versions that were installed in a Docker container. These steps ensure that existing experiments are saved. 

**WARNING**: Experiments, MLIs, and MOJOs reside in the Driverless AI tmp directory and are not automatically upgraded when Driverless AI is upgraded. 

 - Build MLI models before upgrading.
 - Build MOJO pipelines before upgrading.
 - Stop Driverless AI and make a backup of your Driverless AI tmp directory before upgrading.

 If you did not build MLI on a model before upgrading Driverless AI, then you will not be able to view MLI on that model after upgrading. Before upgrading, be sure to run MLI jobs on models that you want to continue to interpret in future releases. If that MLI job appears in the list of Interpreted Models in your current version, then it will be retained after upgrading. 

 If you did not build a MOJO pipeline on a model before upgrading Driverless AI, then you will not be able to build a MOJO pipeline on that model after upgrading.  Before upgrading, be sure to build MOJO pipelines on all desired models and then back up your Driverless AI tmp directory.  

**Note**: Stop Driverless AI if it is still running.

Upgrade Steps
'''''''''''''

1. SSH into the IP address of the machine that is running Driverless AI. 
2. Set up a directory for the version of Driverless AI on the host machine:

 .. code-block:: bash
    :substitutions:

    # Set up directory with the version name
    mkdir |VERSION-dir|

    # cd into the new directory
    cd |VERSION-dir|

3. Retrieve the Driverless AI package from https://www.h2o.ai/download/ and add it to the new directory. 

4. Load the Driverless AI Docker image inside the new directory:

 .. code-block:: bash
    :substitutions:

    # Load the Driverless AI docker image
    docker load < dai-docker-ubi8-x86_64-|VERSION-long|.tar.gz

5. Copy the data, log, license, and tmp directories from the previous Driverless AI directory to the new Driverless AI directory:

 .. code-block:: bash
    :substitutions:
    
    # Copy the data, log, license, and tmp directories on the host machine
    cp -a dai_rel_1.8.4/data |VERSION-dir|/data
    cp -a dai_rel_1.8.4/log |VERSION-dir|/log
    cp -a dai_rel_1.8.4/license |VERSION-dir|/license
    cp -a dai_rel_1.8.4/tmp |VERSION-dir|/tmp

 At this point, your experiments from the previous versions will be visible inside the Docker container.  

6. Use ``docker images`` to find the new image tag.

7. Start the Driverless AI Docker image.

8. Connect to Driverless AI with your browser at http://Your-Driverless-AI-Host-Machine:12345.