Docker

Some organizations are starting to deploy Posit Connect within a Docker container. In Connect’s native execution mode, the Connect server manages and runs your processes within that container. If you are using Connect’s off-host execution features, content processes are started in isolated Pods on Kubernetes, external to the server container. This section describes the requirements for a container-based deployment.

Off-Host Execution

To get started with Posit Connect’s off-host execution feature, see the Getting Started documentation.

If you are using multiple Docker containers to run Posit Connect, the High Availability and Load Balancing section contains requirements for a load-balanced, multi-host configuration.

Please contact your Customer Success representative for guidance deploying Posit Connect into your particular environment.

Distributions

Posit Connect is supported on the Linux distributions given in the System Requirements section. Docker-based deployments need to use one of these operating systems.

R

R version 3.1.0 or higher must be installed within your Docker container. We recommend installing a curated set of R versions rather than using R installed by a package manager. Use the R installation instructions from the R Installation section when building your Docker image.

Python

To support Python content deployment on Posit Connect, Python version 3.7 or higher must be installed within your Docker container. We recommend installing a curated set of Python versions rather than using Python installed by a package manager. Use the Python installation instructions from the Python Installation section when building your Docker image.

Quarto

To support Quarto content deployment on Posit Connect, Quarto must be installed within your Docker container. Use Posit’s Quarto Installation instructions when building your Docker image.

Privileged containers

Off-Host Execution

This section about privileged containers only applies to the “native” execution mode of Posit Connect, which requires privileged containers.

If you are running Posit Connect with off-host Kubernetes execution, the Posit Connect container does not need to be run as privileged or with the CAP_SYS_ADMIN capability. When using off-host Kubernetes execution, isolation between content items is handled using separate containers and Kubernetes VolumeMounts. See the Architecture Overview appendix for additional details.

Posit Connect runs processes within an environment constructed using unshare(2). Within this environment, a mount namespace (CLONE_NEWNS) and a user namespace (CLONE_NEWUSER) are created to partially isolate user processes.

Details about the environment used to run user processes is described in the Sandboxing section.

Construction of the mount namespace, its bind mounts, and the user namespace is not possible within an unprivileged container. In order for Connect to construct its process sandbox, the CAP_SYS_ADMIN capability is required.

The Docker container running Posit Connect must be started with either --cap-add=CAP_SYS_ADMIN or --privileged=true.

Licensing

We recommend using a floating license server and having Posit Connect use that license server. The Floating Licenses section explains how to obtain and configure the license server as associating Posit Connect with the floating license server.

Note

We recommend using docker stop rather than docker kill to terminate your Posit Connect Docker containers. Using docker stop allows floating license leases to be gracefully released. License leases not returned to the license server need to wait for lease expiration before they can be reused.

Please contact your Customer Success representative if your organization is unable to run a persistent floating license server.

Storage

Mount a persistent storage location into the Docker container and configure that location as your Server.DataDir. Do not mount this to the default /var/lib/rstudio-connect location. See the Variable Data section for more information about the data managed by Posit Connect.

Database

The default SQLite database provider may be used when Posit Connect runs inside a single Docker container and your Server.DataDir is a mounted volume that is not part of a networked (NFS) share.

You must use PostgreSQL in all multiple-container deployments or if your persistent storage location is a networked location.

Examples

This section contains an rstudio-connect.gcfg configuration file and Dockerfile to help get you started building your own environment.

With the Dockerfile and rstudio-connect.gcfg files in a directory, you can build a Docker image tagged with rstudio/connect-docker:latest with the command:

docker build -t rstudio/connect-docker .

Once the image is built, it can be run with the command:

docker run -d --privileged=true --rm \
    -p :9999:3939 \
    -v $(pwd)/data:/data \
    rstudio/connect-docker:latest

This launches Posit Connect within a Docker container. The Connect instance is available on port :9999 (published from :3939 within the container). This sample mounts the ./data directory as our persistent storage and will need updating for your environment.

Configuration

