README.md

AYON Launcher - Desktop application

Introduction

Desktop application launcher for AYON pipeline. You need AYON launcher to be able to interact with any of the integrated applications. It acts as the main entry point into the pipeline for all artists publishing and loading data with AYON. Even though AYON launcher is a standalone desktop application, it doesn't do anything until it's connected to an AYON server instance.

The main purpose of application is to distribute updates based on current server state and to start main logic of core addon. At this moment core addon is ayon_core.

Desktop application also deploys AYON shim, which acts as bridge for different versions of AYON launcher. More information here.

To get all the information about the project, go to AYON.io

Shim

AYON shim is a small executable that knows where to find "real" executable of AYON launcher.

Usage of shim:

1. Handle custom uri protocol scheme ayon-launcher:// which is used for running web actions.
2. Path to shim executable can be used for shortcuts and automations, so you don't need to worry about updating the path on AYON launcher update. This might be useful e.g. for Deadline plugin.

Shim is installed with AYON launcher, or on first run of AYON launcher. It is installed to app data which is based on OS, or to {AYON_LAUNCHER_LOCAL_DIR}/shim/ directory if AYON_LAUNCHER_LOCAL_DIR environment variable is set.

Caution

Shim on macOs is installed to /Applications/AYON.app. To be able to use it in automation which waits for AYON launcher to finish then you have to use full path to executable /Applications/AYON.app/Contents/MacOS/ayon.

Building AYON Desktop application

We aim to closely follow VFX Reference Platform

AYON is written in Python 3 with specific elements still running in Python2 until all DCCs are fully updated. To see the list of those, that are not quite there yet, go to VFX Python3 tracker

CX_Freeze is used to freeze the Python code and all of its dependencies, and Poetry for virtual environment management.

We provide comprehensive build steps:

• Windows
• macOS
• Linux - needs distribution specific steps

Linux build

We do recommend to use docker build options for linux distributions. Prepared dockerfiles do all necessary steps for you.

NOTE: There might be cases when linux installer should use PySide2 instead of PySide6 (which is default). You can change this by using --use-pyside2 in docker build command. Or you can use env variable QT_BINDING=pyside2 for local build.

Output of the build process is installer with metadata file that can be distributed to workstations.

Upload installer to server

Create installer information from json file on server and upload the installer file to be downloaded by users.

Windows

Run ./tools/manage.ps1 upload --server <your server> --api-key <your api key>

Or, run ./tools/manage.ps1 upload --server <your server> --username <your admin username> --password <your pasword>

Linux & macOS

Run ./tools/make.sh upload --server <your server> --api-key <your api key>

Or, run ./tools/make.sh upload --server <your server> --username <your admin username> --password <your pasword>

Upload command has more options, use --help to investigate them. For example, it is possible to use username & password instead of api key.

Running AYON Desktop application

AYON can be executed either from live sources (this repository) or from "frozen code" - executables that can be build using steps described above.

From sources

You need to create env and install dependencies first.

Ideally, this step should be re-run with each new version.

Windows

./tools/manage.ps1 create-env
./tools/manage.ps1 install-runtime-dependencies

Linux & macOS

./tools/make.sh create-env
./tools/make.sh install-runtime-dependencies

Run

AYON can be run directly from sources by activating virtual environment:

Windows

./tools/manage.ps1 run

Linux & macOS

./tools/make.sh run

From frozen code

You need to build AYON first. This will produce executable - ayon.exe and ayon_console.exe on Windows, ayon on Linux and AYON {version}.app for macOS.

Windows

Executable ayon_console.exe creates console with output - useful for debugging, ayon.exe does not create console, but does not have any stdout or stderr output.

Startup

Once AYON launcher is installed and launched there are few ways how to affect what will happen. Default behavior will ask for login to server, if user did not log in yet, then starts distribution of updates, and last step is to start the main logic.

Main logic is now using command line handling from ayon_core addon. If path to python script is passed it will start the python script as main logic instead.

Arguments

There are reserver global arguments that cannot be used in any cli handling:

• init-ayon-launcher - Initialize launcher. Register executable path to known AYON launcher locations, and install shim executable.
• --bundle <BUNDLE NAME> - Force AYON to use specific bundle instead of the one that is set in the config file. This is useful for testing new bundles before they are released.
• --verbose <LOG LEVEL> - Change logging level to one of the following: DEBUG, INFO, WARNING, ERROR, CRITICAL.
• --debug - Simplified way how to change verbose to DEBUG, unless AYON_LOG_LEVEL is already set. Also sets AYON_DEBUG environment variable to 1.
• --skip-headers - Skip headers in the console output.
• --use-dev - Use dev bundle and settings, if bundle is not explicitly defined.
• --use-staging - Use staging settings, and use staging bundle, if bundle is not explicitly defined. Cannot be combined with staging.
• --headless - Tell AYON to run in headless mode. No UIs are shown during bootstrap. Affects AYON_HEADLESS_MODE environment variable. Custom logic must handle headless mode on own.
• --ayon-login - Show login dialog on startup.
• --skip-bootstrap - Skip bootstrap process. Used for inner logic of distribution.

Environment variables

Environment variables that are set during startup:

