Quick start for Linux

Try OpenCue in the sandbox environment on Linux

OpenCue is an open source render management system. You can use OpenCue in visual effects and animation production to break down complex jobs into individual tasks. You can submit jobs to a queue that allocates rendering resources. You can also monitor rendering jobs from your workstation.

The sandbox environment provides a way to quickly start a test OpenCue deployment. You can use the test deployment to run small tests or for development work. The sandbox environment runs OpenCue components in separate Docker containers on your local machine.

This quick start takes approximately 20 minutes to complete.

Before you begin

You must have the following software installed on your machine:

If you don’t already have a recent local copy of the OpenCue source code, you must do one of the following:

  1. Download and unzip the OpenCue source code ZIP file.

  2. If you have the git command installed on your machine, you can clone the repository:

    git clone https://github.com/AcademySoftwareFoundation/OpenCue.git

Deploying the OpenCue sandbox environment

You deploy the sandbox environment using Docker Compose, which downloads and runs the images of the following containers from Docker Hub:

  • a PostgresSQL database
  • a Cuebot server
  • an RQD rendering server

Docker Compose downloads images of Cuebot and RQD corresponding to the latest release of OpenCue.

The Docker Compose deployment process also configures the database and applies any database migrations. The deployment process creates a db-data directory in the sandbox directory. The db-data directory is mounted as a volume in the PostgresSQL database container and stores the contents of the database. If you stop your database container, all data is preserved as long as you don’t remove this directory. If you need to start from scratch with a fresh database, remove the contents of this directory and restart the containers with the docker-compose command.

To deploy the OpenCue sandbox environment:

  1. Open a Terminal window.

  2. If you haven’t already, add your user account to the docker group:

    sudo gpasswd -a $USER docker
  3. Docker Compose mounts volumes for the RQD rendering server on the host operating system under /tmp/rqd/logs and /tmp/rqd/shots. RQD saves logs to the logs directory. You specify the shots directory to save RQD output when creating OpenCue jobs.

    To create the mount points with the required permissions, run the following command:

    mkdir -p /tmp/rqd/logs /tmp/rqd/shots
  4. Change to the root of the OpenCue source code directory:

    cd OpenCue
  5. To deploy the OpenCue sandbox environment, export the CUE_FRAME_LOG_DIR environment variable:

    export CUE_FRAME_LOG_DIR=/tmp/rqd/logs
  6. To specify a password for the database, export the POSTGRES_PASSWORD environment variable:

  7. Build the RQD container from source:

    docker build -t opencue/rqd -f rqd/Dockerfile .
  8. To deploy the sandbox environment, run the docker-compose command:

    docker-compose --project-directory . -f sandbox/docker-compose.yml up

    The command produces a lot of output. When the setup process completes, you see output similar to the following example:

    rqd_1     | 2019-09-03 16:56:09,906 WARNING   rqd3-__main__   RQD Starting Up
    rqd_1     | 2019-09-03 16:56:10,395 WARNING   rqd3-rqcore     RQD Started
    cuebot_1  | 2019-09-03 16:56:10,405 WARN pool-1-thread-1 com.imageworks.spcue.dispatcher.HostReportHandler - Unable
     to find host,org.springframework.dao.EmptyResultDataAccessException: Failed to find host , c
    reating host.

Leave this shell running in the background.

Installing the OpenCue client packages

OpenCue includes the following client packages to help you submit, monitor, and manage rendering jobs:

  • PyCue is the OpenCue Python API. OpenCue client-side Python tools, such as CueGUI and cueadmin, all use PyCue for communicating with your OpenCue deployment.
  • PyOutline is a Python library that provides a Python interface to the job specification XML. You can use PyOutline to construct complex jobs with Python code instead of working directly with XML.
  • CueSubmit is a graphical user interface for configuring and launching rendering jobs to an OpenCue deployment.
  • CueGUI is a graphical user interface you run to monitor and manage jobs, layers, and frames.
  • cueadmin is the OpenCue command-line client for administering an OpenCue deployment.
  • pycuerun is a command-line client for submitting jobs to OpenCue.

