Merge pull request #150 from fatfish-lab/aquarium/first-documentation

website/docs/addon_aquarium_admin.md

@@ -0,0 +1,107 @@
+---
+id: addon_aquarium_admin
+title: Aquarium
+sidebar_label: Aquarium
+---
+
+import ReactMarkdown from "react-markdown";
+import versions from '@site/docs/assets/json/Ayon_addons_version.json'
+
+<ReactMarkdown>
+{versions.Aquarium_Badge}
+</ReactMarkdown>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+![Aquarium addon for Ayon](assets/aquarium/aquarium-ayon-logo.png)
+
+## Introduction
+
+Aquarium addon, allow you to:
+
+ - Create new Ayon project using existing Aquarium's data
+ - Create new Aquarium project using existing Ayon's data
+ - Keep your Ayon project in sync with Aquarium, using Ayon services system and Aquarium's events.
+ - Publish media
+
+
+:::info
+In the future, new feature will be added, based on your requests. Feel free to [reach us](https://[email protected]).
+:::
+
+We are open to receive new pull request (PR). Follow our [developer documentation to start](addon_aquarium_developer).
+
+
+## Configuring addon
+
+First, you need to install the addon. It's available from Ayon market or you can install it from its repository. For that follow our [developer documentation](addon_aquarium_developer) or [Ayon's manual installation guide](admin_server_installing_addons)
+
+### Getting Aquarium bot
+
+Synchronizing Ayon and Aquarium rely on a specific account type called Bot.
+
+Go into your Aquarium `project settings`, `connectors` tab and select `Ayon`.
+
+![Enable Ayon connector in Aquarium](assets/aquarium/ayon-connector-enable.png)
+
+Select an existing bot, or create a dedicated bot for this project
+
+![Select or create a bot](assets/aquarium/ayon-connector-bot.png)
+
+When you create a bot, a `bot secret` is created. It's like a password, but for bot. So keep it safe ! It won't be shown twice. If you lost that secret, you will need to generate a new one.
+
+### Setting Ayon Secrets
+
+Go back to Ayon. From your `Studio settings`, select your `Secret` tab, and create two new secrets :
+
+ - One to store your bot_key
+ - Another one to store your bot_secret
+
+Choose the name you want, but if you don't have any idea, `aq_bot_key` and `aq_bot_secret` is a good start 👍
+
+![Ayon secrets](assets/aquarium/ayon-secrets.png)
+
+### Aquarium addon Studio settings configuration
+
+Once secrets are configured then Aquarium addon can be set. In your `Studio settings` or `Project settings` is you want a specific configuration only for the selected project, choose your `Aquarium` addon, and fill the inputs.
+
+:::tip
+Don't forget to select the correct bundle version on which you want to set this configuration.
+:::
+
+![Aquarium addon settings](assets/aquarium/aquarium-addon-settings.png)
+
+Here is the detail of each option:
+
+- **Aquarium URL** is your specific Aquarium URL you use to access to.
+- **Aquarium domain** is specific for Fatfish Lab developers, or customers who run Aquarium in a non DNS environment.
+- **Service settings** is all the setting dedicated to Aquarium services
+  - Select the **Bot key** secret you want to use
+  - Select the **Bot secret** you want to use
+- **Sync settings** is all the settings for synching data
+  - **Default sync info** regroup all default data transformation. It's used to transform Aquarium data to Ayon. Those settings are optional, if they are not provided, the addon will try to translate it for you.
+    - **Tasks** is for translating Aquarium's tasks to Ayon's tasks names
+    - **Statuses** is for transforming Aquarium's tasks statuses to Ayon's statuses
+
+
+## Starting Ayon Aquarium addon service
+
+Aquarium addon rely on two services to synchronize your projects:
+
+- Leecher, responsible to listening Aquarium events, and store them into Ayon's database for later process
+- Processor, responsible to processing specific Aquarium events, stored in Ayon's database. The processor "only" transform the data and then pass it to the Addon API.
+
+This requires to ASH to be working so the service can be attached to it. In main menu select Services.
+
+![Ayon services menu](assets/aquarium/ayon-services.png)
+
+Use **New service** button.
+
+![Spawn new service](assets/aquarium/ayon-spawn-service.png)
+
+Once ASH is working then worker options should be offering any available workers. Find `Aquarium` addon name and the same version which is used in your bundle. For easier late recognition, make sure to prefix your service with `aquarium_` or just `aq_`. Hit **Spawn** and wait for status of service to be set to green *Running*.
+
+:::info
+Don't forget to repeat the same action for the processor
+:::

website/docs/addon_aquarium_artist.md

@@ -0,0 +1,38 @@
+---
+id: addon_aquarium_artist
+title: Aquarium for artists
+sidebar_label: Artists
+---
+
+import ReactMarkdown from "react-markdown";
+import versions from '@site/docs/assets/json/Ayon_addons_version.json'
+
+<ReactMarkdown>
+{versions.Aquarium_Badge}
+</ReactMarkdown>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+![Aquarium addon for Ayon](assets/aquarium/aquarium-ayon-logo.png)
+
+## Introduction
+
+The Aquarium addon integration allow you to
+
+ - Authenticate the user
+ - Publish media
+
+:::tip We need you
+You are looking for other integrations or feature ? [Contact our team](mailto:[email protected]) to exchange about your need !
+:::
+
+## Signing to your Aquarium account
+
+From the launcher tray menu, click on Aquarium to show the sign-in form. Enter your Aquarium credential here.
+
+![Ayon launcher sign-in](assets/aquarium/ayon-launcher-signin.png)
+
+:::info
+This form will automatically open when the launcher start and the user is not login
+:::