• AYON_VERSION - Version of AYON launcher.
• AYON_BUNDLE_NAME - Name of bundle that is used.
• AYON_LOG_LEVEL - Log level that is used, see Logging.
• AYON_DEBUG - Debug flag enabled when set to '1'. Does not change log level, use AYON_LOG_LEVEL or --debug.
• AYON_USE_STAGING - Use staging settings when set to '1'.
• AYON_USE_DEV - Use dev mode settings when set to '1'.
• AYON_HEADLESS_MODE - Headless mode flag enabled when set to '1'.
• AYON_EXECUTABLE - Path to executable that is used to run AYON.
• AYON_ROOT - Root to AYON launcher content.
• AYON_LAUNCHER_STORAGE_DIR - Directory where are stored dependency packages, addons and files related to addons. At own risk can be shared (NOT TESTED).
• AYON_LAUNCHER_LOCAL_DIR - Directory where are stored user/machine specific files. This MUST NOT be shared.
• AYON_ADDONS_DIR - Path to AYON addons directory - Still used but considered as deprecated. Please rather use 'AYON_LAUNCHER_STORAGE_DIR' to change location.
• AYON_DEPENDENCIES_DIR - Path to AYON dependencies directory - Still used but considered as deprecated. Please rather use 'AYON_LAUNCHER_STORAGE_DIR' to change location.
• AYON_AUTO_UPDATE - Modify auto-update behavior which might be useful for shared distribution location. Missing AYON launcher, addon or dependency package won't be updated if is set to 'skip', instead will try to continue. And won't allow user to launch if is set to 'block' with brief explanation in a dialog.

Note

Environment variables AYON_LAUNCHER_STORAGE_DIR and AYON_LAUNCHER_LOCAL_DIR are by default set to the same folder. Path is based on OS.

• Windows: %LOCALAPPDATA%\Ynput\AYON
• Linux: ~/.local/share/AYON
• macOS: ~/Library/Application Support/AYON It is required to set the environment variables before AYON launcher is started as it is required for bootstrap.

Tip

Environment variables AYON_ADDONS_DIR and AYON_DEPENDENCIES_DIR by default lead relative to AYON_LAUNCHER_STORAGE_DIR.

• AYON_ADDONS_DIR -> {AYON_LAUNCHER_STORAGE_DIR}/addons
• AYON_DEPENDENCIES_DIR -> {AYON_LAUNCHER_STORAGE_DIR}/dependency_packages Changing their values will change where addons and dependency packages are stored even if you change AYON_LAUNCHER_STORAGE_DIR!

• AYON_MENU_LABEL - Label for AYON menu -> TODO move to ayon_core addon.

• SSL_CERT_FILE - Use certificates from 'certifi' if 'SSL_CERT_FILE' is not set.

Logging environment variables are described in Logging.

Logging

AYON launcher uses structured logging (structlog). Each record has a message and additional fields, e.g. logger.info("Distribution of {bundle} finished", bundle=bundle_name). Message is a message template using Python format string syntax, same as in ayon-core: fields are rendered into the message, tokens without a field are kept as they are, and the template is stored in message_template field of JSON records. Logging is configured by AYON launcher until control is passed to ayon_core (or to a script), which configures logging for its own needs with the same environment variables, see ayon-core.

There are three outputs, additive to each other:

1. Console - human readable output to stderr. Always enabled.
2. Log file - one JSON object per line (NDJSON), enabled with AYON_LOG_TO_FILE=1.
3. Vector - JSON records sent to a Vector HTTP source, enabled by setting AYON_VECTOR_LOG_URL.

Log level

Log level is set by AYON_LOG_LEVEL and applies to all outputs. It accepts a name (DEBUG, INFO, WARNING, ERROR, CRITICAL) or a number (10). Default is INFO. Arguments --verbose <LOG LEVEL> and --debug set it too.

Console

• Only the message is shown, additional fields (key=value) are not. Use message template to show them. Log file and Vector always contain all fields.
• Logger name is shown only with DEBUG log level.
• Message of spans contains their duration, e.g. launcher.bootstrap (duration 3.65s).
• Context fields (site_id, session_id, trace_id, span_id, parent_span_id) are never shown in console.
• Timestamps are in local time.

Variable	Description	Default
AYON_LOG_CONSOLE_STYLE	ayon - log level without padding, e.g. [info], structlog - default structlog layout with padded log level, e.g. [info ], logger name and all fields always shown.	ayon
AYON_LOG_CONSOLE_TIME_FORMAT	strftime format of timestamps, e.g. %H:%M:%S.%f. Invalid format falls back to the default.	%Y/%m/%d %H:%M:%S

Log file

Variable	Description	Default
AYON_LOG_TO_FILE	Write logs to a file when set to 1.	-
AYON_LOG_RETENTION_DAYS	Days after which old log files are removed, at least 1.	3

Log files are stored in logs subfolder of AYON_LAUNCHER_LOCAL_DIR, e.g. %LOCALAPPDATA%\Ynput\AYON\logs on Windows. Each process writes its own file ayon_<YYYYMMDD-HHMMSS>_<pid>.ndjson, rotated at midnight. Timestamps in log files are ISO 8601 in UTC.

Vector

Variable	Description	Default
AYON_VECTOR_LOG_URL	URL of Vector HTTP source, e.g. http://localhost:8686.	-

Records are sent in batches as JSON arrays from a background thread. When Vector is unreachable, records are dropped and sending is paused for a while.

Record fields

JSON records (log file and Vector) contain event (rendered message), message_template (when the message is a template), level, logger, timestamp and additional fields of the record, plus context fields:

• site_id - from AYON_SITE_ID.
• session_id - from AYON_SESSION_ID, correlates records of related processes.
• trace_id, span_id, parent_span_id - of the span in which the record was logged.

Developer mode

Developer mode enables to skip standard distribution process and use local sources of addon code. This is useful for development of addon. Developer mode must be enabled and configured on AYON server. To use it in AYON launcher create dev bundle and use --use-dev argument, or define bundle name --bundle <dev bundle name> in cli arguments.

Links

• Launcher Dev | AYON Docs
• AYON Developer Mode – Guide | AYON Forums
• How to keep up with AYON updates? | AYON Forums

TODOs

• Remove unused 'acre' dependency. Now has to be kept for ayon-core compatibility.