To install the OpenCue client packages:

  1. Open a second Terminal window.

  2. Change to the root of the OpenCue source code directory:

    cd OpenCue
  3. Create a virtual environment for the Python packages:

    virtualenv venv
  4. Activate the venv virtual environment:

    source venv/bin/activate
  5. To install the lastest versions of the OpenCue client packages, you must configure the installation script with the version number. You can look up the version numbers for OpenCue releases on GitHub.

    export VERSION=0.2.65
  6. Install the Python dependencies and client packages in the venv virtual environment:


Testing the sandbox environment

To connect to the sandbox environment, you must first configure your local client packages to:

  • Locate the outline.cfg PyOutline configuration file included in the OpenCue Git repository.
  • Locate the Cuebot server running in a Docker container on your machine.

To test the sandbox environment, run the following commands from the second Terminal window:

  1. Set the location of the PyOutline configuration file:

    export OL_CONFIG=pyoutline/etc/outline.cfg
  2. The Cuebot docker container is forwarding the gRPC ports to your localhost, so you can connect to it as localhost:

    export CUEBOT_HOSTS=localhost
  3. To verify the successful installation of the sandbox environment, as well as the connection between the client packages and sandbox, you can run the cueadmin command-line tool. To list the hosts in the sandbox environment, run the following cueadmin command:

    cueadmin -lh

    The command produces output similar to the following:

    Host            Load NIMBY freeMem  freeSwap freeMcp   Cores Mem   Idle             Os       Uptime   State  Locked    Alloc      Thread      52   False 24.2G    0K       183.1G    2.0   25.5G [ 2.00 / 25.5G ] Linux    00:04    UP     OPEN      local.general AUTO
  4. Launch the CueSubmit app for submitting jobs:

    cuesubmit &

    The following screenshot illustrates the layout of CueSubmit as a standalone app:

    The default CueSubmit window

  5. By default, the OpenCue sandbox environment doesn’t include any rendering software. To experiment with the user interface, you can execute simple command-line shell scripts.

    To execute a command-line shell script:

    • For Job Name, type HelloWorld.
    • For User Name, type test-user.
    • For Shot, type test-shot.
    • For Layer Name, type test-layer.
    • For Command To Run, type the following command:
    echo "Output from frame: #IFRAME#; layer: #LAYER#; job: #JOB#"
    • For Frame Spec, type 1-10.

    This job consists of 10 frames, which each run a simple echo command. For each frame, the echo command prints the frame number, layer name, and job name using replacement tokens such as #IFRAME# and #JOB#.

  6. To submit the job to OpenCue, click Submit.

  7. Launch the CueGUI Cuetopia app for monitoring jobs:

    cuegui &

    The following screenshot illustrates the layout of CueGUI Cuetopia monitoring app:

    The default CueGUI Cuetopia window

  8. Click Load.

    CueGUI displays the job name testing-test-shot-test-user_helloworld in the list of jobs.

  9. Double-click the job name.

    CueGUI displays the list of frames in the job.

  10. After OpenCue marks the status of a frame as SUCCEEDED, click the corresponding row in the list of frames.

  11. In the LogView view, review the log output for the job to verify the frame produced output similar to the following:

    Output from frame: 9; layer: test_layer; job: testing-test-shot-test-user_helloworld

Stopping and deleting the sandbox environment

To delete the resources you created in this guide, run the following commands from the second shell:

  1. To stop the sandbox environment, run the following command:

    docker-compose --project-directory . -f sandbox/docker-compose.yml stop
  2. To free up storage space, delete the containers:

    docker-compose --project-directory . -f sandbox/docker-compose.yml rm
  3. To delete the virtual environment for the Python client packages:

    rm -rf venv

What’s next?

Last modified Wednesday, March 18, 2020: Fixes Error : 404 Page not found (#163) (e02cd29)