Using Ayon service host
=======================

Ayon service host (ASH) is a helper service that allows you to run other services in docker containers.
It periodically checks the services declared in the Ayon server database and starts them if they are not
running. It also provides a simple API for services to report their status and to receive configuration.

This document describes how to set up ASH and use it to run OpenPype import service.

Docker images
-------------

First ensure you have the latest version of ASH and openpype import docker images:

Addon services will be updated automatically when switched to proper verioning system,
during this stage you need to update them manually.

docker pull ynput/ayon-ash:latest
docker pull ynput/ayon-openpype-import:latest

Also make sure you have the latest version of the addon pulled from github.

Service user
------------

Ensure you have a service account with API key. For evaluation purposes you can use `settings/template.json` to make sure there is one with persistent API key.
Users defined in this file are created automatically when the server starts for the first time or when you run `make setup`.

  {
      "name": "service",
      "apiKey": "veryinsecurapikey",
      "isService": true
  }

In production you should create a service account using the web frontend it instead.

Setting up ASH
--------------

Now add ASH as a service to your docker-compose.yml file:

worker:                                                                                                                           
  image: ynput/ayon-ash:latest
  hostname: worker01
  restart: unless-stopped
  depends_on:
    - server
  volumes:
    - "/var/run/docker.sock:/var/run/docker.sock"
  environment:
    - "AYON_API_KEY=veryinsecureapikey"
    - "AYON_SERVER_URL=https://ayon.example.com"

`hostname` set here will be used as a name of the worker in the web frontend.

Notice that we are mounting docker socket into the container. This is required for ASH to be able to
start containers on the host machine.

ASH itself runs in the same docker compose stack in this example, but spawned services don't, so `AYON_SERVER_URL` must point to a host accessible from the docker network - in this case we use FQDN of the server, but it may as well be an IP address of the host machine or docker network IP address (172....). You cannot use `http://worker` or `localhost` here.

Starting
--------

Run the following command to start the worker:

docker-compose up --detach --build worker

You may re-run this command whenever you want to update the worker (after `docker pull`)

Setting up OpenPype import
--------------------------

In the settings/addon versions page of the web frontend, set the OpenPype addon to the latest version.

If you just pulled the latest version of the addon, you may need to restart the server to make sure
the new version is loaded.

After page reload, you should be able to see the OpenPype import tab in the settings page.

Now go to services page and create one or more instances of OpenPype import service.
Services should start automatically.

You can check the status of the service by running (replace `op3import` with the name of your service):

docker logs -f --tail=300 aysvc_op3import

Troubleshooting
---------------

If a service fails to stop and remove its container, check the running services using

docker ps | grep aysvc

and stop the orphaned ones manually using `docker stop`

Importing projects
------------------

Now go to the OpenPype import tab in the settings page and add a project to import.
You can add multiple projects, but they will be imported one after another.

Import file must be a zip file containing the project. Each zip contains a single `project.json` file. Optionally, it may contain a thumbnails directory.