.. raw:: html

  <ul class="breadcrumb">
      <li><a href="../../index.html">Home</a></li>
      <li><a href="../quickstart.html">QuickStarts</a></li>
      <li>Docker</li>
  </ul>

Quick-start - Containers
========================

*****

:stepnumberonedigit:`1` :stepheading:`Register with the Virtalica software and downloads portal`

To gain access to StorageFabric documentation and software,
register at https://content.virtalica.com.

*****

:stepnumberonedigit:`2` :stepheading:`Download and install the StorageFabric software`

Choose to either download and install the rpm, or to download and extract the tar file.

.. content-tabs::

    .. tab-container:: tab1
        :title: RPM

        :stepnumbertwodigits:`2a` :stepheading:`Download the StorageFabric rpm`

        .. code-block:: bash

                curl -s -S -u USERNAME URL --output storagefabric-4.1.0-1.c1.x86_64.rpm

        In the above commands, replace **USERNAME** with your registered user name with
        https://content.virtalica.com. Replace **URL** based on your selected distribution:

        **CentOS 7.x**

        .. parsed-literal::
            https://repos.virtalica.com/fabric/enterprise/centos/7/x86_64/storagefabric-4.1.0-1.c1.x86_64.rpm

        **RedHat 7.x**

        .. parsed-literal::
            https://repos.virtalica.com/fabric/enterprise/rhel/7/x86_64/storagefabric-4.1.0-1.c1.x86_64.rpm

        **RedHat 8.x**

        .. parsed-literal::
            https://repos.virtalica.com/fabric/enterprise/rhel/8/x86_64/storagefabric-4.1.0-1.c1.x86_64.rpm

        Enter your password when prompted to download the software.

        :stepnumbertwodigits:`2b` :stepheading:`Import StorageFabric RPM-GPG key`

        Download the repository key using the below command based on your distribution:

        .. content-tabs::

          **RedHat**

          .. code-block:: bash

            curl "https://repos.virtalica.com/fabric/enterprise/rhel/RPM-GPG-KEY-StorageFabric" \\
              -u USERNAME > /etc/pki/rpm-gpg/RPM-GPG-KEY-StorageFabric

          **CentOS 7**

          .. code-block:: bash

            curl "https://repos.virtalica.com/fabric/enterprise/centos/RPM-GPG-KEY-StorageFabric" \\
              -u USERNAME > /etc/pki/rpm-gpg/RPM-GPG-KEY-StorageFabric

        In the above commands, replace ``USERNAME`` with your registered user name.
        You will be prompted to enter the password.

        Import the repository key.

        .. code-block:: bash

                rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-StorageFabric


        :stepnumbertwodigits:`2c` :stepheading:`Install the StorageFabric rpm`

        The below command will create a directory /opt/storagefabric-4.1.0-1.c1/
        which contains the files necessary for running StorageFabric containers.

        .. code-block:: bash

            rpm -i storagefabric-4.1.0-1.c1.x86_64.rpm

    .. tab-container:: tab2
        :title: TAR

        :stepnumbertwodigits:`2a` :stepheading:`Download the StorageFabric tar`

        First, set your working directory to where you'd like the tar file stored. Then, download the tar file by using the below command.

        .. code-block:: bash

            curl -O -u USERNAME https://repos.virtalica.com/fabric/enterprise/files/storagefabric-4.1.0-1.c1.tar.gz

        In the above commands, replace ``USERNAME`` with your registered user name.
        You will be prompted to enter the password.

        The ``-O`` flag will result in the downloaded tar file having the same name as on the remote server, which is ``storagefabric-4.1.0-1.c1.tar.gz``

        :stepnumbertwodigits:`2b` :stepheading:`Create directory`

        A new directory needs to be created, which will be used in the next step to hold the extracted tar contents.

        .. code-block:: bash

            sudo mkdir -p /opt/storagefabric-4.1.0-1.c1

        :stepnumbertwodigits:`2c` :stepheading:`Extract tar`

        While in the directory with the tar downloaded in the first step, run the below command to extract its contents to the ``/opt/storagefabric-4.1.0-1.c1`` directory.

        .. code-block:: bash

            tar -xvzf storagefabric-4.1.0-1.c1.tar.gz -C /opt/storagefabric-4.1.0-1.c1

        The ``/opt/storagefabric-4.1.0-1.c1`` directory now contains everything needed to start running containers.

