.. _wirepas-tutorial-gui:
===========================================
Wirepas Services Tutorial
===========================================
This step-by-step guide walks you through deploying the Wirepas stack to a fleet of edge devices using Orchestra.
Video Tutorial
-------------------
.. raw:: html
Before You Begin
--------------------
Make sure you have the following:
1. **Active Orchestra Subscription:** For details, see :ref:`buying-orchestra-flow`.
2. **Edge Devices Onboarded:** Add your devices to Orchestra Manager (see :ref:`add-device`) and ensure they run Orchestra Daemon (orchestrad) version 1.4.13 or higher (see :ref:`updating-orchestra-daemon`).
3. **Docker Engine Installed:** Each edge device needs Docker Engine. Get it here: `Install Docker Engine `_
4. **Docker Compose File Prepared:** Save the following YAML configuration as ``docker-compose.yml``. We'll use it shortly.
.. include:: ../../../../shared/wirepas-docker-compose.rst
5. **Gather Variables:** You'll need values for these variables during the deployment process.
* ``WM_SERVICES_MQTT_USERNAME``
* ``WM_SERVICES_MQTT_PASSWORD``
* ``WM_SERVICES_MQTT_HOSTNAME``
* ``WM_SERVICES_MQTT_PORT``
* ``WM_GW_MODEL``
* ``WM_GW_VERSION``
* ``WM_GW_ID``
Deployment Steps
----------------
We'll divide the deployment into several key stages.
Step 1: Create a New Fleet
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Fleets group your devices for easier management. Here's how to set one up:
1. **Open Orchestra Manager:** Navigate to `Orchestra Manager `_ in your web browser.
2. **Go to Fleets:** Use the sidebar and click on "Fleets."
.. image:: images/fleets.png
:alt: Fleets Section in Orchestra Manager
:width: 100%
:align: center
3. **Add a New Fleet:** Click the "Add" button in the top-right corner.
4. **Configure the Fleet:** Give your fleet a descriptive name and select the target devices for your Wirepas deployment.
.. image:: images/create-new-fleet.png
:alt: Creating a New Fleet
:width: 100%
:align: center
Once created, your fleet will be visible:
.. image:: images/fleet-created.png
:alt: Newly Created Fleet
:width: 100%
:align: center
Step 2: Create a Composition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Think of a composition as the blueprint for your application.
1. **Navigate to Compositions:** In the sidebar, click on "Compositions."
.. image:: images/compositions.png
:alt: Compositions Section
:width: 100%
:align: center
2. **Create a Composition:** Click "Add" (top-right) and provide a name for your composition in the dialog box.
.. image:: images/create-new-composition.png
:alt: New Composition Dialog
:width: 100%
:align: center
Step 3: Create the First Composition Version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Each composition can have multiple versions, allowing you to manage updates effectively.
1. **Start Version Creation:** Click "Create first version" on the composition page.
.. image:: images/composition-newly-created.png
:alt: Newly Created Composition
:width: 100%
:align: center
2. **Specify Version:** Use semantic versioning (e.g., 1.0.0) for clarity.
3. **Upload Docker Compose:** Select the ``docker-compose.yaml`` file you prepared earlier.
.. image:: images/create-version.png
:alt: Creating the First Version
:width: 100%
:align: center
You'll now see an overview of your composition with the uploaded file:
.. image:: images/composition-overview.png
:alt: Composition Overview
:width: 100%
:align: center
Step 4: Attach Composition to the Fleet
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now, let's link your composition to the target fleet of devices.
1. **Go to Your Fleet:** Navigate back to the fleet you created in Step 1.
2. **Add the Composition:** In the "Compositions" table, click "Add".
.. image:: images/attach-composition.png
:alt: Adding a Composition to a Fleet
:width: 100%
:align: center
3. **Select the Composition:** Choose your newly created composition from the dropdown.
.. image:: images/choose-composition.png
:alt: Choosing the Target Composition
:width: 100%
:align: center
Step 5: Setting Variables at the Composition Level
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Variables provide customization for your deployment.
* **Variable Scopes in Orchestra:** Understand the hierarchy:
* **Device:** Unique to a single device.
* **Fleet:** Applies to all devices within a fleet.
* **Composition:** Specific to an application composition.
* **Global:** Universal settings across all devices and compositions.
* **Inheritance:** Variables inherit values from broader scopes:
Global > Composition > Fleet > Device
(More specific settings override broader ones).
**Add Composition Variables:**
1. Go to the "Variables" tab of your composition.
.. image:: images/composition-variables-empty.png
:alt:
:width: 100%
:align: center
2. Click "Add" to introduce a new variable.
3. Start with ``WM_SERVICES_MQTT_HOSTNAME`` – provide your actual hostname as the value.
.. image:: images/create-variable-composition.png
:alt:
:width: 100%
:align: center
4. Repeat the process to add these variables, providing their values:
* ``WM_SERVICES_MQTT_USERNAME``
* ``WM_SERVICES_MQTT_PASSWORD``
* ``WM_SERVICES_MQTT_PORT``
Step 6: Fleet-Level Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For environmental variables common to all devices in the fleet:
1. **Go to Fleet Variables:** Navigate to your fleet and open the "Variables" tab.
2. **Observe Inheritance:** Notice how the composition-level variables are already present due to inheritance.
3. **Add Fleet-Specific Variables:** Introduce:
* ``WM_GW_MODEL``
* ``WM_GW_VERSION``
.. image:: images/create-variable-fleet.png
:alt:
:width: 100%
:align: center
Step 7: Device-Level Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If needed, set individual device variables:
1. **Go to Device Variables:** Navigate to a device within your fleet and access its "Variables" tab.
2. **Confirm Inheritance:** Check if the variables from the fleet and composition levels are correctly inherited.
3. **Add Gateway ID:** Add the ``WM_GW_ID`` variable, specific to this device.
4. **Add another device-level variable:** ``WM_GW_SINK_UART_PORT`` for example value can be ``/dev/tty/ACM0``.
5. **Repeat for Other Devices:** Assign a unique ``WM_GW_ID`` to each device in your fleet.
.. image:: images/create-variable-device.png
:alt:
:width: 100%
:align: center
Step 8: Release Your Composition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Time to deploy!
1. **Go to Compositions:** On your fleet page, open the "Compositions" tab.
.. image:: images/fleet-compositions-tab.png
:alt: Compositions Tab
:width: 100%
:align: center
2. **Select and Release:** Choose your Wirepas composition and click "Create new release".
.. image:: images/create-new-release.png
:alt: Creating a New Release
:width: 100%
:align: center
Orchestra will begin deploying your composition to all devices in the fleet:
.. image:: images/composition-version-released.png
:alt: Release in Progress
:width: 100%
:align: center
Checking Deployment Success
----------------------------
1. **Go to Device Details:** On your fleet's "Compositions" tab, click a device's **ID** to see its details.
2. **Open Terminal:** In the device details, go to the "Terminal" tab and start a new terminal session.
3. **List Containers:** Run the command ``docker ps`` to view active containers. This confirms successful deployment.
Next steps
--------------
Next, you can :ref:`configuring-sink-via-cli`.
Need Help?
----------
Reach out through our `Customer Portal `_ if you encounter any issues.