Advanced Portal Features

Google Analytics Integration

The rXg portal system provides seamless integration with Google Analytics to track user behavior, conversion rates, and portal performance metrics. This integration supports both the legacy Universal Analytics (GA3) and the modern Google Analytics 4 (GA4) platforms, allowing operators to maintain existing analytics setups while transitioning to newer measurement frameworks.

Universal Analytics Configuration (GA3)

To configure Universal Analytics tracking, navigate to System::Portals and edit your custom portal. In the Google Analytics Web Property field, enter your Universal Analytics property ID in the format UA-123456-1, where the numbers correspond to your specific Google Analytics account and property identifiers. For example, if your Google Analytics account ID is 98765432 and this is your first property, you would enter UA-98765432-1.

Once configured, the portal will automatically inject the Universal Analytics tracking code into every page load. This includes tracking for page views, session duration, bounce rates, and custom events such as login attempts, authentication successes, and portal navigation patterns.

Google Analytics 4 Configuration (GA4)

For the newer Google Analytics 4 platform, use the Google Analytics Measurement ID field instead. GA4 measurement IDs follow the format G-ABC123DEF4, where the alphanumeric string after the 'G-' prefix uniquely identifies your GA4 data stream. For instance, a typical measurement ID might look like G-XXXXXXXXXX where the X's represent your specific measurement identifier.

GA4 provides enhanced event tracking capabilities that the rXg portal automatically leverages. The system will track enhanced ecommerce events for payment transactions, user engagement metrics for portal interaction quality, and conversion tracking for successful authentications and policy assignments.

Configuration Workflow Example

To set up Google Analytics tracking for a hotel portal, begin by creating your custom portal named "Hotel Guest Portal" with the controller name "hotel_guest". After the portal is created and the web server restarted, edit the portal record and locate the analytics configuration section.

If you are using Universal Analytics, obtain your tracking ID from your Google Analytics dashboard (typically found under Admin Property Tracking Info Tracking Code) and enter it in the Web Property field. For a hotel with account number 87654321, this might be UA-87654321-1.

Alternatively, for GA4 implementation, create a new GA4 property in your Google Analytics account, establish a web data stream for your portal domain, and copy the Measurement ID (found in the data stream details) into the Measurement ID field. This ID will appear similar to G-ABC123DEF4.

After saving the portal configuration, restart the web server in production mode to ensure the tracking code is properly integrated. You can verify successful integration by viewing the page source of your portal and confirming the presence of either the gtag or analytics.js tracking script, depending on your chosen analytics platform.

Bootstrap Configuration

The rXg portal system supports automated configuration through bootstrap YAML files, enabling operators to deploy portals with pre-configured account groups, policies, shared credentials, and other essential objects. This bootstrap mechanism eliminates the need for manual configuration after portal deployment and ensures consistent setup across multiple rXg installations or when redeploying portals.

Bootstrap File Structure and Location

The bootstrap configuration file must be named bootstrap.yml and placed in the root directory of your custom portal alongside the controller files and asset directories. When the portal is first activated or when the bootstrap process is manually triggered, the rXg system reads this YAML file and creates or updates the specified configuration objects according to the defined specifications.

Comprehensive Bootstrap Example

Consider a complete bootstrap configuration for a hotel guest portal that requires multiple account groups, differentiated service policies, and various authentication methods:

# Hotel Guest Portal Bootstrap Configuration
# This file automatically configures account groups, policies, and credentials
# Place this file as bootstrap.yml in the portal root directory

AccountGroup:
  - name: "Standard Hotel Guests"
    note: "Regular hotel guests with basic internet access"
    default_policy: "Basic Internet Access"
    session_timeout: "4 hours"

  - name: "Premium Hotel Guests"
    note: "Suite guests with enhanced service levels"
    default_policy: "Premium Internet Access"
    session_timeout: "24 hours"

  - name: "Hotel Staff"
    note: "Hotel employees and management personnel"
    default_policy: "Staff Network Access"
    session_timeout: "8 hours"

