Overview

You can provision your AYON server using the following methods:

• The AYON Web UI

• AYON Docker Helper Scripts

• AYON Server CLI Tools.

• Modifying the conent of the AYON Docker addons and storage directories.

AYON Docker Helper Scripts

The AYON Docker repository includes a set of helper scripts that can be accessed using make on Linux and Mac, and manage.ps1 on Windows.

Arguments for Server Management

These arguments are used for provisioning and maintaining the AYON server.

• setup: Applies the settings template from settings/template.json.

• dbshell: Opens a PostgreSQL shell.

• reload: Reloads the running server.

• demo: Creates demo projects based on the settings in the ./demo directory.

• dump <PROJECT>: Dumps a project's database into a file.

• restore <PROJECT> <SQL File>: Restores a project's database from a file.

Arguments for Development

These arguments assist with development.

• backend: Clones or updates the ayon-backend repository into the ./backend directory within your ayon-docker clone.

• frontend: Clones or updates the ayon-frontend repository into the ./frontend directory within your ayon-docker clone.

• build: Builds the AYON Docker image from the ./backend and ./frontend directories.

• relinfo: Creates a RELEASE file with version information (for debugging purposes).

Setup

The settings/template.json file allows you to specify server settings without using the web UI.

You can apply these settings by running the setup argument in the terminal:

Example
Windows
Linux & Mac
Copy
cd <path to your ayon docker>
./manage.ps1 setup

Service Account​

A common use case for template.json is creating a service account. This allows you to have a default service account with a hardcoded API key, which is useful for development since the web interface always generates a random API key.

You can create a service account by modifying the settings/template.json provisioning file and then running the setup argument.

Example template.json :

Example
settings/template.json
Copy
{
    "users": [
        {
            "name": "service",
            "apiKey": "veryinsecurapikey",
            "isService": true
        }
    ]
}

dbshell

The dbshell argument allows accessing AYON’s Postgre DB shell.

Example
Windows
Linux & Mac
Copy
cd <path to your ayon docker>
./manage.ps1 dbshell

Alternatively, you can access the DB shell via a Docker command, which works on all operating systems (Windows, Linux, and Mac):

docker compose exec postgres psql -U ayon

Example DB Shell: Print all projects in AYON.

psql (15.13 (Debian 15.13-1.pgdg120+1)) Type "help" for help.

ayon=# SELECT name from projects;
       name        
-------------------
 demo_Commercial
 demo_Big_Episodic
(2 rows)

demo

To help you become familiar with the web interface, the demo/ directory includes three demo project templates:

• demo_Commercial

• demo_Big_Episodic

• demo_Big_Feature

Example
Windows
Linux & Mac
Copy
cd <path to your ayon docker>
./manage.ps1 demo

dump

This argument dumps a project's database into a file, which is primarily used for creating backups.

Example
Windows
Linux & Mac
Copy
cd <path to your ayon docker>
./manage.ps1 dump projectname=<project_name>

It output’s project database sql file dump.{project_name}.sql.

restore

This argument restores a project's database from a file, which is primarily used for restoring from backups.

Example
Windows
Linux & Mac
Copy
cd <path to your ayon docker>
./manage.ps1 restore projectname=<project_name> <project_db_sql_file>

AYON Server CLI Tools

Since AYON Server version 1.11.0, command-line interface (CLI) tools have been included in the AYON server image. These tools can be accessed using the docker compose exec server with the ay command.

• To view the list of available tools:

  cd <path to your ayon docker>
  docker compose exec server ay --help 

• To run a specific tool:

  cd <path to your ayon docker>
  docker compose exec server ay {toolname} 

Addons Directory

AYON addons are installed into the addons directory, following this structure:

addons/
  └── {addon_name}/
         └── {addon_version}/

Manage Addons Manually

You can add or remove addons to your AYON server by modifying the contents of the addons directory.

Using Development Versions of Addons​

AYON supports the use of addons that are in active development. A +git suffix is added to the addon's version to differentiate it from a production version. This happens because the addon's version directory contains the .git folder.

To set up a development version of an addon, follow these steps:

1. Create a directory for the addon within the addons folder if it doesn’t exist already, using the addon's name (specified in its package.py file). e.g., the core addon's name is core, as shown here.

   mkdir addons/core

2. Navigate to the addon directory.

   cd addons/core

3. Clone the addon repository into a development directory. While you can name this directory anything you like, we will use dev in this guide.

   git clone https://github.com/ynput/ayon-core dev

4. Restart your AYON Server from the web UI or by using docker compose restart in the terminal.

5. In your bundle, you will see the development addon version with the +git suffix.

   

Your addon's directory structure should now look like this:

addons/
   └── core/
        └── dev/
             └── the addon repository contents.

For additional information about development mode, please see the AYON development mode documentation.

Storage Directory

This folder contains uploads to your AYON server, such as AYON Launcher installers, dependency packages, avatar images, and project data.

The storage directory structure is as follows:

