Guide | Deployment

Once you're ready to deploy your Compose Apps, you'll need to create a production environment from the home page. This generates a new production API key that should be used for the deployment.

What are environments?

Like most software, Compose Apps exist within one of two environments: Development and Production.

Production is for live apps to be shared with your whole organization, while Development is designed for engineers to rapidly develop apps in a local environment. Every engineer is automatically assigned a personal development environment and API key for connecting to it.

Deployment Options

Compose is designed to be run on your own infrastructure - we can't see your code or secrets by design.

You're able host Compose however you want. The only requirement is that your environment is able to maintain an internet connection so that it can connect to our servers.

Shared Deployment

The easiest way to deploy Compose is as a dependency inside your existing server environment. Compose runs safely in the background via a secure websocket connection to the Compose servers.

This approach enables you to leverage your existing deployment tooling and infrastructure and avoid standing up a separate service.

TypeScript / JavaScript

// Example Express app

import { Compose } from "@composehq/sdk";
import express from "express";

const server = express();

server.get("*", (req, res) => {
    res.send("Hello World");
});

const helloWorldApp = new Compose.App({
    route: "hello-world",
    handler: async ({ page, ui }) => {
        page.add(() => ui.text("Hello World"));
    }
})

const client = new Compose.Client({
    apiKey: process.env.COMPOSE_API_KEY,
    apps: [helloWorldApp],
});

// Compose will run safely in the background, while your server handles regular traffic.
client.connect();

server.listen(process.env.PORT || "3000");

Python

# Example Flask app

import compose_sdk as c
from flask import Flask
import os

client = c.Client(
    api_key=os.environ.get("COMPOSE_API_KEY"),
    apps=[...],
)

# Compose will run safely in a separate thread, while your server handles regular traffic.
if os.environ.get("WERKZEUG_RUN_MAIN") == "true":
    client.connect_async()

server = Flask(__name__)

@server.route("/")
def say_hello():
    return "<p>Hello, World!</p>"

def main(page: c.Page, ui: c.UI):
    page.add(lambda: ui.text("Hello world!"))

Separate Deployment

Many users choose to run a dedicated Compose instance alongside their server. Deploy an additional instance of your server that does not serve regular traffic, but instead only exists to run Compose.

This is useful if you want to isolate your Compose runtime from your server or deploy updates to your Compose Apps without redeploying your entire server, while still having access to your full codebase.

TypeScript / JavaScript

import { Compose } from "@composehq/sdk";
import express from "express";

const server = express();

server.get("*", (req, res) => {
    res.send("Hello World");
});

const client = new Compose.Client({
    apiKey: process.env.COMPOSE_API_KEY,
    apps: [...],
});

const deploymentType: "server" | "compose" = process.env.DEPLOYMENT_TYPE || "server";

if (deploymentType === "compose") {
    client.connect();
} else {
    server.listen(process.env.PORT || "3000");
}

Python

# Example Flask app

import compose_sdk as c
from flask import Flask
import os

client = c.Client(
    api_key=os.environ.get("COMPOSE_API_KEY"),
    apps=[...],
)

deployment_type: "server" | "compose" = os.environ.get("DEPLOYMENT_TYPE")

if deployment_type == "compose":
    client.connect()

server = Flask(__name__)

@server.route("/")
def say_hello():
    return "<p>Hello, World!</p>"

def main(page: c.Page, ui: c.UI):
    page.add(lambda: ui.text("Hello world!"))

info

For a dedicated Compose deployment, you should use client.connect() instead of client.connect_async().

• connect() is a blocking call that runs Compose in the main thread. Use this when deploying a dedicated Compose instance.
• connect_async() is a non-blocking call that runs Compose in a separate thread. Use this when embedding Compose inside an existing server environment.

Dedicated Compose deployments can run as a "background service", meaning they only need to support outbound internet access.

Looking for help with deploying? We'd be happy to help! Just email atul@composehq.com or message us in our Discord.

System Requirements

Compose is designed to be lightweight and efficient, and is fine to run on entry-level hardware for most use-cases (e.g. the cheapest available virtual machine on AWS).

• CPU: CPU requirements are generally minimal and not a bottleneck for most applications.
• Memory: For best results, we recommend 512MB of RAM or more, though usage generally remains far below this limit. For very data-intensive applications (e.g. rendering large PDFs or tables with tens of thousands of rows) with many simultaneous users, you may need to increase the amount of memory allocated. As always, you should monitor your server's performance and scale up resources as needed.
• Location: Compose's servers are hosted in Salt Lake City, Utah. To minimize latency, we recommend you deploy your own server that will run the SDK as close to this location as possible. Though in general, deploying anywhere in the US will be fine.

Notes

If you have multiple servers that try to connect to the same Compose environment, Compose will choose one at random and disregard any others. This is because Compose apps are stateful, i.e. they maintain the same server process for the lifetime of the app.