<commit_before>.. _guide:

==============
Blockade Guide
==============

This guide walks you through a simple example that highlights the power of
Blockade. We will start a fake "application" consisting of three Docker
containers. The first runs a simple ``sleep`` command. The other two
containers ping the first. With this simple structure, we can easily see
what happens when we introduce partitions and network failures between
the containers.

Check your Blockade install
---------------------------

This guide assumes you have functional installation of Blockade and Docker,
and can run as root (or via sudo). To check, run the following commands:

.. code-block:: bash

    # check docker
    $ sudo docker info

    # check blockade
    $ sudo blockade -h

If you get an error from either command, you'll need to fix this before
proceeding. See the `Docker installation docs`_ and :ref:`install`.

Set up your Blockade config
---------------------------

Now create a new directory and in it create a ``blockade.yml`` file with
these contents:

.. code-block:: yaml

    containers:
      c1:
        image: ubuntu
        command: /bin/sleep 300000
        ports: [10000]

      c2:
        image: ubuntu
        command: sh -c "ping $C1_PORT_10000_TCP_ADDR"
        links: ["c1"]

      c3:
        image: ubuntu
        command: sh -c "ping $C1_PORT_10000_TCP_ADDR"
        links: ["c1"]


This configuration specifies the three containers we described above. Note
that we rely on Docker `named links`_ which require at least one open port.
Hence our sleeping ``c1`` container has a fake port 10000 open.

Start the Blockade
------------------

Now use the ``blockade up`` command to stand up our containers:

.. code-block:: bash

    $ sudo blockade up

    NODE            CONTAINER ID    STATUS  IP              NETWORK    PARTITION
    c1              b9794aaeed42    UP      172.17.0.2      NORMAL
    c2              875885f54593    UP      172.17.0.4      NORMAL
    c3              9b7227b42466    UP      172.17.0.3      NORMAL

You should see output like above. Note that you get the local IP address
and Docker container ID for each container.

Now let's take a look at the output of ``c2``, which is pinging ``c1``. We'll use
the ``blockade logs`` command, but pipe it through tail so we just get the last
several lines:

.. code-block:: bash

    $ sudo blockade logs c2 | tail
    64 bytes from 172.17.0.2: icmp_req=59 ttl=64 time=0.067 ms
    64 bytes from 172.17.0.2: icmp_req=60 ttl=64 time=0.077 ms
    64 bytes from 172.17.0.2: icmp_req=61 ttl=64 time=0.077 ms
    64 bytes from 172.17.0.2: icmp_req=62 ttl=64 time=0.073 ms<commit_msg>Add info about image existance requirement<commit_after>.. _guide:

==============
Blockade Guide
==============

This guide walks you through a simple example that highlights the power of
Blockade. We will start a fake "application" consisting of three Docker
containers. The first runs a simple ``sleep`` command. The other two
containers ping the first. With this simple structure, we can easily see
what happens when we introduce partitions and network failures between
the containers.

Check your Blockade install
---------------------------

This guide assumes you have functional installation of Blockade and Docker,
and can run as root (or via sudo). To check, run the following commands:

.. code-block:: bash

    # check docker
    $ sudo docker info

    # check blockade
    $ sudo blockade -h

If you get an error from either command, you'll need to fix this before
proceeding. See the `Docker installation docs`_ and :ref:`install`.

Set up your Blockade config
---------------------------

Now create a new directory and in it create a ``blockade.yml`` file with
these contents:

.. code-block:: yaml

    containers:
      c1:
        image: ubuntu
        command: /bin/sleep 300000
        ports: [10000]

      c2:
        image: ubuntu
        command: sh -c "ping $C1_PORT_10000_TCP_ADDR"
        links: ["c1"]

      c3:
        image: ubuntu
        command: sh -c "ping $C1_PORT_10000_TCP_ADDR"
        links: ["c1"]


This configuration specifies the three containers we described above. Note
that we rely on Docker `named links`_ which require at least one open port.
Hence our sleeping ``c1`` container has a fake port 10000 open.
The ``ubuntu`` image must exist in your Docker installation.
You can download it using the docker pull command ``sudo docker pull ubuntu``.

Start the Blockade
------------------

Now use the ``blockade up`` command to stand up our containers:

.. code-block:: bash

    $ sudo blockade up

    NODE            CONTAINER ID    STATUS  IP              NETWORK    PARTITION
    c1              b9794aaeed42    UP      172.17.0.2      NORMAL
    c2              875885f54593    UP      172.17.0.4      NORMAL
    c3              9b7227b42466    UP      172.17.0.3      NORMAL

You should see output like above. Note that you get the local IP address
and Docker container ID for each container.

Now let's take a look at the output of ``c2``, which is pinging ``c1``. We'll use
the ``blockade logs`` command, but pipe it through tail so we just get the last
several lines:

.. code-block:: bash

    $ sudo blockade logs c2 | tail
    64 bytes from 172.17.0.2: icmp_req=59 ttl=64 time=0.067 ms
    64 bytes from 172.17.0.2: icmp_req=60 ttl=64 time=0.077 ms
    64 bytes from 172.17.0.2: icmp_req=61 ttl=64 time=0.077 ms
    64 bytes from 172.17.0.2: icmp_req=62 ttl=64 time=0.073 ms
{'fraction_non_alphanumeric': 0.10208900999091734, 'fraction_numerical': 0.05667574931880109, 'mean_word_length': 2.4804045512010116, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 14, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1594168', 'n_tokens_mistral': 1819, 'n_tokens_neox': 1544, 'n_words': 718}