Cloud Zeta

This is the main repo for Cloud Zeta, a cloud platform for creators to manage 3D assets, collaborate on projects, and deliver content from anywhere.

Developer environment

• Dev container on Windows (WSL) or Linux
• It is recommended to use VS Code for easy ramp up. CLion or Visual Studio may also work, but you will be on your own to setup dev environment.

Install WSL2

https://learn.microsoft.com/en-us/windows/wsl/install

Make sure to have git lfs installed

Some of our dependencies need it.

sudo apt-get install git-lfs

For macOS

brew install git-lfs

Cloning the repository in WSL2

git clone --recurse-submodules git@github.com:cloud-zeta/zeta.git

When updating existing repository, don't forget to update all submodules:

git pull
git submodule update --recursive

Install Docker

Before you begin, ensure Docker is installed. The recommended setup is to run Docker Desktop on Windows and use WSL2 as the backend. This allows developers to use the same setup on both Windows and Linux.

If you use CLion, check out the Docker toolchain documentation.

VS Code setup

Install VS Code

NOTE Do not install VS Code in WSL using apt-get. Instead, follow the VS Code WSL Tutorial.

Once done, code command in WSL will open the VS Code in Windows.

Open project folder with VS Code

code .

Open DevContainer

We use DevContainer for the development. When you open the VS Code workspace for the first time, VS Code will automatically prompt you to Re-open in the container. VS Code will build the container and setup the environment for you.

The first time running this will take some time.

See Developing inside a Container for more context about DevContainers.

Build and run Cloud Zeta web app (Basic)

Run the following command in the VS Code terminal (inside the DevContainer)

./scripts/build_usd.sh
./scripts/build.sh
./devops/run/web_app.sh
./devops/run/web_server.sh

Once everything is done, open http://localhost:8080 in any brower avaialble to your Windows. VS Code already sets up all the necessary port forwarding.

Use the beta Supabase backend

Set the TARGET_DEPLOYMENT environment variable to zeta to use the Supabase database in beta. This points to the beta database with https://beta.zetabase.ai.

TARGET_DEPLOYMENT=zeta ./devops/run/web_server.sh
TARGET_DEPLOYMENT=zeta ./devops/run/web_app.sh

INFO

You can also visit the beta instance directly at beta.zetabase.ai. And supabase admin console at studio.beta.zetabase.ai. Take a look at the .env file for the credentials for the admin console.

Use the locally Supabase backend

Start the local Kubernetes cluster and deploy the Postgres and Supabase services.

minikube start --cpus 8 --memory 4096 --disk-size 20g --driver=docker --network=zeta_default --network-plugin=cni --cni=cilium
minikube addons enable storage-provisioner
minikube addons enable default-storageclass

TARGET_DEPLOYMENT=local ./devops/deploy/postgres.sh
TARGET_DEPLOYMENT=local ./devops/deploy/supabase.sh

Then run the Zeta containers, similar to the previous section, but with TARGET_DEPLOYMENT=local.

TARGET_DEPLOYMENT=local ./devops/run/web_server.sh
TARGET_DEPLOYMENT=local ./devops/run/web_app.sh

Useful VS Code tasks

Check out tasks.json for available targets. See VS Code Tasks to learn more.

Tasks	Description
build-usd-wasm-release	Release build for OpenUSD for Emscripten
build-usd-linux-debug	Debug build for OpenUSD for Linux
run-tests-linux	Run native tests for Linux
build-usd-viewer-linux	Build Hydrogent USD Viewer for Linux
run-usd-viewer-linux	Run Hydrogent USD Viewer for Linux

NOTE Cloud Zeta's DevContainer has been confitured to run Linux GUI programs. The GUI is available in a VNC server available at http://localhost:6080. If you don't know the password, ask around.

NOTE Make sure to use the corresponding cmake-kits for different Emscripten and Linux tasks.

Run Python server code

We use Google Cloud Run to host backend services. The code is available at src/python.

To run the full web server, run the following steps:

Step 1: Build OpenUSD for Linux

./scripts/build_usd.sh -t linux -v release

Alternatively, you can use the build-usd-linux-release VS Code task.

Step 2: Build OpenUSD

./scripts/build_zeta_native.sh

Alternatively, you can also build with VS Code by select the Clang kit. See cmake-kits for more detauls.

Step 3: Run the Web Server

./devops/run/web_server.sh

This script will build the container for the web server and execute it.

NOTE The flask app requires GOOGLE_APPLICATION_CREDENTIALS points to a valid Google Cloud secret. Currently, we don't have a dev or staging environment.

To debug individual Python scripts or run test without Google Cloud dependencies, you need to create pip virtual environment.

cd src/python
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

python zeta/importer/usdz.py

Step 4 (optional): Attach Python Debugger to Web Server

• When running in debug mode, flask app will listen on port 5678 for debugger.
• Run docker -ps to get the id of the zeta-flask container.
• Run docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' <zeta-flask-id> to get the ip of the running container and set it in the launch.json file.
• Run the (debugpy) attach to web server debug option.

Non VS Code setup

NOTE This path is maintain for the CI/CD pipeline. Not recommended for day-to-day development.

Build with Docker

Simply run the following command to build Cloud Zeta with Docker:

./docker_build.sh

The script will build the Docker image and run the build inside the container. The build artifacts will available in the ./build directory.

To build the image or Cloud Zeta project manually, inspect the content of docker_build.sh, build.sh and Dockerfile.

By default, the build script will build the release build, for debug build, run the following command:

./docker_build.sh -e debug

Run Cloud Zeta web app

./docker_run.sh

The script will run the Cloud Zeta web app inside the container, it will automatically reload the app when

1. The Javascript source code changes.
2. After each ./docker_build.sh command.

WASM test server

Build

cmake --build /code/zeta/build-Emscripten-Release --config Release --target install --

The test server has no cloud dependencies, just run:

./scripts/run_test_server.sh

Visit tests at http://localhost:8082/tests/.