Policy:
  - name: "Basic Internet Access"
    note: "Standard internet service for hotel guests"
    captive_portal: "hotel_guest_splash"
    landing_portal: "hotel_guest_landing"
    download_bandwidth: "10 Mbps"
    upload_bandwidth: "2 Mbps"
    content_filtering: "Family Safe Browsing"

  - name: "Premium Internet Access"
    note: "Enhanced service for suite guests"
    captive_portal: "hotel_premium_splash"
    landing_portal: "hotel_premium_landing"
    download_bandwidth: "50 Mbps"
    upload_bandwidth: "10 Mbps"
    content_filtering: "Minimal Restrictions"

  - name: "Staff Network Access"
    note: "Internal network access for hotel operations"
    captive_portal: "hotel_staff_splash"
    landing_portal: "hotel_staff_dashboard"
    download_bandwidth: "100 Mbps"
    upload_bandwidth: "50 Mbps"
    content_filtering: "Business Appropriate"

SharedCredential:
  - name: "Guest WiFi Access"
    credential: ""
    policy: "Basic Internet Access"
    time: "4 hours"
    note: "Click-through access for standard hotel guests"

  - name: "Premium Guest Access"
    credential: "SUITE2024"
    policy: "Premium Internet Access"
    time: "24 hours"
    note: "Password-based access for suite guests"
    max_simultaneous_users: 50

  - name: "Conference Room Access"
    credential: "MEETING"
    policy: "Basic Internet Access"
    time: "2 hours"
    note: "Temporary access for meeting attendees"
    max_simultaneous_users: 20

CaptivePortal:
  - name: "Hotel Guest Splash"
    controller_name: "hotel_guest_splash"
    note: "Main landing page for hotel internet access"

  - name: "Hotel Premium Splash"
    controller_name: "hotel_premium_splash"
    note: "Premium guest portal with enhanced branding"

  - name: "Hotel Staff Splash"
    controller_name: "hotel_staff_splash"
    note: "Internal staff portal with administrative links"

LandingPortal:
  - name: "Hotel Guest Landing"
    controller_name: "hotel_guest_landing"
    note: "Post-authentication page for standard guests"

  - name: "Hotel Premium Landing"
    controller_name: "hotel_premium_landing"
    note: "Enhanced post-auth experience for premium guests"

  - name: "Hotel Staff Dashboard"
    controller_name: "hotel_staff_dashboard"
    note: "Staff dashboard with operational tools and reports"

Bootstrap Processing Workflow

When a portal containing a bootstrap.yml file is deployed, the rXg system initiates an automated configuration process. First, the system validates the YAML syntax and checks for required fields in each configuration object. If validation succeeds, the system proceeds to create or update each object type in dependency order, ensuring that referenced objects exist before creating objects that depend on them.

For example, policies must be created before shared credentials that reference them, and captive portals must exist before policies can reference them. The bootstrap processor handles these dependencies automatically, creating objects in the correct sequence to avoid reference errors.

Manual Bootstrap Execution

While bootstrap processing typically occurs automatically during portal deployment, operators can manually trigger the bootstrap process by accessing the portal configuration interface and selecting the "Apply Bootstrap" option. This capability proves valuable when updating existing configurations or when troubleshooting bootstrap-related issues.

To manually execute bootstrap processing, navigate to System::Portals, locate your custom portal, and click the "Apply Bootstrap" button. The system will display processing results, including any errors encountered during object creation or updates. Successful processing results in a summary showing the number of objects created or modified in each category.

Bootstrap Configuration Best Practices

When designing bootstrap configurations, use descriptive names and comprehensive notes for all objects to facilitate future maintenance and troubleshooting. Organize the YAML file with consistent indentation and logical grouping of related objects. Consider the interdependencies between objects and structure the file to reflect these relationships clearly.

Test bootstrap configurations in a development environment before deploying to production systems. This testing approach allows you to identify and resolve configuration issues without impacting live portal operations. Additionally, maintain version control for bootstrap files to track changes and enable rollback capabilities when needed.

Portal API

The rXg provides a Portal API for programmatic interaction with portal functionality. The API endpoints are accessed through the /portal_api/ path and support JSON responses using the REST Framework.

Available API Endpoints

The Portal API includes the following controllers:

• /portal_api/logins - Authentication methods (RADIUS login currently implemented)
• /portal_api/account - Current account information and profile management
• /portal_api/devices - Device management for the logged-in account
• /portal_api/usage_plans - Available usage plans
• /portal_api/static_ips - Static IP management
• /portal_api/iot - IoT device management
• /portal_api/lan_parties - LAN party management

Authentication

The Portal API uses session-based authentication. Users must be authenticated through the portal before accessing API endpoints. API requests should include the session cookie from an authenticated portal session.

