Skip to content
Browse files

Add initial quick start (#100)

* Add initial quick start

* Fix formatting
  • Loading branch information...
sharifsalah committed Sep 20, 2019
1 parent a51fd4f commit 5390a0b7375d454aaf90524a45ba5c8da3c3e96a
@@ -1,7 +1,7 @@
title: "Concepts"
linkTitle: "Concepts"
weight: 1
weight: 2
description: >
Conceptual guides for all users to introduce OpenCue
@@ -1,8 +1,7 @@

title: "OpenCue getting started guide"
linkTitle: "Getting started"
weight: 2
weight: 3
date: 2019-02-22
description: >
Guides for system admins deploying OpenCue components and installing dependencies
@@ -1,8 +1,7 @@

title: "Other guides"
linkTitle: "Other guides"
weight: 4
weight: 5
date: 2019-02-22
description: >
Guides for system admins and technical directors completing common tasks related to managing, supporting, and troubleshooting OpenCue
@@ -0,0 +1,7 @@
title: "Quick starts"
linkTitle: "Quick starts"
weight: 1
description: >
Try OpenCue in the sandbox environment on different operating systems
@@ -0,0 +1,217 @@
title: "Quick start for macOS"
linkTitle: "Quick start for macOS"
weight: 1
date: 2019-09-04
description: >
Try OpenCue in the sandbox environment on macOS

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:

* Python version 2.7 or greater
* The Python [`pip` command](
* The Python [virtualenv tool](
* [Docker](
* [Docker Compose](

{{% alert title="Note" color="info"%}}Docker compose is included in the
desktop installation of Docker on macOS.{{% /alert %}}

You must allocate a minimum of 6 GB of memory to Docker. To learn
how to update the memory limit on macOS, see
[Get started with Docker Desktop for Mac](

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](

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

git clone

## Deploying the OpenCue sandbox environment

You deploy the sandbox environment using
[Docker Compose]([]), which runs the
following containers:

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

{{% alert title="Note" color="info"%}}In a production OpenCue deployment,
you might run many hundreds of RQD rendering servers.{{% /alert %}}

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. Start the Terminal app.

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

cd OpenCue

2. To deploy the OpenCue sandbox environment, export the `CUE_FRAME_LOG_DIR`
environment variable:

{{% alert title="Note" color="info"%}}You must export all environment
variables each time you start the sandbox.{{% /alert %}}

export CUE_FRAME_LOG_DIR=/tmp/rqd/logs

3. To specify a password for the database, export the `POSTGRES_PASSWORD`
environment variable:


4. 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
* 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
* `pycuerun` is a command-line client for submitting jobs to OpenCue.

To install the OpenCue client packages:

1. Open a second Terminal window.

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

cd OpenCue

1. Create a virtual environment for the Python packages:

virtualenv venv

2. Activate the `venv` virtual environment:

source venv/bin/activate

3. Install the Python dependencies and client packages in the `venv` virtual


## 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:

{{% alert title="Note" color="info"%}}You must export all environment
variables each time you start the client packages.{{% /alert %}}

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:

{{% alert title="Note" color="info"%}}The OpenCue sandbox environment
doesn't include any rendering software. To experiment with the user
interface, you can execute simple command-line scripts.{{% /alert %}}

cuesubmit &

5. Launch the CueGUI app for monitoring jobs:

cuegui &

## 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?

* Learn more about [OpenCue concepts and terminology](/docs/concepts/).
* Install the full [OpenCue infrastructure](/docs/getting-started/).
@@ -1,7 +1,7 @@
title: "Reference"
linkTitle: "Reference"
weight: 5
weight: 6
description: >
Reference guides for all users running OpenCue tools and interfaces
@@ -1,8 +1,7 @@

title: "User guides"
linkTitle: "User guides"
weight: 3
weight: 4
date: 2019-02-22
description: >
Guides for artists and wranglers completing common OpenCue user tasks

0 comments on commit 5390a0b

Please sign in to comment.
You can’t perform that action at this time.