.. _quickStart:

Quick Start Guide
=================

The easiest way to get started with DPBuddy is to use its :ref:`docker image <dpbuddyDocker>`:

.. code-block:: bash

  docker pull myarch/dpbuddy:3.4
  docker volume create dpbuddy-work
  docker create -it --name dpbuddy -v dpbuddy-work:/opt/dpbuddy/src myarch/dpbuddy:3.4

You can later :ref:`further customize <dpbuddyDocker>` your docker configuration.

You can now start the container:

.. code-block:: bash

  docker start -i dpbuddy


Without docker, you can install DPBuddy from its distribution:

* `Install Java <https://java.com/en/download/help/index_installing.xml>`_ if it's not already installed. DPBuddy supports any flavor of Java 7 and Java 8/9, including Oracle, IBM and OpenJDK. If you already have Java 7 installed, make sure that the latest updates are applied. Make sure that you can run "java" from command line, e.g., ``java -version``.

* `Download DPBuddy <https://myarch.com/download-dpbuddy>`_ and unzip/untar the content of the file into a directory, e.g., ``c:\dpbuddy`` or ``/opt/dpbuddy``:

* Define the ``DPBUDDY_HOME`` environment variable and point it to the directory containing the DPBuddy installation, e.g., ``c:\dpbuddy\dpbuddy-3.4`` or ``/opt/dpbuddy/dpbuddy-3.4``.

* Add ``%DPBUDDY_HOME%\bin`` or ``$DPBUDDY_HOME/bin`` to your PATH environment variable. On Linux, make sure that ``$DPBUDDY_HOME/bin/dpbuddy`` has the "execute" permission, run the appropriate "chmod" command if it does not.

On Linux, you can add these lines to your .bashrc:

.. code-block:: bash

  export DPBUDDY_HOME=/opt/dpbuddy/dpbuddy-3.4
  export PATH=$DPBUDDY_HOME/bin:$PATH

On Windows, you can simply run these commands from the command line or update environment variables (Control Panel/System Properties/Environment Variables...):

.. code-block:: bat

  set DPBUDDY_HOME=c:\dpbuddy\dpbuddy-3.4
  set PATH=%DPBUDDY_HOME%\bin;%PATH%


Once DPBuddy is installed, type ``dpbuddy -h`` in a command line/terminal window. You should see a help screen containing the list of commands and options supported by the tool.

Now configure your DataPower appliances:

* Login to each appliance and enable XML Management if it's not already enabled. (Network/Management/XML Management).
* DPBuddy uses the "old" DataPower v2004 message format for file transfer (the 2004 schema is more efficient, since it allows for uploading multiple files at once). This means that the "SOAP Configuration Management (v2004)" checkbox must be checked on the XML management screen.
* Create a user account that will be used by DPBuddy. Make sure that you're able to login to WebGUI using this account and that the password was reset. The account does not have to be a privileged account, unless you want to be able to perform domain-level operations (restart domain, quiesce domain) using DPBuddy.

.. _dpbuddy_conf_quick_start:

Define your DataPower connection parameters in dpbuddy.conf file. ``dpbuddy.conf`` could :ref:`reside anywhere <confFileCli>`, but to get started you can use the ``dpbuddy.starter.conf`` file in ``$DPBUDDY_HOME/conf`` (e.g., ``c:\dpbuddy\dpbuddy-3.4\conf`` or ``/opt/dpbuddy/dpbuddy-3.4/conf``):

* If you're using the docker image, copy dpbuddy.starter.conf to the ``src`` directory: ``cp /opt/dpbuddy/conf/dpbuddy.starter.conf /opt/dpbuddy/src/dpbuddy.conf``.
* Without docker, rename dpbuddy.starter.conf to dpbuddy.conf. Keep dpbuddy.conf in the "conf" folder.
* Update your DataPower host(s) and the username/password for the DPBuddy account created earlier.

Your dpbuddy.conf file could look like this:

.. code-block:: js

  // Username that DPBuddy will use to login to DataPower
  dpUsername: dpbuddy
  dpPassword: 12345

  dev: {
      dpUrl: dp1-host
      dpDomain: dev
  }

  test: {
      dpUrl: dp2-host
      dpDomain: test
  }

You're now ready to run DPBuddy. First, run the :ref:`connect <testConnection>` command to make sure that you're able to connect to DataPower. Provide the name of the environment defined in dpbuddy.conf:

.. code-block:: bash

  dpbuddy connect -env dev

``connect`` prints some basic information about your appliance, including its firmware version. If you get any connection or authentication errors, please verify your domain name and username and password that you specified in "dpbuddy.conf". Note that DataPower raises an authentication exception if the domain that you provided does not exist.

If ``connect`` does not print any appliance information, verify that you're able to login to the appliance using the username/password from "dpbuddy.conf". If you just created the account, make sure that the password was reset.

You can use ``-h`` with any command to see the list of available options, e.g. ``dpbuddy import -h``.

You can now :ref:`export <export>` one of the domains:

.. code-block:: bash

  dpbuddy export -file dev-domain.zip -env dev

This command will export all objects in the domain. If you'd like to export only a subset of objects, first run :ref:`listObjects <listObjects>` to see all objects in the domain:

.. code-block:: bash

  dpbuddy listObjects -env dev

You can then filter objects using the ``-objects`` option:

.. code-block:: bash

  dpbuddy listObjects -objects WSGateway -env dev

To export only the gateways (and their dependent objects), run the following command:

.. code-block:: bash

  dpbuddy export -file dev-domain.zip -objects WSGateway -env dev

You can now import the exported objects into another domain. The target domain has to exist.

.. code-block:: bat

  dpbuddy import -file dev-domain.zip -save -env test


This command will import the exported objects into the "test" environment and it will also save the domain's configuration.

To verify that all gateways in the domain are up and running, run the :ref:`assertState <assertState>` command:

.. code-block:: bash

  dpbuddy assertState -activeService -objects WSGateway -env dev