For programmatic access, accounts can generate API keys through the account endpoint:

# Generate an API key for the logged-in account
curl -X POST https://rxg.domain/portal_api/account/generate_api_key \
  -H "Cookie: _session_id=<session_cookie>"

The response includes the API key and connection details:

{
  "api_key": "generated_api_key_string",
  "fqdn": "rxg.domain",
  "login": "account_username"
}

Login Methods

The logins endpoint provides information about available authentication methods:

# Get available login methods
curl -X GET https://rxg.domain/portal_api/logins/available_methods

Response indicates which login methods are configured:

["account", "free", "shared_credential"]

RADIUS authentication is available through:

# RADIUS authentication
curl -X POST https://rxg.domain/portal_api/logins/radius \
  -H "Content-Type: application/json" \
  -d '{
    "realm": "radius_realm_name",
    "login": "username",
    "password": "password"
  }'

Account Information

Retrieve and update account information for the logged-in user:

# Get current account info
curl -X GET https://rxg.domain/portal_api/account \
  -H "Cookie: _session_id=<session_cookie>"

The response includes account details and usage plan information:

{
  "id": 123,
  "login": "username",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "usage_plan": {
    "id": 1,
    "name": "Standard Plan",
    "account_group": {"id": 1, "name": "Guests"},
    "time_plan": {"id": 1, "name": "24 Hour Access"},
    "quota_plan": {"id": 1, "name": "5GB Daily"}
  }
}

API Response Format

All API endpoints return JSON responses. Successful operations return HTTP 200 status codes. Errors return appropriate HTTP status codes with descriptive messages:

• 400 - Bad request or invalid parameters
• 404 - Resource not found
• 405 - Method not allowed or not implemented

Note: Some login methods (account, free, shared_credential) may return "Not currently implemented" depending on the rXg configuration. RADIUS authentication is fully implemented.

Template Variables and Helpers

The rXg portal template system provides access to contextual variables and helper methods for dynamic content generation. These are available in ERB templates within your custom portal.

Instance Variables

The portal controller sets up several instance variables that are available in templates:

• @account - The authenticated user's Account record (nil if not logged in)
• @login_session - The current LoginSession record with connection details
• @captive_portal - The current CaptivePortal configuration
• @landing_portal - The current LandingPortal configuration (if applicable)

Account Information

Access authenticated user information through the @account variable:

<div class="welcome-section">
  <% if @account %>
    <h2>Welcome back, <%= @account.first_name || @account.login %>!</h2>
    <p>Account: <%= @account.login %></p>
    <% if @account.email.present? %>
      <p>Email: <%= @account.email %></p>
    <% end %>
  <% else %>
    <h2>Welcome to our network!</h2>
    <p>Please authenticate to access internet services.</p>
  <% end %>
</div>

Login Session Information

The @login_session variable provides network session details:

<div class="connection-details">
  <% if @login_session %>
    <h3>Your Connection Details</h3>
    <p><strong>IP Address:</strong> <%= @login_session.ip %></p>
    <p><strong>MAC Address:</strong> <%= @login_session.mac %></p>
    <p><strong>Connected Since:</strong> <%= @login_session.created_at.strftime("%I:%M %p") %></p>
  <% else %>
    <p>Connection details will appear after authentication.</p>
  <% end %>
</div>

Portal Helpers

The portal system provides helper methods for common operations:

Image handling with Portal Mod support: erb <%= portal_image_tag('logo.png', alt: 'Company Logo', class: 'img-fluid') %>

Rendering partials with Portal Mod override support: erb <%= render_portal_partial(:welcome_message) %> <%= render_portal_partial(:login_options) %>

The render_portal_partial helper checks for Portal Mod overrides. If a Portal Mod with a matching Partial Override exists for the portal, the Portal Mod HTML content is rendered instead of the default partial file.

Time-Based Greetings

Create dynamic greetings using Ruby's Time class:

<div class="greeting">
  <% current_time = Time.current %>
  <% if current_time.hour < 12 %>
    <p>Good morning!</p>
  <% elsif current_time.hour < 17 %>
    <p>Good afternoon!</p>
  <% else %>
    <p>Good evening!</p>
  <% end %>
</div>

Portal-Specific Content

Customize content based on which portal is being accessed:

<div class="portal-branding">
  <% if @captive_portal %>
    <h1><%= @captive_portal.name %></h1>
  <% end %>
</div>