This rstudio-connect.gcfg file is copied into the Docker image by a COPY command in the Dockerfile that follows. This file is only an initial configuration and requires customization for your organization.

; /etc/rstudio-connect/rstudio-connect.gcfg

; Posit Connect sample configuration
[Server]
; SenderEmail is an email address used by Posit Connect to send
; outbound email. The system will not be able to send administrative
; email until this setting is configured.
SenderEmail = account@company.com

; The public URL to this Posit Connect container. This might the
; address for a proxy or the host running the Docker container.
Address = https://posit-connect.company.com

; The persistent data directory mounted into our container.
DataDir = /data

[Licensing]
LicenseType = remote

; Use and configure our PostgreSQL database.
[Database]
Provider = postgres

[Postgres]
URL = "postgres://username:password@db.company.com/connect"

[HTTP]
; Posit Connect will listen on this network address for HTTP
; connections.
Listen = :3939

[Authentication]
; Specifies the type of user authentication.
Provider = password

Dockerfile

Here is a simple Dockerfile that can be used to run Posit Connect within an Ubuntu 22.04 (jammy) Docker container.

This environment installs a single R version using a DEB installer produced by the r-builds project. The R binaries produced by r-builds live in a version-specific directory beneath /opt/R/.

# Posit Connect sample Dockerfile
FROM ubuntu:jammy

# Install tools needed to obtain and install R and Posit Connect.
RUN export DEBIAN_FRONTEND=noninteractive && \
    apt-get update && \
    apt-get install -y curl gdebi-core && \
    rm -rf /var/lib/apt/lists/*

# Download and install R 3.6.3.
ARG R_VERSION="3.6.3"
ARG R_OS=ubuntu-2204
ARG R_PACKAGE=r-${R_VERSION}_1_amd64.deb
ARG R_PACKAGE_URL=https://cdn.posit.co/r/${R_OS}/pkgs/${R_PACKAGE}
RUN curl -fsSL -O ${R_PACKAGE_URL} && \
    export DEBIAN_FRONTEND=noninteractive && \
    apt-get update && \
    apt-get install -f -y ./${R_PACKAGE} && \
    rm ${R_PACKAGE} && \
    rm -rf /var/lib/apt/lists/*

# Download and install Posit Connect.
ARG CONNECT_VERSION=2023.07.0
ARG CONNECT_SHORT_VERSION=2023.07
ARG CONNECT_DISTRIBUTION=ubuntu22
ARG CONNECT_PACKAGE=rstudio-connect_${CONNECT_VERSION}~${CONNECT_DISTRIBUTION}_amd64.deb
ARG CONNECT_URL=https://cdn.posit.co/connect/${CONNECT_SHORT_VERSION}/${CONNECT_PACKAGE}
RUN curl -sL -o rstudio-connect.deb ${CONNECT_URL} && \
    apt-get update && \
    gdebi -n rstudio-connect.deb && \
    rm rstudio-connect.deb && \
    rm -rf /var/lib/apt/lists/*

# Copy our configuration over the default install configuration
COPY rstudio-connect.gcfg /etc/rstudio-connect/rstudio-connect.gcfg

# Use a remote license server issuing floating licenses
RUN /opt/rstudio-connect/bin/license-manager license-server licensing.company.com

# Expose the configured listen port.
EXPOSE 3939

# Launch Connect.
CMD ["--config", "/etc/rstudio-connect/rstudio-connect.gcfg"]
ENTRYPOINT ["/opt/rstudio-connect/bin/connect"]

This Dockerfile installs a single R version but may be extended to install a number of different R versions.

Learn more about how Posit Connect can use multiple R installations in the R chapter.

Your organization may have a shared volume containing all of the available R installations. You can mount those installations into the container as it is started. This sample command mounts a shared /shared/software/R location into the well-known /opt/R location within the container:

docker run -d --privileged=true --rm \
    -p :9999:3939 \
    -v $(pwd)/data:/data \
    -v /shared/software/R:/opt/R \
    rstudio/connect-docker:latest