Connect Orientation

How Posit Connect runs your code

You can use Connect to host dashboards, reports, notebooks, applications, APIs, or scripts. These types of content often require a Python or R process to react to a user input from the browser, produce a table of statistics, or trigger some work to be performed on another system. Connect is the engine responsible for managing when that code execution takes place based on the type of content you deploy.

Posit Connect has three execution modes:

Execution mode	Connect actions	User experience	Example content types
Interactive	Connect starts a process when a user visits your application and shuts it down when they finish.	Users interact with your content, causing computation (code execution) to occur on the server.	Streamlit, Shiny, FastAPI
Non-interactive (batch)	Connect runs your code without user input. No process is running when a user visits your content.	Users view results which were executed by Connect before they arrived. Any interactivity is provided by the browser.	Quarto, Jupyter, R Markdown
Static hosting (no execution)	Connect serves your content but does not execute code.	Users view results which were executed before publication to Connect. Any interactivity is provided by the browser.	Pins, Shinylive, React

The execution mode determines what tools Connect provides to help you manage and distribute your content.

Interactive code execution

sequenceDiagram
    accTitle: Interactive code execution on Posit Connect
    accDescr {
        A publisher deploys an interactive app to Connect.
        Connect starts the app when a viewer visits and shuts the app down after their session concludes.
    }
    participant publisher
    participant connect as Posit Connect
    
    publisher->>connect: deploy /interactive-app
    
    create participant app as /interactive-app
    connect->>+app: start /interactive-app

    create participant viewer
    app<<->>viewer: twiddle and recalculate

    destroy viewer
    viewer-->>app: end session

    app-->>connect: no more viewers

    destroy app
    connect->>app: shutdown

box server
participant connect
participant app
end

A sequence diagram of the process of interactive code execution.

In this mode, Posit Connect runs a Python or R process because you’ve chosen a type of interactivity that requires server-side code execution. Examples of content types in this category include applications (e.g., Streamlit, Shiny for Python, Shiny for R, Dash, and Gradio), APIs (e.g., Plumber, FastAPI, Flask), and interactive documents (e.g., Voilà, Shiny R Markdown).

When a user visits your application hosted on Connect, their browser connects to a running Python or R process on the server. When that user changes an input, the browser sends a message to the server, which runs your app code and returns the result. With APIs, server-side code execution is typically initiated by a process running on a server separate from Connect, rather than by a human controlling a browser.

Not all content with user interactivity requires server-side code execution. Frameworks like Observable and htmlwidgets can provide interactivity using JavaScript that executes in the viewer’s browser. Jupyter Widgets are another popular framework in this category; however they are currently only supported in Connect through the ipywidgets package and Voilà, which runs in interactive mode.

Scalable execution

Posit Connect manages the processes used for interactive execution to meet the demands of your users. Connect provides sensible defaults for controlling processes and resource utilization which you can alter to ensure your applications, APIs, and interactive documents remain responsive and performant as they are accessed by more users. Here are some considerations for scaling and tuning in Connect:

Handle more users efficiently

As user demand grows, an individual R or Python process may not be able to serve all user requests in a timely manner. Connect allows you to set a limit on the number of simultaneous connections each process should handle.

Customize by workload

Different types of content will have different computational needs. A dashboard that primarily summarizes a small amount of data might be well-served by Connect’s default scaling behavior. By contrast, an application that performs complex simulations may want to be more proactive about spawning additional processes.

Keep a process ready and waiting

By default, Connect spins up a new R or Python process only when a user connects. This is desirable because it frees up those resources for other work, but users may experience delays as a process starts. For public-facing or frequently accessed apps, keeping a process alive between users helps reduces the need to reload or recompute everything on each connection. Persistent processes can be especially beneficial for applications that maintain in-memory state across sessions, like cached data or model objects.

All the scaling and tuning options for interactive execution are documented in the Runtime section of this guide.

Non-interactive code execution

sequenceDiagram
    accTitle: Non-interactive code execution on Posit Connect
    accDescr {
        A publisher deploys a document to Connect.
        Connect executes the document, saves the results, and then serves
        the results to viewers when they visit the document.
    }
    participant publisher
    participant connect as Posit Connect
    
    publisher->>connect: deploy /rendered
    
    create participant app as /rendered
    connect->>+app: serve /rendered

    create participant viewer
    app->>viewer: browse

    destroy viewer
    viewer-->>app: end session

    box server
    participant connect
    participant app
    end

A sequence diagram of the process of non-interactive code execution.

In this mode, Posit Connect runs your code start to finish without user input during execution. Connect hosts the output of that execution event (usually HTML) and enables you to share it. Content types in this category include Python and R scripts, notebooks, and dashboards without interactive runtime requirements (e.g., Quarto, R Markdown, Jupyter Notebooks).

Any user interactivity must be achieved through client-side methods. Frameworks like Observable and htmlwidgets provide client-side interactivity using JavaScript that executes in the viewer’s browser. In cases like this, content will appear interactive to the viewer, but Posit Connect is not running an R or Python process that responds to user input. Note: Jupyter Widgets are currently only supported in interactive mode.

Note

If you’re ever in doubt about whether a content item you own falls into the non-interactive code execution category, check whether it can be executed (rendered) on a schedule by navigating to the Schedule tab in the Content Settings pane. Scheduling is a feature that applies exclusively to this execution mode.

Scheduled execution

sequenceDiagram
    accTitle: Scheduled non-interactive code execution on Posit Connect
    accDescr {
        A publisher deploys a document to Connect.
        Connect executes the document, saves the results, and then serves
        the results to viewers when they visit the document.
        On a schedule, Connect executes the document, updates the results,
        and serves the newest version to viewers.
    }
    participant publisher
    participant connect as Posit Connect
    
    publisher->>connect: deploy /rendered
    
    create participant app as /rendered
    connect->>+app: serve /rendered

    create participant viewer
    app->>viewer: browse

    destroy viewer
    viewer-->>app: end session

    connect ->> connect: scheduled render
    connect ->> app: update document

    create participant v2 as viewer
    app ->> v2: browse
    destroy v2
    v2 ->> app: end session

    box server
    participant connect
    participant app
    end

A sequence diagram of the process of scheduled non-interactive code execution.

All content that runs in non-interactive mode can be executed on-demand or (optionally) on a schedule. You can view the History of previous ad hoc and scheduled executions of content.

Programmatic execution

To trigger execution programmatically (e.g., from an external ETL process or tool), take a look at the Cookbook examples for rendering content.

Post-execution events

Content of this type can be configured to send email to a distribution list following an execution event. Email functionality requires configuration by your Connect server administrator. See the Admin Guide for additional details.

Static hosting

sequenceDiagram
    accTitle: Static content hosting on Posit Connect
    accDescr {
        A publisher renders a document in their environment
        and publishes the output to Connect.
        Connect serves the output when it is visited.
    }
    participant publisher
    
    create participant static
    publisher ->> static: render static

    create participant connect
    

    destroy static
    static->>connect: publish static

    create participant s2 as static
    connect ->> s2: serve /static

    create participant viewer
    s2 ->> viewer: browse

    destroy viewer
    viewer ->> s2: end session

    box server
    participant connect
    participant s2
    end

A sequence diagram of the static hosting process.

In this mode, Posit Connect functions as a web server for static files. Content types in this category include:

Static sites
Pins
Content (e.g., Quarto, R Markdown, and Jupyter Notebooks) that has been rendered into HTML or other output files
Single-page app frameworks where no server execution is required