Defensive Programming

Always check for variable availability before use to prevent errors:

<%= @account.first_name if @account %>
<%= @login_session.ip if @login_session %>

Portal Inheritance and Controller Architecture

Custom portals follow a controller inheritance hierarchy: ApplicationController BasePortalController (shared portal logic) PortalController (main captive portal functionality) Portal::DefaultController (default portal) Portal::<CustomName>Controller (your custom portal)

This architecture allows custom portals to: - Override specific actions while inheriting base functionality - Add new controller actions via Portal Mods - Access all rXg helper methods and models - Implement custom authentication flows

Advanced Sync and Deployment

The rXg portal system provides sophisticated deployment and synchronization capabilities that enable automated portal updates from external sources. These advanced deployment methods facilitate development workflows, version control integration, and automated distribution of portal updates across multiple rXg installations.

Git Repository Integration

Git integration enables direct deployment of portals from version control repositories, supporting both public repositories and private repositories with authentication. This integration maintains full version control history and enables automated deployment workflows triggered by repository changes.

To configure Git-based portal deployment, create a new custom portal and select "Git" as the portal source. In the Remote Sync URL field, specify the Git repository URL using either HTTPS or SSH protocols. For public repositories, use HTTPS URLs such as https://github.com/username/hotel-portal.git. Private repositories require SSH URLs like [email protected]:username/private-hotel-portal.git along with SSH key authentication.

For SSH key authentication with private repositories, generate an SSH keypair specifically for the rXg portal deployment. Navigate to System::SSH Keypairs and create a new keypair with a descriptive name like "Hotel Portal Git Access". Copy the public key portion and add it to your Git repository's deploy keys or your user account's SSH keys, depending on your repository hosting platform's requirements.

After configuring the SSH keypair, return to the portal configuration and select the appropriate keypair from the SSH Keypair dropdown. Specify the desired branch or tag in the Git Ref field, using standard Git reference formats such as main, production, v1.2.3, or refs/heads/development.

The automatic sync functionality enables scheduled updates from the Git repository without manual intervention. Configure the Sync Frequency to match your deployment requirements, choosing from hourly updates for active development environments, daily updates for staging systems, or weekly updates for production deployments. When Restart After Sync is enabled, the system automatically restarts the web server after successful synchronization to ensure updated portal files are immediately active.

A comprehensive Git deployment workflow begins with repository preparation. Structure your Git repository to match the rXg portal directory layout, placing assets in appropriate subdirectories and ensuring the bootstrap.yml file is present in the repository root if automated configuration is required. Tag releases using semantic versioning to enable stable production deployments while maintaining development flexibility.

Monitor synchronization status through the portal management interface, which displays the last sync timestamp, current commit hash, and any synchronization errors. Failed synchronizations retain the previous portal version while logging detailed error information for troubleshooting purposes.

HTTP Archive Deployment

HTTP archive deployment enables portal distribution through web-accessible ZIP or TAR archive files, facilitating integration with build systems, content delivery networks, and automated deployment pipelines. This deployment method proves particularly valuable for organizations with existing web-based artifact distribution systems.

Configure HTTP archive deployment by selecting "Archive file via HTTP GET" as the portal source and specifying the archive URL in the Remote Sync URL field. The system supports both HTTP and HTTPS URLs, with HTTPS strongly recommended for production deployments. Archive URLs might resemble https://cdn.company.com/portals/hotel-portal-v1.3.2.zip or https://build.company.com/artifacts/portal-builds/latest.tar.gz.

Authentication options include basic HTTP authentication and SSL client certificate authentication. For basic authentication, configure the Remote Sync Username and Remote Sync Password fields with appropriate credentials. The system securely stores these credentials and includes them in archive retrieval requests.

SSL client certificate authentication provides enhanced security for archive retrieval from enterprise systems. Upload the client certificate through the Client Certificate configuration field, ensuring the certificate includes both the certificate and private key components. The remote server must be configured to accept the specified client certificate for authentication.

Archive processing involves automatic extraction and validation of portal files. The system supports ZIP archives created with standard compression utilities and TAR archives with optional gzip compression. Archives must contain the complete portal directory structure, including all required files and subdirectories.

Design your archive creation process to include version information and validation checks. Consider including a manifest file that lists expected files and their checksums, enabling the rXg system to verify archive integrity after extraction. Implement archive rotation policies to prevent excessive storage consumption while maintaining deployment history.

