.. 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
========================

.. note::

    - Please replace ``4.5.0-1.c1`` with the desired version in the following steps.

``prerequisites``

* A RedHat 9 or Rocky Linux 9 system with *Docker* or *Podman* installed.

|

To get started with StorageFabric, use the following steps:

#. `Create a Configuration Bucket and Access Keys`_
#. `Install StorageFabric`_
#. `Set up the StorageFabric configuration`_
#. `Run StorageFabric`_
#. `Configure StorageFabric (Create Virtual Buckets)`_
#. `Upload data using StorageFabric`_

*****

Create a Configuration Bucket and Access Keys
---------------------------------------------

Create a :ref:`glossary-master-bucket` with a backend storage provider of your choice. With StorageFabric, all data (including configuration) is stored with backend providers. This makes StorageFabric components stateless, resulting in less management overhead, easy deployment & scaling, and quick disaster recovery.

:stepnumberonedigit:`1` :stepheading:`Create a configuration bucket and a data bucket with a storage provider.`

.. include:: common/prerequisites-buckets.rst

*****

:stepnumberonedigit:`2` :stepheading:`Get your storage provider access credentials.`

.. include:: common/prerequisites-credentials.rst

Next Step: `Install StorageFabric`_

*****

Install StorageFabric
---------------------

: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 -O -u USERNAME URL

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

        **RedHat 9.x**

        .. parsed-literal::

            https://repos.virtalica.com/fabric/enterprise/rhel/9/x86_64/storagefabric-4.5.0-1.c1.x86_64.rpm

        **Rocky 9.x**

        .. parsed-literal::

            https://repos.virtalica.com/fabric/enterprise/rocky/9/x86_64/storagefabric-4.5.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

          **Rocky**

          .. code-block:: bash

            curl "https://repos.virtalica.com/fabric/enterprise/rocky/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.5.0-1.c1/
        which contains the files necessary for running StorageFabric containers.

        .. code-block:: bash

            rpm -i storagefabric-4.5.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.5.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.5.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.5.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.5.0-1.c1`` directory.

        .. code-block:: bash

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

        The ``/opt/storagefabric-4.5.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.5.0-1.c1/storagefabric-docker-image-4.5.0-1.c1.tar.gz

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

        .. code-block:: bash

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

*****

Set up the StorageFabric configuration
--------------------------------------

:stepnumberonedigit:`1` :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:`2` :stepheading:`Set up the StorageFabric configuration`

Enable which StorageFabric components are running within a container by modifying
the file ``/opt/storagefabric-4.5.0-1.c1/storagefabric/storagefabric`` 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. Note that some minimum configuration options must be set to run StorageFabric.

.. note::

    The configuration file supports the Ansible format. Sensitive items can also be stored encrypted using the Ansible vault feature. For details, see :doc:`../tutorials/containers/configuration-encryption`.

    Moreover, these files are required when starting up a StorageFabric container. Once container has started, these files can be removed from the host system.

.. content-tabs::

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

    Minimum configuration options that need to be set in
    /opt/storagefabric-4.5.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.5.0-1.c1/storagefabric/gateway.yml:

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

.. note::

    To reconfigure a running container (without restart), see :ref:`containers-reconfiguration`.