website/docs/addon_aquarium_developer.md

@@ -0,0 +1,168 @@
+---
+id: addon_aquarium_developer
+title: Aquarium
+sidebar_label: Aquarium
+---
+
+import ReactMarkdown from "react-markdown";
+import versions from '@site/docs/assets/json/Ayon_addons_version.json'
+
+<ReactMarkdown>
+{versions.Aquarium_Badge}
+</ReactMarkdown>
+
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+![Aquarium addon for Ayon](assets/aquarium/aquarium-ayon-logo.png)
+
+## Introduction
+
+Welcome in the developer documentation of Aquarium addon and thanks for looking into it.
+
+This documentation is here to provide information on :
+
+- [How this code is structured](#code-structure) ?
+- [How to setup your developer environment](#developer-environment) ?
+
+:::info
+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 [[email protected]](mailto:[email protected])
+:::
+
+## Code structure
+
+This addon is composed by 3 main parts:
+
+- [Client](#client)
+- [Server](#server)
+  - API
+  - Frontend
+- [Services](#services)
+  - Leecher
+  - Processor
+
+### Directory
+
+#### Client
+
+Client code is used in the [Ayon Launcher](https://github.com/ynput/ayon-launcher), the AYON pipeline desktop application.
+
+:::info
+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](./dev_event_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](https://docs.docker.com/engine/install/) first.
+- [Ayon Docker](https://github.com/ynput/ayon-docker)
+- [Ayon Core](https://github.com/ynput/ayon-core)
+  - You can clone this one, into `ayon-docker/addons/core` folder. Here is the steps :
+    2. From the `core` folder execute this command:
+       - `git clone ssh://[email protected]:ynput/ayon-core.git dev`
+       - This command will clone the repository and rename it `dev`, in order to follow [Ayon addon directory structure](https://ayon.ynput.io/docs/admin_server_installing_addons#directory-structure)
+- [Ayon dependencies](https://github.com/ynput/ayon-dependencies-tool)
+- [Aquarium addon](https://github.com/ynput/ayon-aquarium)
+  - You can clone this one, into `ayon-docker/addons` folder. Here is the steps :
+    1. Create a folder `ayon-aquarium` in `ayon-docker/addons` folder
+    2. From the `ayon-aquarium` folder execute this command:
+       - `git clone ssh://[email protected]:ynput/ayon-aquarium.git dev`
+       - This command will clone the repository and rename it `dev`, in order to follow [Ayon addon directory structure](https://ayon.ynput.io/docs/admin_server_installing_addons#directory-structure)
+
+### Optional requirements
+
+If you are looking for Python type checking, you will need extra steps:
+
+1. Clone [Ayon Backend](https://github.com/ynput/ayon-backend) repository
+2. Clone [Aquarium python API](https://github.com/fatfish-lab/aquarium-python-api)
+3. Create a new pyenv dedicated for development `pyenv virtualenv ayondevaquarium` using python 3.10.12
+4. Enable your pyenv `pyenv shell ayondevaquarium` and/or select this pyenv in your IDE.
+5. Install dependencies from your local repositories
+   1. `python -m pip install -e /path/to/aquarium-python-api`
+   2. `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](https://github.com/ynput/ayon-docker).
+
+#### 2. Create a service user
+
+To interact with Ayon server, we need to create a service User.
+
+1. On your Ayon server, create a service user from `Studio settings` > `Users` tab > `Add new user`. Choose `Service` in the access level section.
+1. On the newly created Service User, generate an API Key.
+   1. Keep that API key, we will use it later.
+
+#### 3. Upload addon to Ayon
+
+1. From your `ayon-aquarium` folder, execute the file `create_package.py`
+2. Locate the `.zip` file created in the new folder `package`
+3. From Ayon server web interface, go to `Studio settings` > `Bundles` tab.
+4. Click on the button `Install addon` and upload your previous `.zip` file.
+5. Restart your Ayon server
+
+#### 4. Create a dev bundle
+
+1. From the `Studio settings` > `Bundles` tab, create a new bundle `aquarium-dev` (choose the name you want)
+2. Assign your self as a developer on this bundle
+3. Locate `aquarium` line in the addon list, and select the version where you have a `+git` at the end.
+4. Enable addon directory and paste the location of the client folder `ayon-docker/addons/ayon-aquarium/dev/client`
+5. Locate `core` line in the addon list, and select the version where you have a `+git` at the end.
+6. Enable addon directory and paste the location of the client folder `ayon-docker/addons/core/dev/client`
+7. Don't forget to save your dev bundle by clicking on the top right button `Save bundle`
+
+#### 5. Build Ayon dependencies
+
+1. From the Ayon dependencies repository folder, copy the file `example_env` as `.env` file.
+2. Edit this file and add your local Ayon dev server URL and your previously generated service API key.
+3. Run the command `./start install`
+4. Run the command `./start create -b aquarium-dev` (Use the name of the previously bundle you created)
+   1. This command will create and upload the dependencies to your Ayon server
+
+#### 6. Update bundle dependencies
+
+1. From the `Studio settings` > `Bundles` tab, select your `aquarium-dev` bundle.
+2. In the right panel, locate the section `Dependency Packages`
+3. Edit dependencies of your OS to select the latest upload dependencies
+
+---
+
+Congratulations, you are now good to go developing ! 🎉
+
+:::tip
+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.
+:::