This vignette explains CS9 installation options and infrastructure requirements.
Installation options
CS9 can be installed in two configurations:
1. CRAN installation (limited functionality)
Install CS9 directly from CRAN for documentation, examples, and development tools:
install.packages("cs9")
library(cs9)
What works with CRAN installation:
- Package documentation and help files
- Function examples and vignettes
- Environment diagnostic tools (
cs9::check_environment_setup()
) - Code templates and development utilities
- Basic configuration management
Limitations:
- No database connectivity
- Cannot run surveillance tasks
- Limited to documentation and development aids
Database Setup
CS9 requires a PostgreSQL database backend for full functionality.
PostgreSQL Installation
Option 1: Docker PostgreSQL (Recommended)
# Run PostgreSQL in Docker
docker run --name cs9-postgres -e POSTGRES_PASSWORD=yourStrongPassword100 \
-e POSTGRES_DB=cs9_surveillance -p 5432:5432 -d postgres:13
# Connect to create additional databases/schemas as needed
docker exec -it cs9-postgres psql -U postgres -d cs9_surveillance
Database Schema Setup
After PostgreSQL is running, create your surveillance database:
-- Connect as postgres user
CREATE DATABASE cs9_surveillance;
CREATE USER cs9_user WITH PASSWORD 'yourStrongPassword100';
GRANT ALL PRIVILEGES ON DATABASE cs9_surveillance TO cs9_user;
-- Create schemas for different access levels
\c cs9_surveillanceCREATE SCHEMA config;
CREATE SCHEMA anon;
GRANT ALL ON SCHEMA config TO cs9_user;
GRANT ALL ON SCHEMA anon TO cs9_user;
Environment Variable Configuration
CS9 requires specific environment variables to connect to your database. These variables must be available in R, typically through your .Renviron
file.
Setting up .Renviron
-
Find or create your .Renviron file:
# Check current .Renviron location Sys.getenv("R_ENVIRON_USER") # Open .Renviron file for editing file.edit("~/.Renviron")
Add CS9 configuration variables:
# CS9 Core Configuration
CS9_AUTO=0
CS9_PATH=
# Database Connection Settings
CS9_DBCONFIG_ACCESS=config/anon
CS9_DBCONFIG_DRIVER=PostgreSQL Unicode
CS9_DBCONFIG_PORT=5432
CS9_DBCONFIG_SERVER=localhost
CS9_DBCONFIG_USER=cs9_user
CS9_DBCONFIG_PASSWORD=yourStrongPassword100
CS9_DBCONFIG_SSLMODE=prefer
# Database Schema Configuration
CS9_DBCONFIG_SCHEMA_CONFIG=config
CS9_DBCONFIG_DB_CONFIG=cs9_surveillance
CS9_DBCONFIG_SCHEMA_ANON=anon
CS9_DBCONFIG_DB_ANON=cs9_surveillance
-
Restart your R session after making changes to
.Renviron
Variable Descriptions
Variable | Example Value | Description |
---|---|---|
CS9_AUTO |
0 |
Set to 0 for interactive mode, 1 for automated mode |
CS9_PATH |
`| Base path for cs9::path function (usually empty) | | CS9_DBCONFIG_ACCESS| config/anon| Database access levels (slash-separated) | | CS9_DBCONFIG_DRIVER| PostgreSQL Unicode| Database driver name | | CS9_DBCONFIG_SERVER| localhost| Database server hostname or IP | | CS9_DBCONFIG_PORT| 5432| Database server port | | CS9_DBCONFIG_USER| cs9_user| Database username | | CS9_DBCONFIG_PASSWORD| yourStrongPassword100| Database password | | CS9_DBCONFIG_SSLMODE| prefer| SSL connection preference | | CS9_DBCONFIG_SCHEMA_CONFIG| config| Schema for CS9 configuration tables | | CS9_DBCONFIG_DB_CONFIG| cs9_surveillance| Database for configuration | | CS9_DBCONFIG_SCHEMA_ANON| anon| Schema for anonymous data tables | | CS9_DBCONFIG_DB_ANON| cs9_surveillance` |
Database for surveillance data |
Package behavior without database configuration
If you install CS9 from CRAN without setting up the database configuration, the package will load with limited functionality. You will see messages like:
Environment setup failed: Missing required environment variables: CS9_DBCONFIG_ACCESS, CS9_DBCONFIG_DRIVER, CS9_DBCONFIG_PORT, CS9_DBCONFIG_SERVER
CS9 database configuration not available. Package loaded with limited functionality.
Use cs9::check_environment_setup() to diagnose configuration issues.
You can use cs9::check_environment_setup()
to diagnose what needs to be configured for full functionality.
Docker
CS9 is designed to work within a containerized environment for production use. An example docker-compose file is available here.
For getting started, we recommend cloning the cs9example repository, which provides a complete template for implementing a surveillance system with CS9.
Transitioning from CRAN to full setup
If you installed CS9 from CRAN and want to enable full surveillance functionality:
-
Check Current Status
cs9::check_environment_setup()
-
Set Up Database
- Install PostgreSQL or MariaDB
- Create databases for your surveillance system
- Note connection parameters (host, port, username, password)
-
Configure Environment Variables
- Add the variables listed below to your
.Renviron
file - Restart R session
- Run
cs9::check_environment_setup()
to verify configuration
- Add the variables listed below to your
-
Test Full Functionality
# This should now work without errors ss <- cs9::SurveillanceSystem_v9$new(name = "test_system")
Verification and Troubleshooting
Verify Your Setup
After completing the installation steps, verify that CS9 is working correctly:
# Load CS9
library(cs9)
# Check environment configuration
cs9::check_environment_setup()
# Test surveillance system creation
ss <- cs9::SurveillanceSystem_v9$new(name = "test_surveillance")
print(ss$name) # Should print "test_surveillance"
Common Issues and Solutions
Issue: “Missing required environment variables”
Solution: Ensure all CS9_DBCONFIG_* variables are set in your .Renviron file and restart R.
Issue: “Could not connect to database”
Solutions: - Verify PostgreSQL is running: sudo systemctl status postgresql
(Linux) or brew services list | grep postgres
(macOS) - Check database credentials match your .Renviron configuration - Test connection manually: docker exec -it cs9-postgres psql -U cs9_user -d cs9_surveillance
Next Steps
Once CS9 is successfully installed and configured:
-
Learn the Framework: Read
vignette("cs9")
for architecture and concepts -
Create Your First Task: Follow
vignette("creating-a-task")
for hands-on tutorial
-
Organize Your Project: See
vignette("file-layout")
for package structure guidance - Explore Examples: Clone cs9example for a complete implementation template