.. note::

    After this point, all steps will be the same, regardless of which option (rpm or tar) you selected.

*****

:stepnumberonedigit:`3` :stepheading:`Import the StorageFabric container image`

Run the below command to make the image available to your container manager.

.. content-tabs::

    .. tab-container:: tab1
        :title: Docker

        .. code-block:: bash

            docker load < /opt/storagefabric-4.1.0-1.c1/storagefabric-docker-image-4.1.0-1.c1.tar.gz

    .. tab-container:: tab2
        :title: Podman

        .. code-block:: bash

            podman load < /opt/storagefabric-4.1.0-1.c1/storagefabric-docker-image-4.1.0-1.c1.tar.gz

*****

:stepnumberonedigit:`4` :stepheading:`Create volumes`

Although you can use bind mounts, we recommend using volumes
instead. Volumes are more portable, allow the use of alternative
storage drivers (such as NFS), and do not require uid/gid mapping.

Create volumes for StorageFabric containers as shown below.

.. note::

    If your use case requires uid/gid, please set uid=997 and gid=995.

Docker Volumes
##############

.. content-tabs::

  .. tab-container:: tab1
    :title: Configuration Manager & Gateway

    .. code-block:: bash

        docker volume create storagefabric-logs

        docker volume create storagefabric-conf

        # Update the size to match your needs
        docker volume create storagefabric-cm-memstore \
            --opt type=tmpfs --opt device=tmpfs --opt o=size=256m

        docker volume create storagefabric-gw-memstore \
            --opt type=tmpfs --opt device=tmpfs --opt o=size=256m

  .. tab-container:: tab2
    :title: Configuration Manager only

    .. code-block:: bash

        docker volume create storagefabric-logs

        docker volume create storagefabric-conf

        # Update the size to match your needs
        docker volume create storagefabric-memstore \
            --opt type=tmpfs --opt device=tmpfs --opt o=size=256m

  .. tab-container:: tab3
    :title: Gateway only

    .. code-block:: bash

        docker volume create storagefabric-logs

        docker volume create storagefabric-conf

        # Update the size to match your needs
        docker volume create storagefabric-memstore \
            --opt type=tmpfs --opt device=tmpfs --opt o=size=256m

Podman Volumes
##############

.. note::

    If using Podman on RHEL, be advised that the size option is only supported on
    file systems that were mounted with ``prjquota`` enabled.
    If an error is encountered, see `xfs_quota(8) man page <https://man7.org/linux/man-pages/man8/xfs_quota.8.html#EXAMPLES>`_.

.. content-tabs::

  .. tab-container:: tab1
    :title: Configuration Manager & Gateway

    .. code-block:: bash

        podman volume create storagefabric-logs

        podman volume create storagefabric-conf

        # Update the size to match your needs
        podman volume create storagefabric-cm-memstore \
            --opt type=tmpfs --opt device=tmpfs --opt o=size=256m

        podman volume create storagefabric-gw-memstore \
            --opt type=tmpfs --opt device=tmpfs --opt o=size=256m

  .. tab-container:: tab2
    :title: Configuration Manager only

    .. code-block:: bash

        podman volume create storagefabric-logs

        podman volume create storagefabric-conf

        # Update the size to match your needs
        podman volume create storagefabric-memstore \
            --opt type=tmpfs --opt device=tmpfs --opt o=size=256m

  .. tab-container:: tab3
    :title: Gateway only

    .. code-block:: bash

        podman volume create storagefabric-logs

        podman volume create storagefabric-conf

        # Update the size to match your needs
        podman volume create storagefabric-memstore \
            --opt type=tmpfs --opt device=tmpfs --opt o=size=256m


*****

:stepnumberonedigit:`5` :stepheading:`Set up the StorageFabric configuration`

Enable which StorageFabric components are running within a container by setting
the file /opt/storagefabric-4.1.0-1.c1/storagefabric/storagefabric.env on the host.
For example, to enable only the :ref:`glossary-proxy`, use:

.. code-block:: bash

  STORAGEFABRIC_CONFIGURATION_MANAGER_ENABLED=false
  STORAGEFABRIC_GATEWAY_ENABLED=true

Then, change your StorageFabric configuration by editing the configuration files
on the host:

