.. _calm-simple-example:
Hello World Tutorial
=======================================
Here we will show you step-by-step how to deploy **Hello World!** application to a fleet of edge devices.
Video Tutorial
-------------------
.. raw:: html
Pre-requisites
------------------
1. Have Orchestra subscription (:ref:`more `).
2. Add all your edge devices to Orchestra Manager (:ref:`more `) or make sure the Orchestra Daemon (orchestrad) installed is version 1.4.13 or above (:ref:`updating-orchestra-daemon`).
3. Install Docker Engine on your edge devices (`Install Docker Engine `_).
4. Make sure your Docker Compose file ``docker-compose.yaml`` is ready and correct before proceeding. Copy the docker file from here and save in your working directory.
.. code:: yaml
services:
static-response-server:
environment:
HTTP_BODY: "Welcome into Carrots Server!\n"
HTTP_CODE: 200
image: colinodell/static-response-server
ports:
- 8080:8080
Steps
----------
Step 1: List All Fleets
^^^^^^^^^^^^^^^^^^^^^^^
Begin by listing all the fleets in your system. This helps you identify existing fleets before proceeding to create a new one (more: :ref:`ocli-calm-fleet-list`).
In this example we have no fleets.
.. tab-set::
.. tab-item:: Command
.. code:: console
$ ocli calm fleet list
.. tab-item:: Output
.. code:: console
:class: no-copybutton
$ ocli calm fleet list
No objects found
Step 2: Create a New Fleet
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now, create a fleet where you will deploy your compositions. Include all of the devices you want to deploy wirepas application on (more: :ref:`ocli-calm-fleet-create`).
.. tab-set::
.. tab-item:: Command
.. code:: console
$ ocli calm fleet create --name "name" --description "desc"
.. tab-item:: Output
.. code:: console
:class: no-copybutton
$ ocli calm fleet create --name "Carrots fleet" --description "Fleet of carrots doing carrots' things."
╒════════════════╤════════════════╤═════════╤═════════════╤═════════╤══════════════╤══════════════════════════╤═════════╤═════════════════╕
│ created_at │ updated_at │ name │ description │ devices │ compositions │ id │ status │ deployment_info │
├────────────────┼────────────────┼─────────┼─────────────┼─────────┼──────────────┼──────────────────────────┼─────────┼─────────────────┤
│ 2024-10-03 │ 2024-10-03 │ Carrots │ Fleet of │ [] │ [] │ 66feac2c9ee4869dbe1ac116 │ UNKNOWN │ │
│ 14:37:32+00:00 │ 14:37:32+00:00 │ fleet │ carrots │ │ │ │ │ │
│ │ │ │ doing │ │ │ │ │ │
│ │ │ │ carrots' │ │ │ │ │ │
│ │ │ │ things. │ │ │ │ │ │
╘════════════════╧════════════════╧═════════╧═════════════╧═════════╧══════════════╧══════════════════════════╧═════════╧═════════════════╛
Step 3: Create a Composition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Next, create a composition. It defines your app and will store the versioning of this app (more: :ref:`ocli-calm-composition-create`).
.. tab-set::
.. tab-item:: Command
.. code:: console
$ ocli calm composition create -n "name"
.. tab-item:: Output
.. code:: console
:class: no-copybutton
$ ocli calm composition create -n "Hello World for carrots app"
╒════════════════╤════════════════╤═════════╤══════════════════════════╤════════════════╕
│ created_at │ updated_at │ name │ id │ latest_version │
├────────────────┼────────────────┼─────────┼──────────────────────────┼────────────────┤
│ 2024-10-03 │ 2024-10-03 │ Hello │ 66feac83ac3bfd8b5dc6ea7b │ │
│ 14:38:59+00:00 │ 14:38:59+00:00 │ World │ │ │
│ │ │ for │ │ │
│ │ │ carrots │ │ │
│ │ │ app │ │ │
╘════════════════╧════════════════╧═════════╧══════════════════════════╧════════════════╛
Step 4: Attach Composition to the Fleet
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now, attach the composition you just created to your fleet. This step ensures that the fleet is ready to deploy the specified services (more: :ref:`ocli-calm-fleet-attach`).
.. tab-set::
.. tab-item:: Command
.. code:: console
$ ocli calm fleet attach composition -r
.. tab-item:: Output
.. code:: console
:class: no-copybutton
$ ocli calm fleet attach composition -r 66feac83ac3bfd8b5dc6ea7b 66feac2c9ee4869dbe1ac116
╒════════════════╤════════════════╤═════════╤═════════════╤═════════╤════════════════════════════╤══════════════════════════╤═════════╤═════════════════╕
│ created_at │ updated_at │ name │ description │ devices │ compositions │ id │ status │ deployment_info │
├────────────────┼────────────────┼─────────┼─────────────┼─────────┼────────────────────────────┼──────────────────────────┼─────────┼─────────────────┤
│ 2024-10-03 │ 2024-10-03 │ Carrots │ Fleet of │ [] │ ['66feacd5683b09301a966fdd │ 66feac2c9ee4869dbe1ac116 │ UNKNOWN │ {'devices': │
│ 14:37:32+00:00 │ 14:37:32+00:00 │ fleet │ carrots │ │ - Hello World for carrots │ │ │ [{'status': │
│ │ │ │ doing │ │ app'] │ │ │ 'TOTAL', │
│ │ │ │ carrots' │ │ │ │ │ 'count': 0}], │
│ │ │ │ things. │ │ │ │ │ 'compositions': │
│ │ │ │ │ │ │ │ │ [{'status': │
│ │ │ │ │ │ │ │ │ 'UNKNOWN', │
│ │ │ │ │ │ │ │ │ 'count': 1}]} │
╘════════════════╧════════════════╧═════════╧═════════════╧═════════╧════════════════════════════╧══════════════════════════╧═════════╧═════════════════╛
Step 5: Attach Devices to Your Fleet
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Add the required devices to your fleet. These devices will run the services defined in your composition (more: :ref:`ocli-calm-fleet-attach`).
.. note:: Use the arrow keys to navigate the list of devices, press Space to select devices, and hit Enter to confirm your selections.
.. tab-set::
.. tab-item:: Command
.. code:: console
$ ocli calm fleet attach device
.. tab-item:: Output
.. code:: console
:class: no-copybutton
$ ocli calm fleet attach device 66feac2c9ee4869dbe1ac116
[?] Pick devices you want to attach to fleet 66feac2c9ee4869dbe1ac116 - Carrots fleet:
[ ] 66d97c0b7814b7be62c5e66d - adam_raspberrypi
[ ] 66d99f328396f822d7393967 - great_kepler__154__corrupted
[ ] 66e13e6c2bc2262a5d5876e2 - test_adam_arm3
[ ] 66e13e994366760572c806f7 - test_adam_adm3
[X] 66e96c91b053f8dea450c2c0 - Harry-Test-GW #1
> [X] 66e96d25d72d0d4c0ff1962b - Harry-Test-GW #2
[ ] 66ea8308ad532faa0af547cd - SIDO Lyon GW
╒════════════════╤════════════════╤═════════╤═════════════╤════════════════════════════╤════════════════════════════╤══════════════════════════╤═════════╤═════════════════╕
│ created_at │ updated_at │ name │ description │ devices │ compositions │ id │ status │ deployment_info │
├────────────────┼────────────────┼─────────┼─────────────┼────────────────────────────┼────────────────────────────┼──────────────────────────┼─────────┼─────────────────┤
│ 2024-10-03 │ 2024-10-03 │ Carrots │ Fleet of │ ['66e96c91b053f8dea450c2c0 │ ['66feacd5683b09301a966fdd │ 66feac2c9ee4869dbe1ac116 │ UNKNOWN │ {'devices': │
│ 14:37:32+00:00 │ 14:37:32+00:00 │ fleet │ carrots │ - Harry-Test-GW #1', │ - Hello World for carrots │ │ │ [{'status': │
│ │ │ │ doing │ '66e96d25d72d0d4c0ff1962b │ app:1.0.0'] │ │ │ 'UNKNOWN', │
│ │ │ │ carrots' │ - Harry-Test-GW #2'] │ │ │ │ 'count': 2}, │
│ │ │ │ things. │ │ │ │ │ {'status': │
│ │ │ │ │ │ │ │ │ 'TOTAL', │
│ │ │ │ │ │ │ │ │ 'count': 2}], │
│ │ │ │ │ │ │ │ │ 'compositions': │
│ │ │ │ │ │ │ │ │ [{'status': │
│ │ │ │ │ │ │ │ │ 'UNKNOWN', │
│ │ │ │ │ │ │ │ │ 'count': 1}]} │
╘════════════════╧════════════════╧═════════╧═════════════╧════════════════════════════╧════════════════════════════╧══════════════════════════╧═════════╧═════════════════╛
Step 6: Create a Composition Version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
After creating the composition, create a composition version for it. This version will be linked to specific configurations in your compose file. (more: :ref:`ocli-calm-composition-version-create`).
.. note:: Make sure your Docker Compose file ``docker-compose.yaml`` is ready and correct before proceeding.
.. tab-set::
.. tab-item:: Command
.. code:: console
$ ocli calm composition-version create -f -v -d "description"
.. tab-item:: Output
.. code:: console
:class: no-copybutton
$ ocli calm composition-version create -f docker_compose.yaml -v 1.0.0 -d "This is an initial version of Hello World for carrots app" 66feac83ac3bfd8b5dc6ea7b
╒════════════════╤════════════════╤══════════════════════════╤═════════╤═════════════╤══════════════╤══════════════════════════╤══════════════════╕
│ created_at │ updated_at │ composition_id │ version │ description │ compose_file │ id │ composition_name │
├────────────────┼────────────────┼──────────────────────────┼─────────┼─────────────┼──────────────┼──────────────────────────┼──────────────────┤
│ 2024-10-03 │ 2024-10-03 │ 66feac83ac3bfd8b5dc6ea7b │ 1.0.0 │ This is an │ OK │ 66feacd5683b09301a966fdd │ Hello World for │
│ 14:40:21+00:00 │ 14:40:21+00:00 │ │ │ initial │ │ │ carrots app │
│ │ │ │ │ version of │ │ │ │
│ │ │ │ │ Hello World │ │ │ │
│ │ │ │ │ for carrots │ │ │ │
│ │ │ │ │ app │ │ │ │
╘════════════════╧════════════════╧══════════════════════════╧═════════╧═════════════╧══════════════╧══════════════════════════╧══════════════════╛
Step 7: Release Your Composition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Finally, release the desired composition version to your fleet. This will deploy the services across the devices in the fleet (more: :ref:`ocli-calm-release-create`).
.. tab-set::
.. tab-item:: Command
.. code:: console
$ ocli calm release create -v -f
.. tab-item:: Output
.. code:: console
:class: no-copybutton
$ ocli calm release create -v 66feacd5683b09301a966fdd -f 66feac2c9ee4869dbe1ac116
Release successfully requested.
Check your fleet in a few minutes.
Step 8: Check The Release
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
After few minutes let's check if the release succeeded. Use the fleet get command (more: :ref:`ocli-calm-fleet-get`).
If the status is ``RECONFIGURING`` wait a few minutes more.
.. tab-set::
.. tab-item:: Command
.. code:: console
$ ocli calm fleet get
.. tab-item:: Output
.. code:: console
:class: no-copybutton
$ ocli calm fleet get 66feac2c9ee4869dbe1ac116
╒════════════════╤════════════════╤═════════╤═════════════╤════════════════════════════╤════════════════════════════╤═══════════════════╤═══════════════╤══════════════════╕
│ created_at │ updated_at │ name │ description │ devices │ compositions │ id │ status │ deployment_info │
├────────────────┼────────────────┼─────────┼─────────────┼────────────────────────────┼────────────────────────────┼───────────────────┼───────────────┼──────────────────┤
│ 2024-10-03 │ 2024-10-03 │ Carrots │ Fleet of │ ['66e96c91b053f8dea450c2c0 │ ['66feacd5683b09301a966fdd │ 66feac2c9ee4869db │ OK │ {'devices': │
│ 14:37:32+00:00 │ 14:37:32+00:00 │ fleet │ carrots │ - Harry-Test-GW #1', │ - Hello World for carrots │ e1ac116 │ │ [{'status': │
│ │ │ │ doing │ '66e96d25d72d0d4c0ff1962b │ app:1.0.0'] │ │ │ 'OK', │
│ │ │ │ carrots' │ - Harry-Test-GW #2'] │ │ │ │ 'count': 2}, │
│ │ │ │ things. │ │ │ │ │ {'status': │
│ │ │ │ │ │ │ │ │ 'TOTAL', │
│ │ │ │ │ │ │ │ │ 'count': 2}], │
│ │ │ │ │ │ │ │ │ 'compositions': │
│ │ │ │ │ │ │ │ │ [{'status': │
│ │ │ │ │ │ │ │ │ 'OK', │
│ │ │ │ │ │ │ │ │ 'count': 1}]} │
╘════════════════╧════════════════╧═════════╧═════════════╧════════════════════════════╧════════════════════════════╧═══════════════════╧═══════════════╧══════════════════╛
Check it
-------------
After deploying user can check if is working by running:
If is called inside your device:
.. code:: console
:class: no-copybutton
$ curl http://localhost:8080
"Welcome into Carrots Server!"
And if device is exposed we can externally knowing its IP:
.. code:: console
:class: no-copybutton
$ curl http://XXX.XXX.XXX.XXX:8080
"Welcome into Carrots Server!"
Success!
Use Variables
--------------------
Now when you already seen how easy you can deploy your service, we can show you how to use variables:
First add variable:
.. code:: console
$ ocli calm variable create -k HTTP_BODY -v "Awesome response" -d "Response" global
Then restart composition:
.. code:: console
$ ocli calm release restart -f
That's it!
.. note:: If you are facing any problems or have suggestions please contact us through our `Customer Portal `_.