Scheduled archive deployment follows the same frequency options as Git integration, enabling automated updates from build systems and continuous integration pipelines. Configure appropriate sync frequencies based on your release cadence and testing requirements, typically using daily or weekly schedules for production environments.

rsync Synchronization

rsync synchronization provides efficient, differential file transfer capabilities that minimize bandwidth usage and transfer time by synchronizing only changed files. This deployment method excels in scenarios requiring frequent updates or when working with large portal assets that change incrementally.

Configure rsync deployment by selecting "rsync" as the portal source and specifying the rsync source path in the Remote Sync URL field. rsync URLs follow the format user@hostname:/path/to/portal/ for SSH-based transfers or rsync://hostname/module/path for rsync daemon connections. For example, a development server synchronization might use [email protected]:/var/www/portals/hotel/ as the source path.

Authentication options include SSH key authentication and password authentication. SSH key authentication provides secure, automated access without interactive password prompts. Configure SSH key authentication using the same keypair management system used for Git integration, ensuring the public key is installed in the authorized_keys file on the source server.

Password authentication requires configuration of the Remote Sync Username and Remote Sync Password fields. While simpler to configure than key-based authentication, password authentication requires careful credential management and may not be suitable for automated deployments in high-security environments.

rsync deployment excels at maintaining exact directory synchronization, including file permissions, timestamps, and directory structures. The system uses rsync options that preserve file metadata while efficiently transferring only modified content. This efficiency makes rsync ideal for portals with large asset collections or frequent incremental updates.

Advanced rsync configuration options include bandwidth throttling to prevent synchronization operations from impacting network performance. Configure bandwidth limits appropriate for your network capacity and usage patterns, typically setting limits during peak usage hours while allowing full bandwidth utilization during maintenance windows.

Implement selective synchronization by configuring rsync include and exclude patterns on the source server. This capability enables synchronization of specific portal components while excluding development files, temporary content, or environment-specific configurations. Maintain separate rsync configurations for different deployment environments to ensure appropriate file selection for each target system.

Monitor rsync operations through detailed logging that captures transferred files, bandwidth utilization, and synchronization duration. Use this information to optimize synchronization schedules and identify potential performance improvements in portal asset organization or network configuration.

Portal Modification Security

Portal Mods include several security features: - ERB Template Validation: Syntax checking prevents broken portals - Controller Action Sandboxing: Ruby code validation before execution - Image Upload Restrictions: File type and size validation (20MB max) - XSS Prevention: Automatic HTML sanitization in Rich Text mode - Portal Isolation: Mods only affect specified portals

Performance Optimization

The rXg portal system implements comprehensive performance optimization strategies that ensure responsive user experiences even under high-traffic conditions. These optimizations encompass caching mechanisms, asset processing, load distribution, and resource management techniques that automatically adapt to usage patterns and system capacity.

Caching Strategies and Implementation

The portal system employs multi-layered caching strategies that significantly improve response times and reduce server load. Production mode enables comprehensive caching of rendered pages, processed templates, and database queries, resulting in sub-second response times for authenticated users and near-instantaneous responses for cached content.

Page-level caching stores complete rendered HTML output for frequently accessed portal pages, eliminating the need to process templates and execute database queries for subsequent requests. The system intelligently invalidates cached pages when portal modifications occur or when underlying data changes, ensuring users always receive current content while benefiting from caching performance improvements.

Template compilation caching pre-processes ERB templates into executable Ruby code, eliminating template parsing overhead during request processing. This optimization proves particularly beneficial for complex templates with extensive conditional logic or data manipulation operations. Template caches automatically refresh when template files change, maintaining development flexibility while maximizing runtime performance.

Database query caching reduces database load by storing frequently executed query results in high-speed memory storage. The system identifies repeatable queries such as policy lookups, user authentication checks, and configuration retrievals, caching results for configurable time periods. Query cache invalidation occurs automatically when underlying data changes, preventing stale data issues while maximizing cache effectiveness.

Development mode deliberately disables caching mechanisms to facilitate rapid development and testing cycles. In development mode, every request processes templates fresh from disk, executes database queries without caching, and reflects file system changes immediately. This behavior enables developers to see modifications instantly without manual cache clearing or server restarts.

