General overview
Morpheus is made up of a set of services that communicate with each other in order to generate images using AI. It was designed to be used locally on a server and deployed in a cloud cluster to scale the service. In addition, it contains the necessary IaC tools to create the infrastructure required for scaling. Also, whether at the local server or cluster level, Morpheus uses ray.io to handle scaling, high demand, and resource optimization in image generation.
We will look at each of these features in more detail below.
Morpheus is made up of a set of microservices:
- morpheus-client. It's a FrontEnd client created with NextJS. It is the interface with which the user can interact and use all the features of morpheus.
- morpheus-server. It's the API created with fastAPI
- morpheus-collaborative. It's a websocket server of the Excalidraw app
- morpheus-worker. It's the ray.io integration to process and generate images with AI. Internally this service consists of a ray server that redirects the tasks to the respective ray actors.
- morpheus-data. It's a library to handle all related data in morpheus such as S3/ bucket integrations, and database repositories. This is very useful because this library could be used crosswise for all other morpheus services.
- morpheus-admin. It's to manage all models used in Morpheus. It allows you to create, update, remove and, activate/deactivate AI models for generating images, prompts, manipulate, and process images for ControlNet.
There is also an additional component that does not appear in the diagram, which we could call morpheus-admin-cli. This is because it can be considered morpheus-admin console version. This CLI allows the same operations as morpheus-admin but from a console. Like admin, the CLI requires morpheus-server to be running as it uses the API for database interactions. Although the CLI is a separate service in docker-compose(called model-script), the code for this service is contained within morpheus-server/scripts/models.
Morpheus can currently be run in two ways:
- On a server. You can run morpheus on your local computer or on a remote server with an available GPU. This makes use of docker compose, which launches the various morpheus services. This is useful for test environments.
- On a cluster in the cloud. You can run morpheus on a Kubernetes cluster using Helm. Currently using AWS but can be adapted to any other provider. This form is useful for production environments where you need high availability, and scalability, and to support high demand.
Therefore, Morpheus offers you the possibility to run it on your own computer or server, as well as using a cluster if you want to scale it up.
It should be noted that due to the nature of each environment, there are certain processes that run differently:
- In a cluster, models are stored in an S3 that is synchronized with the cluster storage. On a server, models are stored on a docker volume.
- To update the service images, you can do it with docker compose build or docker build. However, for cluster deployment, you need those images to be stored in a repository. In our case, we use dockerhub as the image repository. If you are running morpheus on a server, you can also use the remote repository, but usually, the images are stored in the docker's local repository.
- To deploy changes on the server, it is not always required to create a new image as the services use a bind mount in docker compose. In the case of a cluster, it is required to create new images to run the new containers with the changes.
It should be noted that, regardless of whether Morpheus is running on a server or a cluster, both will need an S3 bucket to store the image results. This is set by default, but you can easily integrate another way of storing the results.
Morpheus also offers a set of terraform templates for deploying and managing infrastructure on AWS.
Additionally, we have defined Morpheus as a monorepo as it is composed of several interrelated services. Because of this, we have created our own scripts and actions that function as a build system for the monorepo.
When a developer creates a Pull Request and pushes changes over that branch, the monorepo build system checks the files changed in the last commit to trigger the respective Github Action according to the morpheus service changed, and therefore it checks only that service. For example, if a PR only contains changes made to morpheus-client, GitHub will only run the actions related to the client. Additionally, in a PR, only the CI pipelines will executed.
When a PR is merged to the main branch, the monorepo build system will trigger only the respective actions related to the service changes and execute the CI and CD pipelines. In the CD pipeline, the actions build and push the new images to the container registry service (Dockerhub in our case) and using helm commands, deploy new changes in the cluster or production environment.
If you want to see more in detail how our build system for monorepo works, you can read this blog post
The following diagram illustrates the process of generating an image in Morpheus using AI models.
Basically, from the frontend/client the user selects an AI model, writes the prompt, and sets additional parameters. Then the user sends the request to the morpheus-server to generate the image and is notified that his request is being processed. After a few seconds, he receives the AI-generated image. Keep in mind that image generation using AI is an exhaustive task that requires GPU usage, so it takes time for the machine to generate a result. Depending on the type or family of GPUs used, the generation may take more or less time.
Internally morpheus-server receives the request, and does some validation and preprocessing to send the task to morpheus-worker. This responds with a task_id with which the client will be monitoring the status of the task until it gets the result.
The morpheus-worker component is a service that uses the ray.io framework to process and scale image generation workloads. It consists of a ray server that uses fastAPI to expose ray services and a ray-worker that consists of a set of Ray Actors that are responsible for processing the workloads.
In this component, ray serve receives the request from morpheus-server, performs preprocessing operations to send the data to the worker, and creates a task_id. With that task_id it registers the task in a database and sends the task to the worker, which is processed asynchronously. In the Worker, where the Actor is defined, it is processed and the image is generated. Once the task is ready, the image is uploaded to the S3 bucket, and the status of the task and the URL of the image in the S3 is updated in the database so that the client can obtain the result and display the result.