.. content-tabs::

  .. tab-container:: tab1
    :title: Configuration Manager

    Minimum configuration options that need to be set in
    /opt/storagefabric-4.1.0-1.c1/storagefabric/configuration_manager.yml:

    .. include:: ./common/configuration-manager-yml.rst

  .. tab-container:: tab2
    :title: Gateway

    Minimum configuration options that need to be set in
    /opt/storagefabric-4.1.0-1.c1/storagefabric/gateway.yml:

    .. include:: ./common/gateway-yml.rst

.. note::

    For detailed help and a complete list of all configuration options,
    refer to the StorageFabric Ansible roles documentation:

    * :doc:`../../../reference/ansible/roles/storagefabric_configuration_manager`
    * :doc:`../../../reference/ansible/roles/storagefabric_gateway`

*****

:stepnumberonedigit:`6` :stepheading:`Run the StorageFabric Container`

.. note::

  For optimal network performance, running containers in host network mode is strongly recommended.

  Virtualized networking can be used instead by replacing ``--network host`` with ``-p [port]:[port]`` in the following commands.

  For more details, see the documentation:

  .. content-tabs::

        .. tab-container:: tab1
            :title: Docker

                `Docker documentation <https://docs.docker.com/network/host/>`_.

        .. tab-container:: tab2
            :title: Podman

                `Podman documentation <https://docs.podman.io/en/latest/markdown/podman-run.1.html#network-mode-net>`_.

Docker Run
##########

.. content-tabs::

  .. tab-container:: tab1
    :title: Configuration Manager & Gateway

    .. code-block:: bash

        docker run -d --network host \
            --name "storagefabric" \
            -v storagefabric-logs:/var/log/storagefabric:Z \
            -v storagefabric-conf:/etc/storagefabric:Z \
            -v storagefabric-cm-memstore:/etc/storagefabric/configuration-manager/memstore:Z \
            -v storagefabric-gw-memstore:/etc/storagefabric/gateway/memstore:Z \
            -v /opt/storagefabric-4.1.0-1.c1/storagefabric:/storagefabric:ro \
            --cap-add CAP_NET_ADMIN \
            --ulimit nofile=17000:17000 \
            virtalica/storagefabric:4.1.0-1.c1

  .. tab-container:: tab2
    :title: Configuration Manager only

    .. code-block:: bash

        docker run -d --network host \
            --name "storagefabric" \
            -v storagefabric-logs:/var/log/storagefabric:Z \
            -v storagefabric-conf:/etc/storagefabric:Z \
            -v storagefabric-memstore:/etc/storagefabric/configuration-manager/memstore:Z \
            -v /opt/storagefabric-4.1.0-1.c1/storagefabric:/storagefabric:ro \
            --ulimit nofile=17000:17000 \
            virtalica/storagefabric:4.1.0-1.c1

  .. tab-container:: tab3
    :title: Gateway only

    .. code-block:: bash

        docker run -d --network host \
            --name "storagefabric" \
            -v storagefabric-logs:/var/log/storagefabric:Z \
            -v storagefabric-conf:/etc/storagefabric:Z \
            -v storagefabric-memstore:/etc/storagefabric/gateway/memstore:Z \
            -v /opt/storagefabric-4.1.0-1.c1/storagefabric:/storagefabric:ro \
            --cap-add CAP_NET_ADMIN \
            --ulimit nofile=17000:17000 \
            virtalica/storagefabric:4.1.0-1.c1

Podman Run
##########

.. content-tabs::

  .. tab-container:: tab1
    :title: Configuration Manager & Gateway

    .. code-block:: bash

        podman run -d --network host \
            --name "storagefabric" \
            -v storagefabric-logs:/var/log/storagefabric:Z \
            -v storagefabric-conf:/etc/storagefabric:Z \
            -v storagefabric-cm-memstore:/etc/storagefabric/configuration-manager/memstore:Z \
            -v storagefabric-gw-memstore:/etc/storagefabric/gateway/memstore:Z \
            -v /opt/storagefabric-4.1.0-1.c1/storagefabric:/storagefabric:ro \
            --cap-add CAP_NET_ADMIN \
            --cap-add=CAP_AUDIT_WRITE \
            --ulimit nofile=17000:17000 \
            localhost/virtalica/storagefabric:4.1.0-1.c1

  .. tab-container:: tab2
    :title: Configuration Manager only

    .. code-block:: bash

        podman run -d --network host \
            --name "storagefabric" \
            -v storagefabric-logs:/var/log/storagefabric:Z \
            -v storagefabric-conf:/etc/storagefabric:Z \
            -v storagefabric-memstore:/etc/storagefabric/configuration-manager/memstore:Z \
            -v /opt/storagefabric-4.1.0-1.c1/storagefabric:/storagefabric:ro \
            --cap-add=CAP_AUDIT_WRITE \
            --ulimit nofile=17000:17000 \
            localhost/virtalica/storagefabric:4.1.0-1.c1

  .. tab-container:: tab3
    :title: Gateway only

    .. code-block:: bash

        podman run -d --network host \
            --name "storagefabric" \
            -v storagefabric-logs:/var/log/storagefabric:Z \
            -v storagefabric-conf:/etc/storagefabric:Z \
            -v storagefabric-memstore:/etc/storagefabric/gateway/memstore:Z \
            -v /opt/storagefabric-4.1.0-1.c1/storagefabric:/storagefabric:ro \
            --cap-add CAP_NET_ADMIN \
            --cap-add=CAP_AUDIT_WRITE \
            --ulimit nofile=17000:17000 \
            localhost/virtalica/storagefabric:4.1.0-1.c1

