Skip to content

Admin Guide

Jump to bottom
VetheonGames edited this page Sep 20, 2025 · 1 revision

Admin Guide

Comprehensive administrative guide for managing Source-License platform operations, users, licenses, and system configuration.

🚪 Admin Panel Access

Initial Login

  1. Access URL: http://localhost:4567/admin (or your domain/admin)
  2. Default Credentials: Set in your .env file during installation 
    ADMIN_EMAIL=admin@yourdomain.com
ADMIN_PASSWORD=your_secure_admin_password
  3. First Time Setup: Change default password immediately after first login

Admin Account Security

Password Requirements

  • Minimum 12 characters
  • Mix of uppercase, lowercase, numbers, and symbols
  • Cannot reuse last 5 passwords
  • Must change every 90 days (configurable)

Two-Factor Authentication

Enable 2FA for enhanced security:

  1. Go to Admin Profile → Security Settings
  2. Click Enable Two-Factor Authentication
  3. Scan QR code with authenticator app
  4. Enter verification code to confirm

📊 Dashboard Overview

The admin dashboard provides real-time insights into your licensing platform:

Key Metrics

  • Total Revenue: Complete sales overview
  • Active Licenses: Currently valid licenses
  • Total Customers: Registered user count
  • Monthly Sales: Revenue trends
  • License Activations: Usage statistics
  • Pending Orders: Orders awaiting processing

Quick Actions

  • Generate License: Create instant licenses
  • Create Product: Add new software products
  • View Recent Orders: Monitor latest transactions
  • System Health: Check application status

Activity Feed

  • Recent license activations
  • New customer registrations
  • Payment notifications
  • System alerts and warnings

👥 User Management

Customer Management

Viewing Customers

Navigate to Admin → Customers to view all registered users:

Customer List Features:

  • Search by email, name, or ID
  • Filter by status (active, inactive, suspended)
  • Sort by registration date, last login, license count
  • Export customer data

Customer Details

Click any customer to view detailed information:

  • Profile Information: Name, email, registration date
  • Account Status: Active, inactive, or suspended
  • License History: All licenses owned by customer
  • Order History: Complete purchase records
  • Login Activity: Recent login attempts and locations

Customer Actions

Account Management:

  • Edit Profile: Update customer information
  • Reset Password: Force password reset
  • Suspend Account: Temporarily disable account
  • Delete Account: Permanently remove customer (cascade deletes)
  • Email Customer: Send notifications or support messages

License Operations:

  • View Licenses: All customer licenses
  • Generate License: Create manual license for customer
  • Transfer License: Move license to different customer
  • Revoke License: Deactivate specific license

Admin Management

Creating Admin Accounts

Navigate to Admin → Admins → New Admin:

  1. Basic Information:

    Email: admin@company.com
Name: John Administrator

  2. Security Settings:

    Temporary Password: [Generate secure password]
Require Password Change: ✓ (recommended)
Account Status: Active

  3. Role Assignment:

    • Super Admin: Full system access
    • Admin: Standard administrative privileges
    • Support: Limited customer support access
    • Custom: Define specific permissions

Admin Permissions

Source-License supports granular permission system:

System Permissions:

  • Manage system settings and configuration
  • Access logs and monitoring tools
  • Manage admin accounts and roles
  • Perform system maintenance

Customer Permissions:

  • View and edit customer accounts
  • Access customer support tools
  • Manage customer licenses
  • Process refunds and chargebacks

Product Permissions:

  • Create and edit products
  • Manage product pricing and features
  • Configure license settings
  • Upload product files

Financial Permissions:

  • View financial reports
  • Process manual payments
  • Manage tax configurations
  • Access revenue analytics

📦 Product Management

Creating Products

Navigate to Admin → Products → New Product:

Basic Product Information

Product Name: My Software Pro
Description: Professional software license
Category: [Select category]
Status: Active

Pricing Configuration

Base Price: $99.00
Setup Fee: $0.00 (optional)
Currency: USD
Tax Configuration: [Select applicable taxes]

License Settings

License Type: One-time purchase / Subscription
Max Activations: 3 (devices per license)
License Duration: Perpetual / 365 days
Trial Period: 30 days (optional)
Grace Period: 7 days (for subscriptions)

Download Files

Upload software files for automatic delivery:

  • Supported Formats: ZIP, EXE, DMG, AppImage, etc.
  • File Size Limit: Configurable (default 500MB)
  • Storage Location: Secure download directory
  • Access Control: Time-limited download links

