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 re-installs 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. This file is initially owned by root with permissions 0600. You will edit this file to properly configure Posit Connect for your organization.
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. We recommend that it remain owned by root and have permissions 0600, as your configuration may need to contain passwords and other sensitive information.
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.
If new versions of Posit Connect require modification to the configuration, a separate /etc/rstudio-connect/rstudio-connect-migration.gcfg file may be created automatically with the updated settings. It will have the same permissions on disk of the main configuration file.
If Posit Connect is using an alternate configuration file or path, the configuration migration will take place in a file with the same name of the one currently in use plus the suffix migration. For example, if the service is started with connect --config /path/to/rsc.gcfg an attempt to migrate the settings will take place for the file /path/to/rsc-migration.gcfg. If Posit Connect cannot create or write to the path where the migrated configuration would be placed then the migration will happen in memory only. A different path for the migration file can be specified by using the --migration-config option for the connect command.
See the Configuration appendix for details about the configuration files, their syntax, the available settings, and the migration process.
Server Log
If you are using the official Posit Connect docker image, the server logs are written to stdout by default and are not available at the default log path /var/log/rstudio/rstudio-connect/rstudio-connect.log. If you prefer to log to a file, you will need to modify the value of the Logging.ServiceLog setting.
The Posit Connect server log is located at /var/log/rstudio/rstudio-connect/rstudio-connect.log. This file is owned by root with permissions 0600.
If logrotate is available when Posit Connect is installed, a logrotate configuration will be installed. The default configuration is to rotate the log file daily. The old log file will be stored alongside the original with a numeric extension, .1, .2, etc. The rotated log files are compressed after one day. The .1 log file is retained uncompressed, but older logs are compressed. Most systems use gzip for compression, giving log files with extensions like .2.gz, .3.gz. Logs will be maintained for 30 days.
The manual for logrotate has more information.
Access Logs
The Posit Connect HTTP access logs are located at /var/log/rstudio/rstudio-connect/rstudio-connect.access.log. This file is owned by root with permissions 0600. Log files are stored in Apache Combined Log Format. See https://httpd.apache.org/docs/2.2/logs.html#combined for a description of this format.
If logrotate is available when Posit Connect is installed, a logrotate configuration will be installed. The default configuration is to rotate the logfile daily. The old logfile will be compressed and stored alongside the original log file with a .1.gz extension (then .2.gz, etc.). Logs will maintained for 30 days.
If you configure Posit Connect to write to a different file, you will need to update the logrotate configuration accordingly.
Audit Log
The Posit Connect audit log file is optional and, if configured, is located at /var/log/rstudio/rstudio-connect/rstudio-connect.audit.log. This file is owned by root with permissions 0600. Audit log files are stored in either CSV or JSON format.
If logrotate is available when Posit Connect is installed, a logrotate configuration will be installed. The default configuration is to rotate the audit log file monthly. The old logfile will be compressed and stored alongside the original log file with a .1.gz extension (then .2.gz, etc.). Logs will maintained for the past 12 months.
If you configure Posit Connect to write to a different file, you will need to update the logrotate configuration accordingly.
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 and SQLite database.
- 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 must exist on local storage. If the location for Server.DataDir is not local storage but a networked location over NFS, configure the setting Database.Dir.
; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
DataDir = /mnt/posit-connect
[Database]
Dir = /var/lib/rstudio-connect/dbWith the configuration above all storage-related files (which includes the encryption key) will be stored in a different location. If there is a reason to keep these other files in a different location such as a shared NFS storage, it is still possible to only change the location of the SQLite database using instead the setting SQLite.Dir.
; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
DataDir = /mnt/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.
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.
We use the Unix account and group name rstudio-connect throughout this section instead of referencing these property names.
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
Learn how to customize metrics collection in the Historical Metrics Settings section.
/var/lib/rstudio-connect
The /var/lib/rstudio-connect directory is owned by root with permissions 0701.
Data directories beneath /var/lib/rstudio-connect not accessed by applications or by the monitoring system 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/ root 0701
\- 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/ root 0701
\- 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/ root 0701
\- 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-packages and python-environments
The python-packages and python-environments directories contain 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/ root 0701
\- python-packages/ rstudio-connect 0700
\- pip/ rstudio-connect 0750
\- python-environments/ rstudio-connect 0700
\- pip/ rstudio-connect 0750
\- 3.11.3/ rstudio-connect 0750All files and directories beneath the python-packages and python-environments paths 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
----------------------------------------------------------------------
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.
/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
----------------------------------------------------------------------
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
----------------------------------------------------------------------
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
----------------------------------------------------------------------
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.