Files & Directories
Program files
The Posit Connect installers place all program files into the /opt/rstudio-connect directory.
You should not need to change any files in the /opt/rstudio-connect hierarchy. Any alterations will be overwritten by subsequent reinstalls or upgrades of Posit Connect.
Configuration
When using the Helm chart, do not set these configurations in the main rstudio-connect.gcfg. Instead, modify the values.yaml configuration file that is used to invoke the helm command. Helm then generates the rstudio-connect.gcfg configuration for Posit Connect. For a detailed overview of this feature, see the Getting Started documentation.
The main Posit Connect configuration file is /etc/rstudio-connect/rstudio-connect.gcfg. You will edit this file to properly configure Posit Connect for your organization.
The rstudio-connect.gcfg file is initially created by the Connect installer and owned by root with 0600 permissions. The configuration file should only be readable by the user running the Connect server and not other users, as it may contain credentials and other sensitive information. For most installations, this means that rstudio-connect.gcfg should remain owned by root with 0600 permissions.
Restart Posit Connect after altering the rstudio-connect.gcfg configuration file using the instructions in the Stopping and Starting section.
Configuration settings marked as “reloadable” do not require a full restart. See the Configuration appendix to learn which properties are reloadable. You can find a “reload” command for your operating system in the Stopping and Starting section.
A configuration management tool like Puppet or Chef can be used to maintain the rstudio-connect.gcfg file.
Posit Connect upgrades will not overwrite customizations to the rstudio-connect.gcfg file. Similarly, the initial installation of Posit Connect will not overwrite the rstudio-connect.gcfg file if it already exists.
See the Configuration appendix for details about the configuration files, their syntax, the available settings, and more.
Server log
The Posit Connect server log is written to /var/log/rstudio/rstudio-connect/rstudio-connect.log by default and is owned by root with 0600 permissions. The server log location must be writable by the user running the Connect server. For most installations, this is the root user.
When logrotate is available, configuration for Connect log rotation is added as part of the Connect product installation. Adjust the logrotate configuration if you alter the server log location.
If you are using the official Posit Connect container image or the Posit Connect Helm chart, the server log is written to STDOUT rather than to disk. The Logging section explains how to adjust this configuration.
Access logs
The Posit Connect HTTP access log is written to /var/log/rstudio/rstudio-connect/rstudio-connect.access.log by default and is owned by root with 0600 permissions. The access log location must be writable by the user running the Connect server. For most installations, this is the root user.
When logrotate is available, configuration for Connect log rotation is added as part of the Connect product installation. Adjust the logrotate configuration if you alter the access log location.
Audit log
The Posit Connect audit log file is disabled by default. When enabled, its configured location (e.g., /var/log/rstudio/rstudio-connect/rstudio-connect.audit.log) is owned by root with 0600 permissions. The audit log location must be writable by the user running the Connect server. For most installations, this is the root user.
When logrotate is available, configuration for Connect log rotation is added as part of the Connect product installation. Adjust the logrotate configuration if you alter the audit log location.
Application logs
Each process launched by Posit Connect produces output that is retained within the jobs subdirectory of the Posit Connect data directory (see the Variable Data section for details). These directories and files are managed by the server. They are retained for 30 days and subsequently removed from the system.
Application logs are available in the Posit Connect dashboard. The dashboard settings page for deployed content contains a Logs section containing execution details for each launched process. Standard output and standard error are captured and available.
Variable data
Posit Connect manages uploaded applications, APIs, documents, and plots. All of the variable data associated with this content is stored within the server’s data directory. This includes:
- Deployment bundles as uploaded by the user.
- Directories containing unpacked bundles, including source code.
- R and Python packages, as demanded by the deployed code.
- Rendered documents.
- Application images as uploaded by the user.
- Git repository clones associated with applications.
The Posit Connect data directory also contains information used by the server in managing your deployed content. This includes:
- The Posit Connect encryption key.
- SQLite database files.
- Process execution information including logged output.
- Parameter overrides for R Markdown documents.
The default location for the Posit Connect data directory is /var/lib/rstudio-connect. This can be customized by specifying an alternate Server.DataDir in your configuration file.
; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
DataDir = /mnt/posit-connectThe Posit Connect SQLite database files must be on a local file system; they cannot reside on a networked file system. If the location for Server.DataDir is a networked file system, perhaps over NFS, configure SQLite.Dir to keep the SQLite data files on local storage.
; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
DataDir = /mnt/nfs/posit-connect
[SQLite]
Dir = /var/lib/rstudio-connect/dbIf you would like to store the encryption key separate from the other variable data, customize Database.Dir. You should also configure SQLite.Dir to indicate where the SQLite data files are stored.
; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
DataDir = /mnt/nfs/posit-connect
[Database]
Dir = /mnt/secrets/posit-connect
[SQLite]
Dir = /var/lib/rstudio-connect/dbPosit Connect will not start if the following user-configurable directories are located under Posit Connect’s installation directory (typically /opt/rstudio-connect): Server.DataDir, SQLite.Dir, Server.TempDir, Database.Dir, Server.LandingDir. See below for help safely relocating variable data.
Relocating variable data
Any time you change the settings Server.DataDir, Database.Dir or SQLite.Dir, you MUST manually move files in those directories from the old location to the new location. Failure to do so may lead to data loss or other errors. Read on for specific directions.
Here are a few scenarios:
If
SQLite.Diris being customized, all files which the names have a prefix ofconnectshould be moved to the new location. All other files, including the encryption.keyfile should not be moved.If
Database.Diris being customized, all files that were previously stored in{Server.DataDir}/dbshould be moved to the new location.If
Server.DataDiris being customized, all files under the configured directory should be moved.
The encryption key is specially sensitive to changes to these settings and can prevent Posit Connect from starting up if not moved correctly. If the encryption key is lost a new one will be created automatically but all encrypted data will be unrecoverable. See the Connect Administrative Tool appendix for more information on how to allow Connect to run again in this situation using the command rscadmin reset-secret-key.
Permissions
Posit Connect assigns ownership and permissions to files beneath the data directory as they are created. This section documents the general ownership patterns you will find under the Posit Connect data directory.
File ownership and permissions within the data directory are adjusted automatically by Posit Connect. You should not need to adjust the ownership or permissions for any files within the Posit Connect data directory.
The file and directory permissions given in this section assume that the Connect server is run by the root user, as that is how most installations run Connect. If Connect is run by an unprivileged user such as rstudio-connect, references to root throughout this section should be seen as references to that unprivileged user.
The root Unix user name is used throughout this section as a stand-in for the user running the Connect server.
Directories directly accessed from R and Python will usually be owned by the Applications.RunAs user and the Applications.SharedRunAsUnixGroup group.
The Applications.RunAs setting defaults to use an rstudio-connect account. The Applications.SharedRunAsUnixGroup setting defaults to use an rstudio-connect group. Both the rstudio-connect Unix user and group are created during Posit Connect installation.
Both Applications.RunAs and Applications.SharedRunAsUnixGroup can be customized. See the process management section for additional details and examples.
The rstudio-connect Unix user name and group name is used throughout this section rather than repeatedly referencing these configuration settings.
Directories used during metrics collection are owned by the rstudio-connect user (customizable via the Metrics.User setting). Group ownership for these directories will be the primary Unix group of the Unix user defined by Metrics.User
The Operational Metrics page describes how to configure metrics collection.
/var/lib/rstudio-connect
The /var/lib/rstudio-connect data directory is owned by the user that runs the Connect server process. In most installations, this means that the directory is owned by root with 0701 permissions.
Path Owner Permission
----------------------------------------------------------------------
/var/lib/rstudio-connect/ root 0701Data directories beneath /var/lib/rstudio-connect not accessed when running content processes or by the monitoring system are also owned by the user that runs the Connect server process. In most installations, this means that locations beneath the Connect data directory and not otherwise listed are owned by root with 0700 permissions.
/var/lib/rstudio-connect/metrics
The metrics directory contains data recorded by the Connect metrics system.
Path Owner Permission
----------------------------------------------------------------------
/var/lib/rstudio-connect/
\- metrics/ rstudio-connect 0700All files and directories beneath the metrics hierarchy must be owned by the rstudio-connect user (configured by the Metrics.User).
/var/lib/rstudio-connect/R
The R directory contains R packages used by Connect to assist when content is deployed. It is a private R library that is not available to content when it runs.
Path Owner Permission
----------------------------------------------------------------------
/var/lib/rstudio-connect/
\- R/ rstudio-connect 0700
\- 4.3.0/ rstudio-connect 0700All files and directories beneath the R hierarchy must be owned by rstudio-connect. Files are given 0600 permissions and directories have 0700.
/var/lib/rstudio-connect/packrat
The packrat subdirectory contains R packages installed on behalf of deployed content. These packages are installed when content is deployed and used each time the content runs.
Path Owner Permission
----------------------------------------------------------------------
/var/lib/rstudio-connect/
\- packrat/ rstudio-connect 0700
\- 4.3.0/ rstudio-connect 0700All files and directories beneath the packrat hierarchy must be owned by the rstudio-connect user and the rstudio-connect group. Files must have 0640 permissions while directories need 0750 permissions.
/var/lib/rstudio-connect/python-environments
The python-environments directories contains downloaded Python packages and virtual environments built on behalf of deployed content. Python environments may be shared by multiple content items if the dependencies match.
Path Owner Permission
----------------------------------------------------------------------
/var/lib/rstudio-connect/
\- python-environments/ rstudio-connect 0700
\- _packages_cache rstudio-connect 0750
\- pip/ rstudio-connect 0750
\- 3.11.3/ rstudio-connect 0750
\- pip/ rstudio-connect 0750
\- 3.11.3/ rstudio-connect 0750All files and directories beneath the python-environments path must be owned by the rstudio-connect user and the rstudio-connect group. Files must have 0640 permissions while directories need 0750 permissions.
/var/lib/rstudio-connect/reports
The reports directory contains the generated output produced by rendering content deployed with source.
Path Owner Permission
----------------------------------------------------------------------
/var/lib/rstudio-connect/
\- reports/ root 0711
\- v2/ root 0711
\- APP_ID/ root 0711
\- VARIANT_ID/ root 0711
\- RENDERING_ID/ rstudio-connect 0700
\- document.html rstudio-connect 0600Within this structure, the APP_ID directory corresponds to a content item (for example, an R Markdown document, Jupyter Notebook, or Quarto project). The VARIANT_ID directory represents a configuration of that document, such as a set of parameter values. Most documents have only a single variant. The RENDERING_ID contains a single rendering of the content using the designated configuration.
When the content has been assigned a RunAs user, the rendering files are owned by that user rather than rstudio-connect.
These files are owned by rstudio-connect or the RunAs user only while the rendering is running. Once it completes, they are owned by root.
/var/lib/rstudio-connect/bookmarks
The bookmarks directory contains a bookmarking state subdirectory for each Shiny application.
Learn more about server-stored Shiny bookmarking state in this article.
Path Owner Permission
----------------------------------------------------------------------
/var/lib/rstudio-connect/
\- bookmarks/ root 0711
\- APP_ID/ rstudio-connect 0770Within this structure, the APP_ID directory corresponds to a single Shiny application.
/var/lib/rstudio-connect/apps
The apps directory contains directories for each deployment, organized by bundle.
Path Owner Permission
----------------------------------------------------------------------
/var/lib/rstudio-connect/
\- apps/ root 0711
\- APP_ID/ root 0700
\- BUNDLE_ID/ rstudio-connect 0750
\- packrat/ rstudio-connect 0750
\- app.R rstudio-connect 0640Within this structure, the APP_ID corresponds to a single content item (for example, a Shiny application, R Markdown document, or Jupyter Notebook). The BUNDLE_ID contains the files associated with a single bundle uploaded for that content.
The ownership and permissions for the BUNDLE_ID directory depend on whether or not the content is configured with a custom RunAs setting. Posit Connect adjusts ownership and permissions whenever the target RunAs user changes.
Without a custom RunAs setting, the BUNDLE_ID directory owned by rstudio-connect with directories having 0750 and files having 0640 permissions.
Learn more about using a custom RunAs user in the User Account for Processes section.
Posit Connect needs more complicated permissions when content uses a custom RunAs setting. The rstudio-connect user (Applications.RunAs) is used to install packages required by the content. The content-specific custom RunAs user is used when running the deployed code.
Path Owner Permission
----------------------------------------------------------------------
/var/lib/rstudio-connect/
\- apps/ root 0711
\- APP_ID/ root 0700
\- BUNDLE_ID/ RunAs 0750
\- packrat/ rstudio-connect 0750
\- app.R RunAs 0640The BUNDLE_ID directory is given 0750 permissions and is owned by the custom RunAs user and the rstudio-connect group. The BUNDLE_ID/packrat and BUNDLE_ID/python directories are owned by rstudio-connect with group ownership of rstudio-connect.