.. 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`

*****

Run StorageFabric
-----------------

Run StorageFabric using Docker/Podman commands or as a systemd service.

Systemd
#######

Setup StorageFabric as a systemd service as described in :ref:`containers-basics-using-systemd`.

Then, simply run using:

.. code-block:: bash

    systemctl start storagefabric

Alternatively, use the underlying Docker/Podman commands directly.

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.5.0-1.c1/storagefabric:/storagefabric:ro \
            --cap-add CAP_NET_ADMIN \
            --ulimit nofile=17000:17000 \
            virtalica/storagefabric:4.5.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.5.0-1.c1/storagefabric:/storagefabric:ro \
            --ulimit nofile=17000:17000 \
            virtalica/storagefabric:4.5.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.5.0-1.c1/storagefabric:/storagefabric:ro \
            --cap-add CAP_NET_ADMIN \
            --ulimit nofile=17000:17000 \
            virtalica/storagefabric:4.5.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.5.0-1.c1/storagefabric:/storagefabric:ro \
            --cap-add CAP_NET_ADMIN \
            --cap-add=CAP_AUDIT_WRITE \
            --ulimit nofile=17000:17000 \
            localhost/virtalica/storagefabric:4.5.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.5.0-1.c1/storagefabric:/storagefabric:ro \
            --cap-add=CAP_AUDIT_WRITE \
            --ulimit nofile=17000:17000 \
            localhost/virtalica/storagefabric:4.5.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.5.0-1.c1/storagefabric:/storagefabric:ro \
            --cap-add CAP_NET_ADMIN \
            --cap-add=CAP_AUDIT_WRITE \
            --ulimit nofile=17000:17000 \
            localhost/virtalica/storagefabric:4.5.0-1.c1

.. note::

  For optimal network performance, running containers in host network mode is strongly recommended.  For more details, refer to the `Docker <https://docs.docker.com/network/host/>`_ or `Podman <https://docs.podman.io/en/latest/markdown/podman-run.1.html#network-mode-net>`_ documentation:

.. 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.

  **Bandwidth and API Rate Limits**

  To let the :doc:`../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.

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

Logs 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

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.

*****

Configure StorageFabric (Create Virtual Buckets)
------------------------------------------------

StorageFabric can be configured via the Command Line Interface (CLI),
the StorageFabric Web Interface, the :doc:`../../reference/api/cm-api-v2`, or using the :doc:`StorageFabric Ansible modules<../../reference/ansible/ansible>`.
In this tutorial, we will use the web interface.

Login to the web interface using the username *admin* and the password that was set in *configuration_manager.yml*. Once logged in to the Web Interface, continue to configure StorageFabric as follows.

**1.** Add access keys for your :ref:`glossary-data-bucket` to StorageFabric configuration.

Access keys for |data buckets| are also referred to as :ref:`glossary-cloud-access-keys`.
Provider Access Keys are used by the :ref:`glossary-proxy` to access the backend bucket.


.. include:: ../common/add-cloud-keys-web-ui.rst

|

**2.** Create a :ref:`glossary-data-bucket`.

.. include:: ../common/add-virtual-bucket-web-ui.rst

To learn more about bucket modes, refer to :doc:`../virtual-buckets`.

|

**3.** Create virtual access keys for :ref:`glossary-client`.

Access keys used by clients to authenticate to the :ref:`glossary-proxy`
are referred to as :ref:`glossary-client-access-keys`.

.. include:: ../common/create-client-keys-web-ui.rst

*****

Upload data using StorageFabric
-------------------------------

In this guide, we will use `s3cmd <http://s3tools.org/s3cmd>`_ as the client-side
tool. Many other existing client-side tools can be used with StorageFabric.
For more details, refer to the tutorial :doc:`../tutorials/using-client-tools-and-sdks`.

First, create a sample file using the command:

.. parsed-literal::

    touch mydata.txt

Then, upload the sample file to your **virtual-data-bucket** using the following
command with the |client access keys| generated earlier.

.. parsed-literal::

    s3cmd put mydata.txt s3://virtual-data-bucket/ \\
        --host localhost:8080 \\
        --host-bucket localhost:8080 \\
        --access_key <CLIENT_ACCESS_KEY_ID> \\
        --secret_key <CLIENT_SECRET_ACCESS_KEY> \\
        --signature-v2 --no-ssl

For remote clients, first add your |top level domain| to clients' **/etc/hosts** file
or set up DNS for your :ref:`glossary-top-level-domain`.
Then, use your :ref:`glossary-top-level-domain` to access cloud storage services via the StorageFabric |proxy|.

.. parsed-literal::

    s3cmd put mydata.txt s3://virtual-data-bucket/ \\
        --host <GATEWAY_DOMAIN>:8080 \\
        --host-bucket <GATEWAY_DOMAIN>:8080 \\
        --access_key <CLIENT_ACCESS_KEY_ID> \\
        --secret_key <CLIENT_SECRET_ACCESS_KEY> \\
        --signature-v2 --no-ssl

.. note::

    To use SSL connections between clients and the StorageFabric |proxy|, refer
    to the tutorial :doc:`../tutorials/setting-up-clients-ssl-connections`.

|

Next Steps
----------

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