Setting up your Environment
----------------------------

`Before setting up your Orchestra development environment, you need to have Docker properly set up and running on your machine.`

Pull down the latest version branch of the Appliance project: 
`https://gitlab.com/ledr/core/dev-platform/appliance/`_

Inside the appliance folder up avial profile of your appliance using:

.. code-block:: shell

    docker compose --profile="avial" up -d

Once you do that, create a `.env` file for the appliance at the root of the appliance folder. 
You only have to set `APPLIANCE_AUTHORITY` and `APPLIANCE_AUTH` variables. This is how your `.env` file would look like:

.. code-block:: shell

    APPLIANCE_AUTHORITY=xxxxxxxxxxxx
    APPLIANCE_AUTH=xxxxxxxxxxxx

To get the values, log into your appliance via Avu using: 

.. code-block:: shell

    docker exec -it $(appliance-avu-container-id) /bin/bash
    rlwrap ./avu

Execute the `root` command and then the `authorization` command. Take the outputted hexadecimal string and put it in the `.env` file.

You can also set up the certificate fields if you wish!  
There is extensive documentation for the entire appliance in every compose file in the Appliance project!  

`Do not touch any variables other than `APPLIANCE_AUTHORITY`, `APPLIANCE_AUTH`, and the `AVESTERRA_CERTIFICATE_*` variables that are under the `certificate_manager` service!`

Once the `.env` file is configured properly, start the orchestra profile of your appliance using, which includes maestro out of the box, using:

.. code-block:: shell

    docker compose --profile="orchestra" up -d


Below is a sample .env for your appliance. 
You can find these well documented within the master branch of the appliance project: 
`https://gitlab.com/ledr/core/dev-platform/appliance/`_