.. note::

  * The capability **CAP_NET_ADMIN** is required for StorageFabric's
    :doc:`../qos/bandwidth-limits` feature on :ref:`Gateways<glossary-proxy>`.
    Certain gateway services in the container will fail to start without this capability.
  * The capability **CAP_AUDIT_WRITE** is required on RedHat for `Audit system logging <https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/security_guide/chap-system_auditing>`_ to function properly.
  * The option **\-\-ulimit nofile=17000:17000** specifies the hard and soft limit of open files
    that are consistent with StorageFabric default settings.

.. note::

    Kernel-level settings for container should be configured on the host. For more information,
    see `Configuring kernel parameters at runtime <https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_monitoring_and_updating_the_kernel/configuring-kernel-parameters-at-runtime_managing-monitoring-and-updating-the-kernel>`_.

    **fs.inotify.max_user_instances**

        1. Edit ``/etc/sysctl.conf`` and add the following line: ``fs.inotify.max_user_instances=256``.
        2. Execute the following command to load the new settings: ``sudo sysctl -p``

    **fs.inotify.max_user_instances** should be at least twice the number of
    logical cores for :ref:`Gateways<glossary-proxy>`.
    See :doc:`../../reference/files/system-administration-files`.

.. note::

  SELinux settings on the host need updates to let certain StorageFabric features work
  properly on the container.

  **QoS**

  To let the :doc:`QoS<../qos>` feature work on the container if using Podman and if
  SELinux is enabled on the host, please run the following command on the host:

  .. code-block:: bash

    setsebool -P domain_kernel_load_modules 1

.. note::

  To run the container in the foreground, remove the ``-d`` option.

.. note::

  Logs from within the container can be retrieved using the below commands.

  .. content-tabs::

        .. tab-container:: tab1
            :title: Docker

            .. code-block:: bash

                # stdout and stderr
                docker logs [-f] storagefabric

                # Configuration logs
                docker exec -it storagefabric bash -c 'cat /var/log/storagefabric/ansible/ansible*log'

            The ``-f`` flag can be used to follow the container output

        .. tab-container:: tab2
            :title: Podman

            .. code-block:: bash

                # stdout and stderr
                podman logs [-f] storagefabric

                # Configuration logs
                podman exec -it storagefabric bash -c 'cat /var/log/storagefabric/ansible/ansible*log'

            The ``-f`` flag can be used to follow the container output

Wait a few moments for StorageFabric to start up before
connecting to the :ref:`glossary-configuration-manager` or :ref:`glossary-proxy`.

*****

Using StorageFabric
-------------------

Once the StorageFabric container is running, use the endpoints described
in the following table:

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Endpoint
     - Description
   * - http://localhost:5600
     - The :ref:`glossary-configuration-manager` web interface and API endpoint.
       To login to the web interface, use the user **admin** and the password that you
       set in **configuration_manager.yml**.
   * - http://localhost:8080
     - The :ref:`glossary-proxy` endpoint.
       Use this endpoint for unified S3 data operations across all backend providers.

Next Step
---------

* :doc:`../tutorials/containers/basics`
* :doc:`../tutorials/containers/change-component-status`
* :doc:`../tutorials/containers/upgrade-container`
* :doc:`../tutorials/containers/hook-scripts`
* :doc:`../tutorials/containers/configuration-encryption`