storage/
  ├── desktop
  |     ├── dependency_packages
  |     └── installers
  ├── server
  |     ├── avatars
  |     └── projects
  └── static

FAQ

How to use pgAdmin?

pgAdmin is a graphical user interface (GUI) tool that allows you to access the AYON database directly, as an alternative to using the dbshell in the terminal.

To use pgAdmin, you must expose the PostgreSQL port of the postgres container. Add the following code snippet below this line in the docker-compose.yml file:

    ports:
      - 5432:5432

Then, rebuild your Docker containers using the docker compose up -d --build command. After this, you will be able to set up the pgAdmin connection.

First, register a server.

Give your connection a name.

Set your connection details. The username and password are both ayon.

Once your connection is set up, you will be able to access the AYON database directly. From there, you can explore the available tables and practice PostgreSQL queries.

SELECT name FROM projects

How to view AYON Server Logs?

You can view the server logs on the web UI's Event Viewer page by using the v+v shortcut.
Alternatively, you can view the full logs from the terminal using the docker compose logs command.

cd <path to your ayon docker>
docker compose logs -t -n 1000 server

How to Back Up and Restore Projects?

You can back up and restore AYON projects using the command-line interface (CLI) from your AYON Docker directory. This process allows you to back up a project along with its settings overrides and server-side files, such as thumbnails.

This is accomplished by dumping and restoring the project's data and its associated server storage.

Backing Up a Project

1. Dump the project database. The resulting dump.<project_name>.sql file should be stored in your backup location.

   Example
   Windows
   Linux & Mac
   Copy
   cd <path to your ayon docker>
   ./manage.ps1 dump projectname=<project_name>

2. Back up the project's server storage by copying the contents of storage/server/projects/YourProjectName to your backup location.

Restoring a Project

1. Restore the project database using the backed-up SQL file.

   Example
   Windows
   Linux & Mac
   Copy
   cd <path to your ayon docker>
   ./manage.ps1 restore projectname=<project_name> <project_db_sql_file>

2. Restore the project's server storage by copying the contents of storage/server/projects/YourProjectName from your backup location.

How to perform full AYON Server backups?

To perform a full AYON server backup, you'll use the PostgreSQL command-line interface (CLI) within your AYON Docker environment. The process involves both backing up the database and copying the server's storage files.

Ful Back up

1. Dump the Database: Navigate to your AYON Docker directory and use the following command to dump the entire database into an SQL file. Replace <backup_file_name> with your desired backup file name.

   cd <path to your ayon docker>
   docker compose exec postgres pg_dump -U ayon > <backup_file_name>.sql

2. Backup Server Storage: Copy the contents of the storage/ and addons/ directories to your chosen backup location.

Full restore

1. Restore Server Storage: Copy the contents of the storage/ and addons/ directories from your backup location back to their original place.

2. Restore the Database: Use the backed-up SQL file to restore the database, then rebuild your AYON Docker containers to complete the process.

   cd <path to your ayon docker>
   docker compose exec -T postgres psql -U ayon ayon < <backup_file_name>.sql
   docker compose up -d --build

How to only backup and restore AYON Settings?

Right now, there isn't a dedicated tool for backing up and restoring just AYON settings. The only way to do this is by retrieving the settings via the AYON API and writing a custom script to save and version them as you see fit.

You can get the settings using the AYON REST API:

• Studio Settings: Use the get all settings operation to get a list of addons and their versions that you want to back up.

• Add-on Studio Overrides: For each addon, use get_raw_addon_studio_overrides to retrieve the studio-level overrides to the default settings.

• Add-on Project Overrides: For each add-on and project, use Get Raw Addon Project Overrides to get the project-specific overrides to the studio settings.

Alternatively, you can find the equivalent functions in the AYON Python API and use them instead.

How to Migrate Projects Between AYON Servers?

You can migrate projects between AYON servers by exporting a project backup or a full server backup from one server and then restoring that backup on another server.

For more information about the backup and restoration process, see:

• How to Back Up and Restore Projects?

• How to perform full AYON Server backups?

How to Monitor Resources Used by AYON Server

The docker stats command shows runtime metrics for the resources used by your Docker containers, allowing you to monitor the resources consumed by your AYON Docker containers.

CONTAINER ID   NAME                     CPU %     MEM USAGE / LIMIT     MEM %     NET I/O           BLOCK I/O        PIDS
d8459f570541   ayon-docker-server-1     0.15%     193.1MiB / 3.826GiB   4.93%     5.32MB / 261kB    71MB / 4.1kB     9
d31e2ed6e002   ayon-docker-postgres-1   0.00%     67.7MiB / 3.826GiB    1.73%     254kB / 5.31MB    61.9MB / 741kB   7
547ca9374432   ayon-docker-redis-1      0.29%     7.766MiB / 3.826GiB   0.20%     8.11kB / 5.03kB   21.6MB / 0B      7

How to display AYON Server Release Info

To display the AYON Server's release information, you can view the contents of the RELEASE file located inside the server image.

cd <path to your ayon docker>
docker compose exec server cat RELEASE