.. code-block:: shell

    ######################
    ### APPLIANCE_AUTH ###

    # This variable sets the target
    # Avial/AvesTerra host for all Orchestra
    # layer systems
    APPLIANCE_HOST=appliance

    # This variable sets the authorization code
    # that all Orchestra layer systems will
    # use to interact with the knowledge space
    # hosted APPLIANCE_HOST
    APPLIANCE_AUTH=5a5d61ce-e44c-4ecb-b9e6-5d57f22209xx

    # Specifies the path, on the local filesystem, to your configured .netrc which stores secrets that can be passed to Docker
    NETRC_PATH=~/.netrc

    # The root authority, this can be optional. 
    # You can set this on inital project startup, if you wish for it to also be your default APPLIANCE_AUTH.
    APPLIANCE_AUTHORITY=

    ######################


    #################################
    ### AvesTerra/Avial Variables ###

    # AvesTerra Release Number to use
    AVESTERRA_RELEASE=24-02

    # TCP Port, on the host, that the
    # AvesTerra server will be listening
    # on
    AVESTERRA_PORT=20057

    # Specifies where Docker containers
    # should access their certificates
    # from
    # If set to 'Certificates', a Docker volume
    # called Certificates will be created for
    # storing/managing Avial Certificates
    # If set to './Certificates', host directory
    # called Certificates will be created for
    # storing/managing Avial Certificates
    CERTIFICATE_ORIGIN=Certificates

    # Specifies where Docker containers
    # should access their configuration
    # files from
    # If set to 'Local', a Docker volume
    # called Local will be created for
    # storing/managing Avial configuration scripts
    # If set to './Local', a host directory
    # called Local will be created for loading
    # avial configuration scripts
    LOCAL_ORIGIN=Local

    # Specifies where Avial/AvesTerra containers
    # should store their data
    # If set to 'Data', a Docker volume
    # called Data will be created for
    # storing AvesTerra/Avial data
    # If set to './Data', a host directory
    # called Data will be created for storing
    # Avial/AvesTerra
    DATA_ORIGIN=Data

    # Specifies where AvesTerra will
    # put their Backups, if ENABLE_BACKUP
    # is set to "1"
    # If set to 'Backup', a Docker volume
    # called Backup will be created for
    # storing/managing Avial configuration scripts
    # If set to './Backup', a host directory
    # called Backup will be created for storing
    # Avial/AvesTerra backups
    BACKUP_ORIGIN=Backup

    # Sets the maximum amount of processes
    # that can concurrently execute in the
    # counter
    AVESTERRA_ULIMIT_NPROC=8192

    # Sets the soft limit on the number of
    # allowed concurrently open file descriptors
    AVESTERRA_ULIMIT_SOFT=4096

    # Sets the hard limit on the number of
    # allowed concurrently open file descriptors
    AVESTERRA_ULIMIT_HARD=8192

    # Sets maximum number of queued connections
    # you want on a listening socket
    AVESTERRA_SOMAXCONN=4096

    # Filter out information messages in adapters or not
    # If set to 1, the filtering will occur
    # If set to 0, the filtering will not occur, and the adapters/avesterra
    # will store INFORMATIONAL messages...will take more MEMORY!
    # It is recommended to leave this value as 0, unless you are
    # operating in a production environment, because Avial/AvesTerra
    # logs are all saved in memory...and memory usage can explode without
    # filtering.  In a development environment...this shouldn't be an issue
    # so information log filtering can be turned off
    FILTER_INFORMATION_LOG=0

    # Filter out information messages in adapters or not
    # If set to 1, your AvesTerra Data will be backed up
    # before AvesTerra starts
    # If set to 0, AvesTerra Data will not be backed up
    # up before AvesTerra starts
    ENABLE_BACKUP=0

    # Set RESTORE_POINT if you want to backup
    # from RESTORE_POINT on the next reboot.
    # I would recommend setting RESTORE_POINT to
    # an empty string after restoring; if you don't
    # then the restore point will be used again
    # after you reboot after restoring....could
    # delete valuable work.  Look in the Backup
    # Volume for RESTORE_POINTS; they should
    # have the .tar.gz extension
    # The RESTORE_POINT should be set to the full
    # name, with extension, of a RESTORE_POINT in
    # the Backups volume.
    RESTORE_POINT=""

    #################################

    ###########################
    ### Certificate Manager ###

    # If set to 1, generate a SELF-SIGNED certificate
    # to access server from the Avial CSR
    # If not set to 1 or set at all, an error message
    # will emit from the Certificate Manager, asking
    # you to send your server.csr, found in the Certificates
    # volume or mounted host directory(./Certificates)
    AVESTERRA_GENERATE_SELF_SIGNED_CERTIFICATE=1

    # Set the COUNTRY(C) to use for Avial Certificate CSR creation
    AVESTERRA_CERTIFICATE_COUNTRY=US

    # Set the PROVINCE/STATE(ST) to use for Avial Certificate CSR creation
    AVESTERRA_CERTIFICATE_STATE_OR_PROVINCE=Wisconsin

    # Set the LOCALITY/CITY(L) to use for Avial Certificate CSR creation
    AVESTERRA_CERTIFICATE_CITY=Madison

    # Set the ORGANIZATION(O) to use for Avial Certificate CSR creation
    AVESTERRA_CERTIFICATE_ORGANIZATION_NAME=LEDR

    # Set the DEPT NAME/ORGANIZATION UNIT(OU) to use for Avial Certificate CSR creation
    AVESTERRA_CERTIFICATE_ORGANIZATION_DEPT_NAME=Engineering

    # Set the COMMON NAME(CN)/HOSTNAME to use for Avial Certificate CSR creation
    AVESTERRA_CERTIFICATE_HOSTNAME=localhost

    # Set the EMAIL(emailAddress) to use for Avial Certificate CSR creation
    AVESTERRA_CERTIFICATE_OWNER_EMAIL=admin@ledr.io

    ###########################

    ################
    ### Explorer ###

    # This variable controls which
    # version of the explorer adapter
    # will be utilized in this appliance
    EXPLORER_RELEASE=XXXX

    ################

    ###############
    ### Maestro ###

    # This variable controls which
    # version of maestro that will be
    # utilized in this appliance
    MAESTRO_RELEASE=XXXX

    # [prod|dev]
    # Sets the operating mode of Maestro
    # If set to 'prod', then AUTH won't be auto
    # filled in the login page if operating
    # in 'standalone' mode
    # If set to 'dev', then AUTH will be auto
    # filled in the login page if operating
    # in 'standalone' mode
    ENV=dev

    # Sets the login mode of Maestro
    # If set to 'standalone', then maestro
    # will only allow logins via authorization
    # If set to anything else, then Maestro will
    # prompt the user for an identity username and
    # password
    LOGINMODE=standalone

    # Sets the protocol that will be used
    # by Maestro to interact with the WSS
    # aka the Web Socket to TLS/TCP Socket
    # translator
    WSS_PROTOCOL=ws

    # Sets the port that Maestro will
    # use to interact with the WSS
    # aka the Web Socket to TLS/TCP Socket
    # translator
    WSS_PORT=20058

    # Sets the host that Maestro will call out to
    # to resolve WSS requests
    WSS_HOST=localhost

    # The protocol that Maestro will use to
    # to listen on the MAESTRO_APP_PORT and
    # MAESTRO_CDN_PORT ports
    # If 'http' is used, then Maestro will listen
    # using the HTTP protocol
    # If 'https' is used, then Maestro will listen
    # using the HTTPS protocol
    MAESTRO_PROTOCOL=http

    # Sets the port that the Maestro container
    # will use to serve the Maestro react app
    MAESTRO_APP_PORT=8888

    # Sets the port that the Maestro container
    # will use to serve Maestro support content
    MAESTRO_CDN_PORT=9999

    ###############

    #############
    ### Mount ###

    # This variable controls which
    # version of the mount adapter
    # will be utilized in this appliance
    MOUNT_RELEASE=XXXX

    #############

    ###########
    ### WSS ###

    # This variable controls which
    # version of the wss that will
    # be utilized in this appliance
    WSS_RELEASE=XXXX

    # This variable controls where
    # the non-volatile storage of the WSS
    # certificates is located
    # If set to WSS, then a Docker volume
    # called WSS will be used to store the
    # certificates
    # If set to ./WSS, then a host mount
    # called WSS will be used to store the
    # certificates
    WSS_SSL_ORIGIN=WSS

    # The port that the WSS and its container
    # will listen on
    WSS_PORT=20058

    # This variable disables or enables automatic
    # certificate generation for the WSS
    # If set to 1, a self signed certificate will
    # be generated for the WSS
    # If not set, then one must provide their own
    # signed certificate for the WSS
    WSS_GENERATE_SELF_SIGNED_CERTIFICATE=1

    # The country to use for the WSS CSR(Certificate Signage Request)
    # generation
    WSS_CERTIFICATE_COUNTRY=US

    # The state/province to use for the WSS CSR(Certificate Signage Request)
    # generation
    WSS_CERTIFICATE_STATE_OR_PROVINCE=Wisconsin

    # The city to use for the WSS CSR(Certificate Signage Request)
    # generation
    WSS_CERTIFICATE_CITY=Madison

    # The organization to use for the WSS CSR(Certificate Signage Request)
    # generation
    WSS_CERTIFICATE_ORGANIZATION_NAME=LEDR

    # The department name to use for the WSS CSR(Certificate Signage Request)
    # generation
    WSS_CERTIFICATE_ORGANIZATION_DEPT_NAME=Engineering

    # The host/common name to use for the WSS CSR(Certificate Signage Request)
    # generation
    WSS_CERTIFICATE_HOSTNAME=localhost

    # The email to use for the WSS CSR(Certificate Signage Request)
    # generation
    WSS_CERTIFICATE_OWNER_EMAIL=admin@ledr.io

    ###########