Advanced Features

License Key Format: XXXX-XXXX-XXXX-XXXX / UUID / Custom
Auto-Generate Licenses: ✓ (on purchase)
Email Delivery: ✓ (send license via email)
API Integration: ✓ (available via REST API)

Product Categories

Organize products into logical categories:

  • Software Licenses: Main applications
  • Plugins & Extensions: Add-ons and plugins
  • Support & Services: Technical support packages
  • Training & Documentation: Educational materials

Bulk Operations

Perform operations on multiple products:

  • Bulk Price Update: Update pricing across products
  • Status Changes: Activate/deactivate multiple products
  • Export Product Data: Generate reports
  • Duplicate Products: Create similar products quickly

🔑 License Management

License Generation

Manual License Creation

Navigate to Admin → Licenses → Generate License:

  1. Product Selection:

    Product: [Select from dropdown]
Quantity: 1-1000 licenses

  2. Customer Assignment:

    Customer Email: customer@example.com
Order Reference: [Optional order ID]

  3. License Configuration:

    Custom Max Activations: [Override product default]
Custom Expiration: [Override product default]
License Notes: [Internal notes]

  4. Delivery Options:

    ✓ Send Email Notification
✓ Generate Download Link
□ Hold for Manual Delivery

Bulk License Generation

For volume licensing or enterprise customers:

  1. Bulk Generation Settings:

    Product: Enterprise Software License
Quantity: 50 licenses
License Key Format: XXXX-XXXX-XXXX-XXXX

  2. Export Options:

    ✓ Generate CSV file
✓ Create PDF report
✓ Email summary to admin

License Operations

License Status Management

Available Actions:

  • Activate: Enable suspended license
  • Suspend: Temporarily disable license
  • Revoke: Permanently disable license
  • Extend: Add time to expiration date
  • Transfer: Move to different customer

Activation Management

Monitor and control license activations:

Activation Details:

  • Machine Fingerprint: Unique device identifier
  • Activation Date: When license was activated
  • IP Address: Activation location
  • System Information: OS, hardware details
  • User Agent: Application information

Activation Actions:

  • View Details: See full activation information
  • Deactivate: Remove activation from device
  • Block Device: Prevent future activations
  • Transfer Activation: Move to different device

License Analytics

Usage Reports

Generate comprehensive license usage reports:

Report Types:

  • Activation Summary: Overall activation statistics
  • Customer Usage: Per-customer activation patterns
  • Geographic Distribution: Activation locations
  • Device Analysis: Hardware and OS statistics
  • Compliance Report: License terms adherence

Export Options:

  • PDF reports for executive summaries
  • CSV data for analysis
  • JSON API for integration
  • Real-time dashboard metrics

💰 Order & Payment Management

Order Processing

Order Dashboard

Navigate to Admin → Orders to manage all transactions:

Order Status Types:

  • Pending: Awaiting payment confirmation
  • Completed: Payment successful, license delivered
  • Failed: Payment processing failed
  • Refunded: Payment returned to customer

Order Details

Click any order to view complete information:

Order Information:

Order ID: #12345
Customer: customer@example.com
Date: 2024-01-15 14:30:00
Status: Completed
Payment Method: Stripe

Items & Pricing:

Product: Software License Pro
Quantity: 1
Unit Price: $99.00
Subtotal: $99.00
Tax: $8.91
Total: $107.91

Payment Details:

Transaction ID: pi_1234567890
Payment Gateway: Stripe
Card Last 4: ****1234
Payment Date: 2024-01-15 14:30:45

Manual Order Processing

For special cases requiring manual intervention:

  1. Create Manual Order:

    Customer Email: customer@example.com
Product: [Select product]
Payment Method: Manual/Bank Transfer/Check
Amount: $99.00

  2. Order Notes:

    Internal Notes: Enterprise customer - annual contract
Customer Notes: License for development team

  3. License Generation:

    ✓ Generate license automatically
✓ Send customer notification
✓ Create activation record

Payment Gateway Management

Stripe Configuration

Configure Stripe payment processing:

  1. API Keys:

    Publishable Key: pk_live_...
Secret Key: sk_live_...
Webhook Secret: whsec_...

  2. Webhook Setup:

    Endpoint URL: https://yourdomain.com/api/webhook/stripe
Events: payment_intent.succeeded, payment_intent.payment_failed

PayPal Configuration

Set up PayPal payment processing:

  1. API Credentials:

    Client ID: your_paypal_client_id
