.. _composition:

Create a Composition
=====================

This tutorial guides you through creating a composition in Orchestra's web application. 

.. note:: If you prefer using the command line, see :ref:`calm-ocli-overview`.

1. **Navigate to Compositions:** 
   
   - Open the Orchestra web application.
   - Use the sidebar to navigate to the **Compositions** page.
  
   .. image:: images/calm-compositions.png
       :alt: Create a new composition
       :width: 100%
       :align: center
  
2. **Create a New Composition:** 
   
   - Click the **Add** button in the top right corner.
   - A "Create a new composition" dialog will appear.
   - Enter the Name for your Composition.

3. **Create First Version**

   - Press the **Create first version** button in the middle of the screen.
   - Provide a version according to semantical versioning.
   - Upload a docker compose file for your composition.

   .. image:: images/calm-composition-create-new-version.png
       :alt: Create a first version of your newly created composition
       :width: 100%
       :align: center

   From here your composition overview page is shown with details and the docker compose is displayed.

   .. image:: images/calm-composition-overview.png
       :alt: First version fo your composition
       :width: 100%
       :align: center

4. **Managing Composition Variables:**
   
   - Click on the **Variables** tab at the top of the Composition details page.
   - Here, you can define custom variables that will apply to all devices that are running this composition. 

   .. note:: Initially, this tab might be empty or show inherited global variables.

   .. image:: images/calm-composition-variables-empty.png
       :alt: Composition variable page without any variables
       :width: 100%
       :align: center

5. **Creating a Composition Variable:** 
   
   - Click the **Add** button in the top right corner.
   - Enter the following:
      - **Key:** A unique identifier for your variable (e.g., `SERVER_PORT`).
      - **Value:** The value you want to assign to the variable (e.g., `8080`).
      - **Description (Optional):**  A brief explanation of the variable's purpose.

   .. image:: images/calm-composition-create-variable.png
       :alt: Creating a variable
       :width: 100%
       :align: center

   - Click **Create** to save the variable.

   Your new variable will now appear in the list of fleet variables:

   .. image:: images/calm-composition-variables.png
       :alt: Newly created fleet variable
       :width: 100%
       :align: center


**Next Steps:**

:ref:`release` of this composition on your fleet.