trogers1884/c77_rbac
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
c77_rbac/INSTALL.md
trogers1884 10f8637413 c77_rbac v1.1
2025-05-23 23:29:45 -05:00

770 lines
22 KiB
Markdown
Raw Blame History

# c77_rbac PostgreSQL Extension - Installation Guide
This comprehensive guide covers all aspects of installing and upgrading the c77_rbac extension, with detailed examples for different scenarios.
## Table of Contents
1. [Prerequisites](#prerequisites)
2. [Installation Overview](#installation-overview)
3. [Fresh Installation (Version 1.1)](#fresh-installation-version-11)
4. [Upgrading from Version 1.0](#upgrading-from-version-10)
5. [Post-Installation Verification](#post-installation-verification)
6. [Initial Configuration](#initial-configuration)
7. [Troubleshooting Installation Issues](#troubleshooting-installation-issues)
8. [Uninstallation](#uninstallation)
9. [Production Deployment Checklist](#production-deployment-checklist)
## Prerequisites
### System Requirements
- **PostgreSQL**: Version 14 or later
- **Operating System**: Linux (Ubuntu, CentOS, RHEL, Debian), macOS, or Windows
- **Privileges**: PostgreSQL superuser access for installation
- **Disk Space**: Minimal (< 1MB for extension files)
### Required Access Levels
1. **System Administrator**: Access to copy files to PostgreSQL extension directory
2. **Database Superuser**: To create the extension and grant privileges
3. **Application User**: Regular database user for your application
### Identify Your PostgreSQL Version and Paths
```bash
# Check PostgreSQL version
psql --version
# or
sudo -u postgres psql -c "SELECT version();"
# Find PostgreSQL installation directory
pg_config --sharedir
# Example output: /usr/share/postgresql/14
# Find extension directory
pg_config --sharedir
# Extension directory will be: /usr/share/postgresql/14/extension/
```
## Installation Overview
### File Structure
The c77_rbac extension consists of these files:
```
c77_rbac.control # Extension metadata (version, dependencies)
c77_rbac--1.1.sql # Fresh installation SQL script
c77_rbac--1.0--1.1.sql # Upgrade script (1.0 → 1.1)
```
### Installation Paths
Choose the appropriate installation method:
- **Fresh Installation**: Use `c77_rbac--1.1.sql` directly
- **Upgrade from 1.0**: Use `c77_rbac--1.0--1.1.sql` upgrade script
## Fresh Installation (Version 1.1)
### Step 1: Download and Prepare Files
Download the extension files to a temporary directory:
```bash
# Create temporary directory
mkdir ~/c77_rbac_install
cd ~/c77_rbac_install
# Download files (replace with your actual download method)
wget https://github.com/yourusername/c77_rbac/releases/download/v1.1/c77_rbac.control
wget https://github.com/yourusername/c77_rbac/releases/download/v1.1/c77_rbac--1.1.sql
# Verify files downloaded
ls -la
# Should show:
# c77_rbac.control
# c77_rbac--1.1.sql
```
### Step 2: Copy Files to PostgreSQL Extension Directory
**For Ubuntu/Debian:**
```bash
# Find the correct PostgreSQL version directory
PG_VERSION=$(pg_config --version | sed 's/PostgreSQL \([0-9]\+\).*/\1/')
echo "PostgreSQL version: $PG_VERSION"
# Copy files (requires sudo)
sudo cp c77_rbac.control /usr/share/postgresql/$PG_VERSION/extension/
sudo cp c77_rbac--1.1.sql /usr/share/postgresql/$PG_VERSION/extension/
# Verify files copied correctly
ls -la /usr/share/postgresql/$PG_VERSION/extension/c77_rbac*
```
**For CentOS/RHEL/Rocky Linux:**
```bash
# Find PostgreSQL version
PG_VERSION=$(pg_config --version | sed 's/PostgreSQL \([0-9]\+\).*/\1/')
# Copy files
sudo cp c77_rbac.control /usr/pgsql-$PG_VERSION/share/extension/
sudo cp c77_rbac--1.1.sql /usr/pgsql-$PG_VERSION/share/extension/
# Verify
ls -la /usr/pgsql-$PG_VERSION/share/extension/c77_rbac*
```
**For macOS (with Homebrew):**
```bash
# Find Homebrew PostgreSQL path
PG_CONFIG_PATH=$(which pg_config)
PG_SHARE_DIR=$(pg_config --sharedir)
# Copy files
sudo cp c77_rbac.control $PG_SHARE_DIR/extension/
sudo cp c77_rbac--1.1.sql $PG_SHARE_DIR/extension/
# Verify
ls -la $PG_SHARE_DIR/extension/c77_rbac*
```
### Step 3: Create Database and Users
Connect as PostgreSQL superuser:
```bash
# Connect as postgres superuser
sudo -u postgres psql
```
Create your application database and users:
```sql
-- Create application database
CREATE DATABASE myapp_production;
-- Create application user with secure password
CREATE USER myapp_user WITH
PASSWORD 'your_very_secure_password_here'
NOSUPERUSER
NOCREATEDB
NOCREATEROLE;
-- Optional: Create read-only user for reporting
CREATE USER myapp_readonly WITH
PASSWORD 'readonly_secure_password'
NOSUPERUSER
NOCREATEDB
NOCREATEROLE;
-- List databases to verify
\l
```
### Step 4: Install the Extension
Connect to your application database:
```sql
-- Connect to your database
\c myapp_production
```
Install the c77_rbac extension:
```sql
-- Install extension (this creates all tables, functions, views)
CREATE EXTENSION c77_rbac;
-- Verify installation
SELECT extname, extversion FROM pg_extension WHERE extname = 'c77_rbac';
-- Should show: c77_rbac | 1.1
```
### Step 5: Grant Privileges to Application User
Grant necessary privileges to your application user:
```sql
-- Grant database-level privileges
GRANT CONNECT ON DATABASE myapp_production TO myapp_user;
GRANT CREATE ON DATABASE myapp_production TO myapp_user;
-- Grant schema usage
GRANT USAGE ON SCHEMA public TO myapp_user;
-- Grant table privileges (read-only, modifications through functions)
GRANT SELECT ON ALL TABLES IN SCHEMA public TO myapp_user;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO myapp_user;
-- Grant function execution privileges
GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA public TO myapp_user;
-- Set default privileges for future objects
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO myapp_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT EXECUTE ON FUNCTIONS TO myapp_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT USAGE, SELECT ON SEQUENCES TO myapp_user;
-- For readonly user (optional)
GRANT CONNECT ON DATABASE myapp_production TO myapp_readonly;
GRANT USAGE ON SCHEMA public TO myapp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO myapp_readonly;
GRANT SELECT ON public.c77_rbac_user_permissions TO myapp_readonly;
GRANT SELECT ON public.c77_rbac_summary TO myapp_readonly;
```
### Step 6: Verify Installation
Test the installation:
```sql
-- Check extension is installed
SELECT extname, extversion, extrelocatable FROM pg_extension WHERE extname = 'c77_rbac';
-- Check tables were created
\dt public.c77_rbac_*
-- Check functions were created
\df public.c77_rbac_*
-- Check views were created
\dv public.c77_rbac_*
-- Test basic functionality
SELECT public.c77_rbac_grant_feature('test_role', 'test_feature');
SELECT public.c77_rbac_assign_subject('test_user', 'test_role', 'global', 'all');
SELECT public.c77_rbac_can_access('test_feature', 'test_user', 'global', 'all');
-- Should return: true
-- Clean up test data
SELECT public.c77_rbac_revoke_subject_role('test_user', 'test_role', 'global', 'all');
SELECT public.c77_rbac_revoke_feature('test_role', 'test_feature');
```
## Upgrading from Version 1.0
### Pre-Upgrade Checklist
1. **Backup your database:**
```bash
pg_dump -U postgres -h localhost myapp_production > backup_before_upgrade.sql
```
2. **Verify current version:**
```sql
SELECT extname, extversion FROM pg_extension WHERE extname = 'c77_rbac';
-- Should show: c77_rbac | 1.0
```
3. **Check for dependencies:**
```sql
SELECT * FROM public.c77_rbac_show_dependencies();
```
### Step 1: Download Upgrade Files
```bash
# Create upgrade directory
mkdir ~/c77_rbac_upgrade
cd ~/c77_rbac_upgrade
# Download upgrade files
wget https://github.com/yourusername/c77_rbac/releases/download/v1.1/c77_rbac.control
wget https://github.com/yourusername/c77_rbac/releases/download/v1.1/c77_rbac--1.0--1.1.sql
# Optional: Download full 1.1 script for reference
wget https://github.com/yourusername/c77_rbac/releases/download/v1.1/c77_rbac--1.1.sql
```
### Step 2: Copy Upgrade Files
```bash
# Find PostgreSQL directory
PG_VERSION=$(pg_config --version | sed 's/PostgreSQL \([0-9]\+\).*/\1/')
# Copy files (Ubuntu/Debian)
sudo cp c77_rbac.control /usr/share/postgresql/$PG_VERSION/extension/
sudo cp c77_rbac--1.0--1.1.sql /usr/share/postgresql/$PG_VERSION/extension/
# For CentOS/RHEL, use:
# sudo cp c77_rbac.control /usr/pgsql-$PG_VERSION/share/extension/
# sudo cp c77_rbac--1.0--1.1.sql /usr/pgsql-$PG_VERSION/share/extension/
# Verify files
ls -la /usr/share/postgresql/$PG_VERSION/extension/c77_rbac*
# Should show:
# c77_rbac.control
# c77_rbac--1.0.sql (existing)
# c77_rbac--1.0--1.1.sql (new)
```
### Step 3: Perform the Upgrade
Connect to your database as superuser:
```bash
sudo -u postgres psql -d myapp_production
```
Execute the upgrade:
```sql
-- Check current version
SELECT extname, extversion FROM pg_extension WHERE extname = 'c77_rbac';
-- Perform upgrade
ALTER EXTENSION c77_rbac UPDATE TO '1.1';
-- Verify upgrade
SELECT extname, extversion FROM pg_extension WHERE extname = 'c77_rbac';
-- Should now show: c77_rbac | 1.1
```
### Step 4: Verify Upgrade Success
Test new functionality:
```sql
-- Test new bulk assignment function
SELECT * FROM public.c77_rbac_bulk_assign_subjects(
ARRAY['user1', 'user2', 'user3'],
'test_role',
'department',
'engineering'
);
-- Test new management views
SELECT * FROM public.c77_rbac_summary;
-- Test new utility functions
SELECT * FROM public.c77_rbac_get_user_roles('user1');
-- Test admin sync function
SELECT public.c77_rbac_sync_admin_features();
-- Clean up test data
SELECT public.c77_rbac_revoke_subject_role('user1', 'test_role', 'department', 'engineering');
SELECT public.c77_rbac_revoke_subject_role('user2', 'test_role', 'department', 'engineering');
SELECT public.c77_rbac_revoke_subject_role('user3', 'test_role', 'department', 'engineering');
```
### Step 5: Update Application Code
After successful upgrade, you can now use new features in your application:
```php
// Laravel example - using new bulk operations
$userIds = ['1001', '1002', '1003', '1004', '1005'];
$results = DB::select("
SELECT * FROM public.c77_rbac_bulk_assign_subjects(?, ?, ?, ?)
", [json_encode($userIds), 'student', 'program', 'dui_education']);
foreach ($results as $result) {
if (!$result->success) {
Log::warning("Failed to assign role to user {$result->external_id}: {$result->error_message}");
}
}
```
## Post-Installation Verification
### Comprehensive Testing Script
Create a test script to verify all functionality:
```sql
-- test_c77_rbac_installation.sql
\echo 'Testing c77_rbac installation...'
-- Test 1: Basic feature granting
\echo 'Test 1: Feature granting'
SELECT public.c77_rbac_grant_feature('admin', 'manage_users');
SELECT public.c77_rbac_grant_feature('manager', 'view_reports');
SELECT public.c77_rbac_grant_feature('employee', 'view_own_data');
-- Test 2: Role assignment
\echo 'Test 2: Role assignment'
SELECT public.c77_rbac_assign_subject('admin_user', 'admin', 'global', 'all');
SELECT public.c77_rbac_assign_subject('dept_manager', 'manager', 'department', 'sales');
SELECT public.c77_rbac_assign_subject('employee_1', 'employee', 'department', 'sales');
-- Test 3: Bulk assignment (v1.1 feature)
\echo 'Test 3: Bulk assignment'
SELECT * FROM public.c77_rbac_bulk_assign_subjects(
ARRAY['emp_1', 'emp_2', 'emp_3'],
'employee',
'department',
'engineering'
);
-- Test 4: Permission checking
\echo 'Test 4: Permission checking'
SELECT public.c77_rbac_can_access('manage_users', 'admin_user', 'global', 'all') as admin_can_manage;
SELECT public.c77_rbac_can_access('view_reports', 'dept_manager', 'department', 'sales') as manager_can_view;
SELECT public.c77_rbac_can_access('manage_users', 'employee_1', 'department', 'sales') as employee_cannot_manage;
-- Test 5: Management views (v1.1 feature)
\echo 'Test 5: Management views'
SELECT * FROM public.c77_rbac_summary;
SELECT * FROM public.c77_rbac_get_user_roles('admin_user');
-- Test 6: Admin sync (v1.1 feature)
\echo 'Test 6: Admin sync'
SELECT public.c77_rbac_sync_admin_features();
-- Test 7: Removal functions (v1.1 feature)
\echo 'Test 7: Removal functions'
SELECT public.c77_rbac_revoke_subject_role('emp_1', 'employee', 'department', 'engineering');
SELECT public.c77_rbac_revoke_feature('employee', 'temporary_feature');
-- Cleanup
\echo 'Cleaning up test data...'
DELETE FROM public.c77_rbac_subject_roles;
DELETE FROM public.c77_rbac_role_features;
DELETE FROM public.c77_rbac_subjects;
DELETE FROM public.c77_rbac_roles;
DELETE FROM public.c77_rbac_features;
\echo 'Installation test complete!'
```
Run the test:
```bash
sudo -u postgres psql -d myapp_production -f test_c77_rbac_installation.sql
```
### Performance Testing
Test with larger datasets:
```sql
-- Performance test script
DO $$
DECLARE
start_time TIMESTAMP;
end_time TIMESTAMP;
i INTEGER;
BEGIN
start_time := clock_timestamp();
-- Create test features
FOR i IN 1..100 LOOP
PERFORM public.c77_rbac_grant_feature('perf_role', 'feature_' || i);
END LOOP;
end_time := clock_timestamp();
RAISE NOTICE 'Feature creation time: %', end_time - start_time;
start_time := clock_timestamp();
-- Test bulk assignment
PERFORM public.c77_rbac_bulk_assign_subjects(
array_agg('user_' || generate_series),
'perf_role',
'department',
'performance_test'
) FROM generate_series(1, 1000);
end_time := clock_timestamp();
RAISE NOTICE 'Bulk assignment time (1000 users): %', end_time - start_time;
start_time := clock_timestamp();
-- Test permission checking
FOR i IN 1..100 LOOP
PERFORM public.c77_rbac_can_access('feature_1', 'user_' || i, 'department', 'performance_test');
END LOOP;
end_time := clock_timestamp();
RAISE NOTICE 'Permission check time (100 checks): %', end_time - start_time;
END $$;
```
## Initial Configuration
### Example: Court Education System Setup
After installation, configure for your specific use case:
```sql
-- court_system_setup.sql
-- Step 1: Create court-specific roles and features
SELECT public.c77_rbac_grant_feature('court_admin', 'manage_all_programs');
SELECT public.c77_rbac_grant_feature('court_admin', 'view_all_participants');
SELECT public.c77_rbac_grant_feature('court_admin', 'generate_court_reports');
SELECT public.c77_rbac_grant_feature('court_admin', 'manage_users');
SELECT public.c77_rbac_grant_feature('judge', 'view_court_participants');
SELECT public.c77_rbac_grant_feature('judge', 'approve_completions');
SELECT public.c77_rbac_grant_feature('judge', 'access_court_reports');
SELECT public.c77_rbac_grant_feature('court_clerk', 'enroll_participants');
SELECT public.c77_rbac_grant_feature('court_clerk', 'view_court_participants');
SELECT public.c77_rbac_grant_feature('court_clerk', 'update_participant_info');
SELECT public.c77_rbac_grant_feature('program_coordinator', 'manage_programs');
SELECT public.c77_rbac_grant_feature('program_coordinator', 'view_program_participants');
SELECT public.c77_rbac_grant_feature('program_coordinator', 'update_progress');
SELECT public.c77_rbac_grant_feature('counselor', 'view_assigned_participants');
SELECT public.c77_rbac_grant_feature('counselor', 'update_progress');
SELECT public.c77_rbac_grant_feature('counselor', 'mark_attendance');
SELECT public.c77_rbac_grant_feature('participant', 'view_own_progress');
SELECT public.c77_rbac_grant_feature('participant', 'access_program_materials');
-- Step 2: Sync admin features
SELECT public.c77_rbac_sync_admin_features();
-- Step 3: Assign initial users
-- System administrator
SELECT public.c77_rbac_assign_subject('1', 'court_admin', 'global', 'all');
-- County Superior Court judge
SELECT public.c77_rbac_assign_subject('101', 'judge', 'court', 'county_superior');
-- Court clerk for county superior
SELECT public.c77_rbac_assign_subject('201', 'court_clerk', 'court', 'county_superior');
-- DUI program coordinator
SELECT public.c77_rbac_assign_subject('301', 'program_coordinator', 'program', 'dui_education');
-- Step 4: Apply security policies to tables (after creating your tables)
-- SELECT public.c77_rbac_apply_policy('participants', 'view_court_participants', 'court', 'assigned_court');
-- SELECT public.c77_rbac_apply_policy('participant_progress', 'view_own_progress', 'participant', 'participant_id');
-- SELECT public.c77_rbac_apply_policy('programs', 'manage_programs', 'program', 'program_type');
-- Step 5: Verify setup
SELECT * FROM public.c77_rbac_summary;
```
### Laravel Environment Configuration
Update your `.env` file:
```ini
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=myapp_production
DB_USERNAME=myapp_user
DB_PASSWORD=your_very_secure_password_here
# Optional: Enable query logging for debugging
DB_LOG_QUERIES=true
```
## Troubleshooting Installation Issues
### Common Installation Problems
#### Problem 1: Permission Denied Copying Files
**Error:**
```bash
cp: cannot create regular file '/usr/share/postgresql/14/extension/c77_rbac.control': Permission denied
```
**Solution:**
```bash
# Use sudo for copying files
sudo cp c77_rbac.control /usr/share/postgresql/14/extension/
# Or change to postgres user temporarily
sudo su - postgres
cp /path/to/c77_rbac.control /usr/share/postgresql/14/extension/
exit
```
#### Problem 2: Extension Directory Not Found
**Error:**
```bash
cp: cannot stat '/usr/share/postgresql/14/extension/': No such file or directory
```
**Solution:**
```bash
# Find the correct PostgreSQL installation
pg_config --sharedir
# Or search for extension directories
find /usr -name "extension" -type d 2>/dev/null | grep postgresql
# Common locations:
# Ubuntu/Debian: /usr/share/postgresql/14/extension/
# CentOS/RHEL: /usr/pgsql-14/share/extension/
# macOS Homebrew: /opt/homebrew/share/postgresql@14/extension/
```
#### Problem 3: Extension Creation Fails
**Error:**
```sql
ERROR: could not open extension control file "/usr/share/postgresql/14/extension/c77_rbac.control": No such file or directory
```
**Solution:**
```bash
# Verify files are in correct location
ls -la /usr/share/postgresql/14/extension/c77_rbac*
# Check file permissions
sudo chmod 644 /usr/share/postgresql/14/extension/c77_rbac*
# Restart PostgreSQL if necessary
sudo systemctl restart postgresql
```
#### Problem 4: Upgrade Fails
**Error:**
```sql
ERROR: extension "c77_rbac" has no update path from version "1.0" to version "1.1"
```
**Solution:**
```bash
# Verify upgrade script exists
ls -la /usr/share/postgresql/14/extension/c77_rbac--1.0--1.1.sql
# Check control file has correct version
cat /usr/share/postgresql/14/extension/c77_rbac.control
# Reload configuration
sudo systemctl reload postgresql
```
### Diagnostic Commands
```sql
-- Check extension status
SELECT * FROM pg_extension WHERE extname = 'c77_rbac';
-- Check available versions
SELECT name, version, comment FROM pg_available_extensions WHERE name = 'c77_rbac';
-- Check update paths
SELECT * FROM pg_extension_update_paths('c77_rbac');
-- Verify tables exist
SELECT tablename FROM pg_tables WHERE tablename LIKE 'c77_rbac_%';
-- Check function permissions
SELECT routine_name, specific_name FROM information_schema.routines
WHERE routine_name LIKE 'c77_rbac_%';
```
### Log Analysis
Check PostgreSQL logs for detailed error information:
```bash
# Ubuntu/Debian
sudo tail -f /var/log/postgresql/postgresql-14-main.log
# CentOS/RHEL
sudo tail -f /var/lib/pgsql/14/data/log/postgresql-*.log
# macOS Homebrew
tail -f /opt/homebrew/var/log/postgresql@14.log
```
## Uninstallation
### Safe Uninstallation Process
1. **Check dependencies first:**
```sql
SELECT * FROM public.c77_rbac_show_dependencies();
```
2. **Remove all RLS policies:**
```sql
SELECT public.c77_rbac_remove_all_policies();
```
3. **Optionally backup RBAC data:**
```sql
COPY (SELECT * FROM public.c77_rbac_user_permissions) TO '/tmp/rbac_backup.csv' CSV HEADER;
```
4. **Complete cleanup:**
```sql
SELECT public.c77_rbac_cleanup_for_removal(true); -- true = remove data
```
5. **Drop the extension:**
```sql
DROP EXTENSION c77_rbac CASCADE;
```
6. **Remove files from system:**
```bash
sudo rm /usr/share/postgresql/14/extension/c77_rbac*
```
## Production Deployment Checklist
### Pre-Deployment
- [ ] **Database backup completed**
- [ ] **Extension files copied to production server**
- [ ] **PostgreSQL service restarted/reloaded**
- [ ] **Test environment upgrade successful**
- [ ] **Application code updated to handle new features**
- [ ] **Rollback plan prepared**
### Deployment Steps
- [ ] **Connect as superuser**
- [ ] **Install/upgrade extension**
- [ ] **Verify installation with test script**
- [ ] **Grant privileges to application users**
- [ ] **Configure initial roles and features**
- [ ] **Apply RLS policies to application tables**
- [ ] **Test application connectivity**
### Post-Deployment
- [ ] **Monitor PostgreSQL logs for errors**
- [ ] **Verify application functionality**
- [ ] **Check performance metrics**
- [ ] **Update monitoring alerts**
- [ ] **Document installation for team**
### Production Configuration Example
```bash
#!/bin/bash
# production_deploy.sh
set -e # Exit on any error
echo "Starting c77_rbac production deployment..."
# Backup database
pg_dump -U postgres -h localhost myapp_production > backup_$(date +%Y%m%d_%H%M%S).sql
# Copy extension files
sudo cp c77_rbac.control /usr/share/postgresql/14/extension/
sudo cp c77_rbac--1.1.sql /usr/share/postgresql/14/extension/
# Install extension
sudo -u postgres psql -d myapp_production -c "CREATE EXTENSION IF NOT EXISTS c77_rbac;"
# Verify installation
sudo -u postgres psql -d myapp_production -c "SELECT extname, extversion FROM pg_extension WHERE extname = 'c77_rbac';"
# Run initialization script
sudo -u postgres psql -d myapp_production -f court_system_setup.sql
echo "Deployment completed successfully!"
```
This installation guide provides comprehensive coverage of all installation scenarios with detailed examples and troubleshooting information. The step-by-step approach ensures successful deployment in any environment.
Reference in New Issue View Git Blame Copy Permalink