Aquarium
Introduction
Welcome in the developer documentation of Aquarium addon and thanks for looking into it.
This documentation is here to provide information on :
Disclaimer: We are new developers into Ayon's ecosystem. The following documentation might require some improvements and we may have missed steps. Feel free to update this file or directly reach us at support@fatfi.sh
Code structure
This addon is composed by 3 main parts:
Directory
Client
Client code is used in the Ayon Launcher, the AYON pipeline desktop application.
The client integration is not finished yet.
This client integration allow you to
- Authenticate the user
- Publish media
Server
Python server-side part of the addon. It's mainly used to declare specific addon API endpoints, used by the leecher and processor services to keep your data in sync.
It's also responsible to declare specific addon settings, in your Ayon server and project settings.
Frontend
This folder is used to provide a web UI in your Ayon settings to pair projects between Ayon and Aquarium and also to trigger a full project sync.
Services
Syncing data between Ayon and Aquarium relies on Ayon services system.
This addon use two services:
- Leecher
- It's listening Aquarium's events, and store them into Ayon database for async processing.
- Processor
- It's looking for specific Aquarium events in Ayon's database and process them to transform data into compatible Ayon's structure and send request to addon server API endpoints to interact with the server.
Developer environment
Requirements
You will need to clone several Ayon repositories in order to run everything locally:
- You need to install Docker first.
- Ayon Docker
- Ayon Core
- You can clone this one, into
ayon-docker/addons/core
folder. Here is the steps : 2. From thecore
folder execute this command:git clone ssh://git@github.com:ynput/ayon-core.git dev
- This command will clone the repository and rename it
dev
, in order to follow Ayon addon directory structure
- You can clone this one, into
- Ayon dependencies
- Aquarium addon
- You can clone this one, into
ayon-docker/addons
folder. Here is the steps :- Create a folder
ayon-aquarium
inayon-docker/addons
folder - From the
ayon-aquarium
folder execute this command:git clone ssh://git@github.com:ynput/ayon-aquarium.git dev
- This command will clone the repository and rename it
dev
, in order to follow Ayon addon directory structure
- Create a folder
- You can clone this one, into
Optional requirements
If you are looking for Python type checking, you will need extra steps:
- Clone Ayon Backend repository
- Clone Aquarium python API
- Create a new pyenv dedicated for development
pyenv virtualenv ayondevaquarium
using python 3.10.12 - Enable your pyenv
pyenv shell ayondevaquarium
and/or select this pyenv in your IDE. - Install dependencies from your local repositories
python -m pip install -e /path/to/aquarium-python-api
python -m pip install -e /path/to/ayon-backend
Setup your dev environment
1. Start Ayon
Start your Ayon instances, from the Ayon Docker repository, using the command docker compose up --build
. For a more precise steps, check out the repository README file.
2. Create a service user
To interact with Ayon server, we need to create a service User.
- On your Ayon server, create a service user from
Studio settings
>Users
tab >Add new user
. ChooseService
in the access level section. - On the newly created Service User, generate an API Key.
- Keep that API key, we will use it later.
3. Upload addon to Ayon
- From your
ayon-aquarium
folder, execute the filecreate_package.py
- Locate the
.zip
file created in the new folderpackage
- From Ayon server web interface, go to
Studio settings
>Bundles
tab. - Click on the button
Install addon
and upload your previous.zip
file. - Restart your Ayon server
4. Create a dev bundle
- From the
Studio settings
>Bundles
tab, create a new bundleaquarium-dev
(choose the name you want) - Assign your self as a developer on this bundle
- Locate
aquarium
line in the addon list, and select the version where you have a+git
at the end. - Enable addon directory and paste the location of the client folder
ayon-docker/addons/ayon-aquarium/dev/client
- Locate
core
line in the addon list, and select the version where you have a+git
at the end. - Enable addon directory and paste the location of the client folder
ayon-docker/addons/core/dev/client
- Don't forget to save your dev bundle by clicking on the top right button
Save bundle
5. Build Ayon dependencies
- From the Ayon dependencies repository folder, copy the file
example_env
as.env
file. - Edit this file and add your local Ayon dev server URL and your previously generated service API key.
- Run the command
./start install
- Run the command
./start create -b aquarium-dev
(Use the name of the previously bundle you created)- This command will create and upload the dependencies to your Ayon server
6. Update bundle dependencies
- From the
Studio settings
>Bundles
tab, select youraquarium-dev
bundle. - In the right panel, locate the section
Dependency Packages
- Edit dependencies of your OS to select the latest upload dependencies
Congratulations, you are now good to go developing ! 🎉
Don't forget to restart your Ayon server if you work on the server part, it's the only way to take your modification in consideration.