The asset pipeline implements sophisticated asset processing and caching that optimizes CSS, JavaScript, and image resources for web delivery. CSS preprocessing combines multiple stylesheet files, processes Sass/SCSS syntax, applies vendor prefixes, and minifies output for reduced file sizes and faster loading times. JavaScript processing concatenates multiple script files, applies compression algorithms, and implements dead code elimination to minimize client-side loading requirements.

Image optimization automatically processes uploaded images to generate multiple size variants optimized for different display contexts. The system creates thumbnail, medium, and full-resolution versions of uploaded images while applying compression algorithms that maintain visual quality while reducing file sizes. WebP format generation provides modern browsers with highly optimized image formats while maintaining JPEG/PNG fallbacks for legacy browser compatibility.

Load Balancing and High Availability

rXg cluster configurations implement automatic load balancing that distributes portal requests across multiple cluster nodes while maintaining session consistency and failover capabilities. Portal files replicate automatically across all cluster nodes, ensuring consistent user experiences regardless of which node services individual requests.

Session affinity mechanisms maintain user session consistency across load-balanced requests while enabling failover to alternative nodes when primary nodes become unavailable. The system stores session data in shared storage accessible by all cluster nodes, preventing session loss during node failures and enabling seamless user experience continuity.

Automatic failover monitoring continuously assesses node health and availability, redirecting traffic away from problematic nodes while maintaining service availability. Health checks include portal responsiveness testing, database connectivity verification, and system resource monitoring to ensure comprehensive service availability assessment.

Load distribution algorithms consider node capacity, current request load, and response times when directing new requests to optimal nodes. The system adapts load distribution patterns based on observed performance characteristics and usage patterns, ensuring efficient resource utilization across the entire cluster.

CDN integration capabilities enable distribution of static portal assets through content delivery networks, reducing bandwidth requirements on rXg nodes while improving global access performance. Configure CDN integration by specifying appropriate asset URLs that reference CDN-hosted versions of images, stylesheets, and JavaScript files. The system maintains fallback capabilities to serve assets directly when CDN services become unavailable.

Resource Management and Optimization

Memory management optimization ensures efficient resource utilization even during peak usage periods. The portal system implements garbage collection tuning, object pooling, and memory leak prevention mechanisms that maintain consistent performance regardless of request volume or session duration.

Database connection pooling optimizes database resource utilization by maintaining reusable connection pools that serve multiple concurrent requests without connection establishment overhead. Connection pool sizing automatically adjusts based on observed usage patterns while maintaining sufficient capacity for peak demand periods.

Asset delivery optimization includes HTTP/2 server push capabilities that proactively deliver critical CSS and JavaScript resources before browsers request them, reducing perceived page loading times. The system identifies critical rendering path resources and implements push strategies that improve user experience without overwhelming client connections.

Bandwidth optimization techniques include response compression using gzip algorithms that reduce transfer sizes for HTML, CSS, and JavaScript content. The system automatically negotiates compression capabilities with client browsers and applies appropriate compression levels that balance transfer speed improvements with server processing requirements.

Monitoring and performance analytics provide detailed insights into portal performance characteristics, enabling identification of optimization opportunities and capacity planning. Performance metrics include response time distributions, cache hit ratios, database query performance, and resource utilization patterns that inform optimization decisions and capacity management strategies.

Debugging and Troubleshooting

Effective debugging and troubleshooting of custom portals requires systematic approaches to identifying, diagnosing, and resolving issues that can arise during portal development, deployment, and operation. The rXg system provides comprehensive diagnostic tools and logging capabilities that facilitate rapid issue resolution while maintaining system stability and user experience quality.

Common Issues and Resolution Strategies

Template errors represent the most frequent category of portal issues, typically manifesting as ERB syntax errors, undefined variable references, or missing helper method calls. When template errors occur, the portal system displays detailed error messages in development mode that include the specific template file, line number, and error description. Production mode suppresses detailed error information to prevent information disclosure while logging complete error details for administrative review.

To resolve template errors systematically, begin by switching to development mode if the issue appeared in production. Development mode provides immediate error feedback without caching interference, enabling rapid iteration and testing of potential solutions. Examine the error message for specific syntax issues such as missing closing tags, unmatched parentheses, or incorrect ERB syntax patterns.

Variable availability issues occur when templates reference variables that are not properly initialized or are unavailable in the current context. Common variable issues include referencing current_user before authentication, accessing policy information without proper user assignment, or using helper methods that require specific portal configurations. Implement defensive programming techniques by checking variable availability before use: <%= current_user.name if current_user %> instead of direct references that can cause errors when variables are nil.