Client Secret: your_paypal_client_secret
Environment: production / sandbox

  2. Webhook Configuration:

    Webhook URL: https://yourdomain.com/api/webhook/paypal
Events: PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.DENIED

Subscription Management

Subscription Dashboard

Monitor recurring billing and subscriptions:

Subscription Status:

  • Active: Currently billing and valid
  • Past Due: Payment failed, in grace period
  • Canceled: Subscription terminated
  • Unpaid: Payment issues, requires attention

Billing Cycle Management

Configure automatic billing for subscription products:

Billing Cycles:

  • Weekly: Every 7 days
  • Monthly: Every 30 days
  • Quarterly: Every 90 days
  • Annually: Every 365 days
  • Custom: Define specific intervals

🏪 E-commerce Features

Shopping Cart Management

Configure shopping cart behavior:

Cart Settings:

Session Timeout: 30 minutes
Guest Checkout: Enabled
Tax Calculation: Automatic
Shipping: Digital delivery only

Discount Codes:

Code: WELCOME10
Discount: 10% off
Valid From: 2024-01-01
Valid Until: 2024-12-31
Usage Limit: 100 uses

Tax Configuration

Tax Settings

Navigate to Admin → Tax Settings:

Enable Taxes: ✓
Display Tax Breakdown: ✓
Tax-Inclusive Pricing: □
Round Tax Amounts: ✓
Auto-Apply Taxes: ✓

Tax Rates

Create and manage tax rates:

Tax Name: Sales Tax
Rate: 8.75%
Status: Active
Description: Local sales tax

Tax Rules

Define when taxes apply:

  • Geographic Rules: Based on customer location
  • Product Rules: Specific products subject to tax
  • Customer Rules: Business vs. consumer taxation

🎨 Customization & Branding

Site Customization

Navigate to Admin → Customize to modify appearance:

Branding

Site Name: Your Company Name
Logo Upload: [Upload company logo]
Favicon: [Upload favicon.ico]
Primary Color: #007bff
Secondary Color: #6c757d

Content Management

Homepage Title: Welcome to Our Software
Homepage Description: Professional licensing solutions
Footer Text: © 2024 Your Company. All rights reserved.

Email Templates

Customize automated email communications:

License Delivery Email:

Subject: Your Software License - Order #{{order_id}}
Template: [HTML email template]
Variables: {{customer_name}}, {{license_key}}, {{download_link}}

Welcome Email:

Subject: Welcome to {{site_name}}
Template: [Customer onboarding template]
Variables: {{customer_name}}, {{account_url}}

Template System

For advanced customization, developers can modify ERB templates:

Template Locations:

  • views/layouts/main_layout.erb: Main site layout
  • views/partials/_navigation.erb: Navigation menu
  • views/index.erb: Homepage template
  • views/cart.erb: Shopping cart page

Note: For detailed template customization instructions, refer to the built-in Code Guide accessible via Admin → Code Guide.

📊 Reports & Analytics

Revenue Reports

Sales Dashboard

Navigate to Admin → Reports → Sales:

Revenue Metrics:

  • Total Revenue: All-time sales
  • Monthly Revenue: Current month sales
  • Average Order Value: Mean transaction amount
  • Revenue Growth: Month-over-month change

Sales Charts:

  • Revenue trends over time
  • Product sales distribution
  • Payment method breakdown
  • Geographic sales distribution

Financial Reports

Generate detailed financial reports:

Report Types:

  • Revenue Summary: High-level financial overview
  • Product Performance: Sales by product
  • Customer Analysis: Revenue per customer
  • Tax Report: Tax collection summary
  • Refund Report: Refund and chargeback tracking

License Analytics

License Usage Reports

Monitor license utilization and compliance:

Usage Metrics:

  • Total Licenses: All generated licenses
  • Active Licenses: Currently valid licenses
  • Activation Rate: Percentage of licenses activated
  • Activation Efficiency: Activations per license

License Distribution:

  • Licenses by product
  • Licenses by customer segment
  • Geographic license distribution
  • License status breakdown

Customer Analytics

Customer Reports

Understand customer behavior and patterns:

Customer Metrics:

  • Customer Acquisition: New registrations
  • Customer Retention: Repeat purchase rate
  • Customer Lifetime Value: Average revenue per customer
  • Churn Rate: Customer attrition

Behavioral Analysis:

  • Login frequency patterns
  • License usage patterns
  • Support ticket correlation
  • Purchase behavior analysis