Asset pipeline issues typically manifest as missing stylesheets, broken JavaScript functionality, or images that fail to load. These issues often result from incorrect asset path references, missing asset compilation, or web server restart requirements. Verify asset pipeline configuration by examining the Rails logs for asset compilation messages and ensuring all referenced assets exist in the correct directory locations.

When assets fail to load, check the browser's developer tools network tab to identify specific failed requests and their associated error codes. HTTP 404 errors indicate missing files or incorrect path references, while HTTP 500 errors suggest server-side processing issues that require log file examination.

Portal loading failures can result from various causes including template errors, missing controller actions, incorrect routing configuration, or server resource constraints. Begin troubleshooting by accessing the portal URL directly and observing any error messages or unexpected redirections. Examine the Rails logs for request processing information and any error messages associated with the failed requests.

Permission issues often prevent portal file access, deployment operations, or administrative functions. These issues typically result from incorrect SSH key configuration, missing administrative role assignments, or file system permission problems. Verify SSH access by attempting direct command-line connection to the rXg system and confirming access to the portals directory. Check administrative role configurations to ensure appropriate permissions are assigned for the intended operations.

Comprehensive Debug Tools and Techniques

Development mode serves as the primary debugging environment for portal development, providing detailed error messages, stack traces, and immediate file change reflection without caching interference. When debugging complex issues, always ensure the system operates in development mode to eliminate caching variables and enable maximum diagnostic information availability.

The Rails console provides direct access to the underlying Ruby on Rails framework, enabling interactive debugging, data inspection, and system state examination. Access the console through SSH connection to the rXg system and executing the rails console command from the portal application directory. Use the console to inspect database records, test helper methods, and examine variable states that may contribute to portal issues.

Logging infrastructure captures comprehensive information about portal operations, including request processing, database queries, template rendering, and error occurrences. Rails logs are accessible through the administrative interface or via direct file system access through SSH. Log analysis tools can help identify patterns, performance bottlenecks, and recurring errors that may not be immediately apparent during manual testing.

Template inspection capabilities allow examination of compiled template output, including the Ruby code generated from ERB templates and the final HTML output sent to browsers. This inspection proves valuable when debugging complex template logic or when template behavior does not match expectations.

Asset pipeline debugging involves examining asset compilation processes, identifying missing dependencies, and verifying correct asset path generation. The Rails asset pipeline provides detailed debugging information when configured appropriately, including asset dependency graphs, compilation timestamps, and error messages for failed asset processing operations.

Browser-based debugging tools complement server-side debugging by providing client-side perspective on portal behavior. Use browser developer tools to examine HTTP requests, response headers, JavaScript console messages, and CSS application. Network monitoring capabilities help identify slow-loading resources, failed requests, and caching behavior that may impact user experience.

Development and Deployment Best Practices

Establish systematic testing procedures that begin with development mode validation before advancing to production deployment. This approach ensures issues are identified and resolved in environments that facilitate debugging while preventing production disruptions that could impact end users.

Implement version control systems for all portal files, including templates, assets, controller code, and configuration files. Version control provides rollback capabilities when issues arise, enables collaboration among multiple developers, and maintains audit trails for all portal modifications. Use branching strategies that isolate development work from stable production versions while facilitating controlled integration of new features and modifications.

Maintain comprehensive backup strategies that include both portal files and associated configuration data. Regular backups enable rapid recovery from significant issues while providing testing environments for complex modifications or upgrades. Document backup procedures and test restoration processes to ensure backup reliability when needed.

Establish cross-browser and cross-device testing protocols that verify portal functionality across the range of client devices and browsers used by your user population. Different browsers may handle CSS, JavaScript, and HTML differently, requiring testing across major browser families including Chrome, Firefox, Safari, and Edge. Mobile device testing ensures portal accessibility and functionality on smartphones and tablets that may represent significant portions of user traffic.

Implement performance monitoring that tracks portal response times, resource utilization, and user experience metrics both during development and after deployment. Performance monitoring helps identify optimization opportunities while detecting degradation that may result from configuration changes or increased usage levels.

Develop documentation standards that capture portal architecture decisions, customization approaches, and operational procedures. Comprehensive documentation facilitates troubleshooting by providing context for design decisions while enabling other administrators or developers to understand and maintain portal implementations effectively.