🔧 System Administration

System Settings

Navigate to Admin → Settings for system configuration:

Application Settings

Site URL: https://yourdomain.com
Admin Email: admin@yourdomain.com
Support Email: support@yourdomain.com
Time Zone: America/New_York
Date Format: MM/DD/YYYY

Security Settings

Force HTTPS: ✓ (production)
Session Timeout: 28800 seconds (8 hours)
Max Login Attempts: 5
Account Lockout Duration: 30 minutes
JWT Token Expiry: 3600 seconds (1 hour)

Email Configuration

SMTP Host: smtp.gmail.com
SMTP Port: 587
SMTP Username: your-email@gmail.com
SMTP Password: [App password]
Enable TLS: ✓

System Maintenance

Database Management

Monitor and maintain database health:

Database Statistics:

  • Total records by table
  • Database size and growth
  • Query performance metrics
  • Connection pool status

Maintenance Operations:

  • Backup Database: Create manual backup
  • Optimize Tables: Improve performance
  • Clean Logs: Remove old log entries
  • Repair Tables: Fix corruption issues

Log Management

Monitor application logs and system events:

Log Categories:

  • Application Logs: General application events
  • Error Logs: Errors and exceptions
  • Security Logs: Authentication and security events
  • Payment Logs: Transaction processing logs

Log Operations:

  • View Logs: Real-time log viewing
  • Download Logs: Export for analysis
  • Clear Logs: Remove old entries
  • Log Rotation: Automatic log management

Backup & Recovery

Automated Backups

Configure automatic backup schedules:

Backup Frequency: Daily
Backup Time: 02:00 AM
Retention Period: 30 days
Backup Location: [Local/Cloud storage]

Backup Contents:

  • Complete database dump
  • Configuration files
  • Upload directories
  • Application logs

Manual Backup

Create immediate backups:

  1. Navigate to Admin → System → Backup
  2. Select backup components: 
    ✓ Database
✓ Configuration
✓ Uploaded files
✓ Logs
  3. Choose compression level and encryption
  4. Download backup file

System Monitoring

Health Checks

Monitor system health and performance:

System Metrics:

  • CPU Usage: Server processor utilization
  • Memory Usage: RAM consumption
  • Disk Space: Storage utilization
  • Database Performance: Query response times

Application Metrics:

  • Response Times: Page load performance
  • Error Rates: Application error frequency
  • Uptime: System availability
  • Active Sessions: Current user sessions

Alerting

Configure alerts for system issues:

Alert Types:

  • High CPU Usage: >80% for 5 minutes
  • Low Disk Space: <10% available
  • Database Errors: Connection failures
  • Payment Failures: Payment processing issues

Notification Methods:

  • Email notifications to admin team
  • Webhook notifications to monitoring services
  • In-app dashboard alerts
  • SMS alerts for critical issues

🆘 Troubleshooting

Common Issues

License Generation Problems

Issue: Licenses not generating automatically Solution:

  1. Check product configuration
  2. Verify order completion status
  3. Review error logs for exceptions
  4. Test manual license generation

Payment Processing Issues

Issue: Payments failing or not completing Solution:

  1. Verify payment gateway credentials
  2. Check webhook configuration
  3. Review payment gateway logs
  4. Test with small transaction

Email Delivery Problems

Issue: License emails not being delivered Solution:

  1. Check SMTP configuration
  2. Verify email templates
  3. Test with manual email send
  4. Check spam/blacklist status

Emergency Procedures

System Recovery

In case of system failure:

  1. Assess Damage: Determine extent of issue
  2. Restore from Backup: Use latest clean backup
  3. Verify Data Integrity: Check database consistency
  4. Test Core Functions: Verify licensing and payments
  5. Notify Stakeholders: Communicate with customers

Security Incident Response

If security breach suspected:

  1. Immediate Actions:

    • Change all admin passwords
    • Revoke all JWT tokens
    • Review recent access logs
    • Block suspicious IP addresses

  2. Investigation:

    • Analyze security logs
    • Check for data modification
    • Review user account changes
    • Document timeline of events

  3. Recovery:

    • Patch security vulnerabilities
    • Restore from clean backup if needed
    • Implement additional security measures
    • Monitor for continued threats

This admin guide provides comprehensive coverage of all administrative functions in Source-License. For technical development information, refer to the Development Guide and the built-in Code Guide accessible through the admin panel.

Clone this wiki locally