Feature Flags Management

Feature flags in Karrio Insiders allow you to control which capabilities are available in your platform. This guide covers how to manage feature flags, understand their impact, and configure them for different use cases.

Overview

Feature flags provide:

Granular Control: Enable or disable specific features without code changes
Progressive Rollout: Test new features with selected users or organizations
License Management: Control feature access based on subscription tiers
Performance Optimization: Disable unused features to improve performance

Available Feature Flags

Core Platform Features

Multi Organizations

Flag: MULTI_ORGANIZATIONS
Default: True
Description: Enables multi-tenant organization management
Impact: When disabled, the platform operates in single-organization mode

Admin Dashboard

Flag: ADMIN_DASHBOARD
Default: True
Description: Provides access to the platform administration interface
Impact: When disabled, the /admin route and admin menu items are hidden

Audit Logging

Flag: AUDIT_LOGGING
Default: False
Description: Tracks all system activities for compliance and security
Impact: When enabled, all API calls and user actions are logged

User Management Features

Flag: ALLOW_SIGNUP
Default: True
Description: Enables public user registration
Impact: When disabled, only administrators can create user accounts

Flag: ALLOW_ADMIN_APPROVED_SIGNUP
Default: False
Description: Requires admin approval for new user registrations
Impact: New users enter a pending state until approved

Multi Account

Flag: ALLOW_MULTI_ACCOUNT
Default: False
Description: Allows users to belong to multiple organizations
Impact: Users can switch between different organization contexts

Business Features

Orders Management

Flag: ORDERS_MANAGEMENT
Default: True
Description: Enables e-commerce order fulfillment features
Impact: Shows/hides the Orders section and related APIs

Documents Management

Flag: DOCUMENTS_MANAGEMENT
Default: True
Description: Enables document generation and management
Impact: Controls access to shipping labels, invoices, and customs documents

Workflow Management

Flag: WORKFLOW_MANAGEMENT
Default: True
Description: Enables automation rules and workflow engine
Impact: Shows/hides workflow configuration and execution

Apps Management

Flag: APPS_MANAGEMENT
Default: True
Description: Enables third-party app integrations
Impact: Controls access to the app marketplace and OAuth features

Advanced Features

Data Import/Export

Flag: DATA_IMPORT_EXPORT
Default: True
Description: Enables bulk data operations
Impact: Shows/hides import/export functionality in the UI

Advanced Analytics

Flag: ADVANCED_ANALYTICS
Default: False
Description: Enables detailed analytics and reporting
Impact: Unlocks advanced dashboards and data visualization

Persist SDK Tracing

Flag: PERSIST_SDK_TRACING
Default: False
Description: Stores detailed API traces for debugging
Impact: Increases storage usage but provides detailed diagnostics

Configuration Methods

1. Admin Dashboard Configuration

The easiest way to manage feature flags:

Navigate to Admin → Platform
Click the edit icon next to Features
Toggle features on/off using the switches
Click Save Changes

Changes take effect immediately for new sessions.

2. Environment Variables

Configure features at deployment time:

.env file
1MULTI_ORGANIZATIONS=True
2ADMIN_DASHBOARD=True
3AUDIT_LOGGING=False
4ALLOW_SIGNUP=True
5ALLOW_ADMIN_APPROVED_SIGNUP=False
6ALLOW_MULTI_ACCOUNT=False
7ORDERS_MANAGEMENT=True
8DOCUMENTS_MANAGEMENT=True
9DATA_IMPORT_EXPORT=True
10WORKFLOW_MANAGEMENT=True
11APPS_MANAGEMENT=True
12ADVANCED_ANALYTICS=False
13PERSIST_SDK_TRACING=False

3. Django Settings

For more complex configurations:

settings/custom.py
1FEATURE_FLAGS = {
2    'MULTI_ORGANIZATIONS': os.getenv('MULTI_ORGANIZATIONS', 'True') == 'True',
3    'ADMIN_DASHBOARD': os.getenv('ADMIN_DASHBOARD', 'True') == 'True',
4    'AUDIT_LOGGING': os.getenv('AUDIT_LOGGING', 'False') == 'True',
5    # ... other flags
6}
7
8# Conditional feature loading
9if FEATURE_FLAGS['AUDIT_LOGGING']:
10    INSTALLED_APPS += ['karrio.server.audit']
11    MIDDLEWARE += ['karrio.server.audit.middleware.AuditMiddleware']

4. Runtime Configuration (Constance)

Feature flags can be modified at runtime through Django Constance:

Access in code
1from constance import config
2
3if config.ORDERS_MANAGEMENT:
4    # Show orders functionality
5    pass

Plugin Registry

In addition to feature flags, Karrio supports enabling/disabling carrier plugins:

Viewing Available Plugins

Go to Admin → Platform
Scroll to Registry Plugins section
View all available carrier integrations

Enabling/Disabling Plugins

Toggle individual carrier plugins:

Enable all plugins by default
1ENABLE_ALL_PLUGINS_BY_DEFAULT=True
2
3# Or control individually
4FEDEX_ENABLED=True
5UPS_ENABLED=True
6DHL_EXPRESS_ENABLED=True
7USPS_ENABLED=False

Use Cases

1. Tiered Subscriptions

Create different feature sets for subscription tiers:

Subscription tiers configuration
1SUBSCRIPTION_FEATURES = {
2    'starter': {
3        'MULTI_ORGANIZATIONS': False,
4        'ADVANCED_ANALYTICS': False,
5        'WORKFLOW_MANAGEMENT': False,
6        'APPS_MANAGEMENT': False,
7    },
8    'professional': {
9        'MULTI_ORGANIZATIONS': True,
10        'ADVANCED_ANALYTICS': False,
11        'WORKFLOW_MANAGEMENT': True,
12        'APPS_MANAGEMENT': True,
13    },
14    'enterprise': {
15        'MULTI_ORGANIZATIONS': True,
16        'ADVANCED_ANALYTICS': True,
17        'WORKFLOW_MANAGEMENT': True,
18        'APPS_MANAGEMENT': True,
19        'AUDIT_LOGGING': True,
20    }
21}

2. Gradual Feature Rollout

Test new features with specific organizations:

Organization-specific features
1def get_features_for_org(organization):
2    base_features = get_default_features()
3    
4    # Beta testers get early access
5    if organization.is_beta_tester:
6        base_features['NEW_FEATURE'] = True
7    
8    # Custom features per organization
9    custom_features = organization.metadata.get('features', {})
10    base_features.update(custom_features)
11    
12    return base_features

3. Performance Optimization

Disable unused features for better performance:

Minimal configuration for high-performance API-only deployment
1MULTI_ORGANIZATIONS=False
2ADMIN_DASHBOARD=False
3ORDERS_MANAGEMENT=False
4DOCUMENTS_MANAGEMENT=True  # Keep only essential features
5WORKFLOW_MANAGEMENT=False
6APPS_MANAGEMENT=False
7ADVANCED_ANALYTICS=False
8PERSIST_SDK_TRACING=False

4. Compliance Requirements

Enable features based on regulatory needs:

GDPR compliance configuration
1if organization.country in EU_COUNTRIES:
2    features['AUDIT_LOGGING'] = True
3    features['DATA_EXPORT'] = True
4    features['RIGHT_TO_ERASURE'] = True
5
6# Healthcare compliance
7if organization.industry == 'healthcare':
8    features['AUDIT_LOGGING'] = True
9    features['ENCRYPTION_AT_REST'] = True
10    features['ACCESS_CONTROLS'] = True

Feature Dependencies

Some features depend on others:

Feature Dependencies:

Multi Account requires Multi Organizations to be enabled
Shipping Rules requires Workflow Management to be enabled
Advanced Analytics may require additional infrastructure setup
Audit Logging requires configured log storage

Dependency Rules

Multi Account requires Multi Organizations
Shipping Rules requires Workflow Management
Advanced Analytics requires additional infrastructure
Audit Logging requires configured log storage

API Access Control

Feature flags also control API endpoint availability:

API endpoint conditional availability
1@require_feature('ORDERS_MANAGEMENT')
2class OrderViewSet(viewsets.ModelViewSet):
3    """Only available when ORDERS_MANAGEMENT is enabled"""
4    pass
5
6# GraphQL field conditional
7class Query:
8    @require_feature('ADVANCED_ANALYTICS')
9    def analytics(self, info):
10        """Only available with ADVANCED_ANALYTICS flag"""
11        pass

Checking Features via API

1query {
2  platform {
3    features {
4      multiOrganizations
5      ordersManagement
6      workflowManagement
7      advancedAnalytics
8    }
9  }
10}

Response:

1{
2  "data": {
3    "platform": {
4      "features": {
5        "multiOrganizations": true,
6        "ordersManagement": true,
7        "workflowManagement": true,
8        "advancedAnalytics": false
9      }
10    }
11  }
12}

Frontend Feature Flags

Access feature flags in the dashboard:

Using feature flags in React components
1import { useFeatureFlags } from '@karrio/hooks/feature-flags';
2
3function Navigation() {
4  const features = useFeatureFlags();
5  
6  return (
7    <nav>
8      <Link to="/shipments">Shipments</Link>
9      {features.ordersManagement && (
10        <Link to="/orders">Orders</Link>
11      )}
12      {features.workflowManagement && (
13        <Link to="/workflows">Workflows</Link>
14      )}
15      {features.adminDashboard && user.isStaff && (
16        <Link to="/admin">Admin</Link>
17      )}
18    </nav>
19  );
20}

Conditional UI Rendering

Feature-gated components
1function DashboardPage() {
2  const features = useFeatureFlags();
3  
4  return (
5    <div>
6      <ShipmentWidget />
7      
8      <FeatureGate feature="ordersManagement">
9        <OrdersWidget />
10      </FeatureGate>
11      
12      <FeatureGate 
13        feature="advancedAnalytics"
14        fallback={<BasicAnalytics />}
15      >
16        <AdvancedAnalytics />
17      </FeatureGate>
18    </div>
19  );
20}

Monitoring Feature Usage

Track which features are being used:

1-- Feature usage query
2SELECT 
3  feature_name,
4  COUNT(DISTINCT user_id) as unique_users,
5  COUNT(*) as total_uses,
6  DATE(created_at) as date
7FROM audit_logs
8WHERE action LIKE 'feature.%'
9GROUP BY feature_name, DATE(created_at)
10ORDER BY date DESC, total_uses DESC;

Best Practices

1. Start Conservative

Begin with minimal features enabled:

Enable only what you need
Add features as requirements grow
Monitor performance impact

2. Document Feature Sets

Maintain clear documentation:

feature-sets.yml
1production:
2  multi_organizations: true
3  audit_logging: true
4  advanced_analytics: false
5
6staging:
7  multi_organizations: true
8  audit_logging: true
9  advanced_analytics: true  # Testing new feature
10
11development:
12  all_features: true  # Enable everything for dev

3. Test Feature Combinations

Ensure features work well together:

Test with different flag combinations
Verify UI consistency
Check API compatibility

4. Plan for Migration

When changing features:

Announce changes in advance
Provide migration guides
Offer grace periods
Support data export if disabling features

Troubleshooting

Feature Not Appearing

Check Configuration

Verify environment variable
1echo $FEATURE_NAME_ENABLED
2
3# Check Django settings
4docker exec -it karrio-api python manage.py shell
5>>> from django.conf import settings
6>>> settings.FEATURE_FLAGS

Clear Cache

1docker exec -it karrio-api python manage.py clear_cache

Restart Services

1docker compose restart api worker dashboard

Performance Issues

If enabling features causes performance problems:

Check Resource Usage
```
1docker stats
```

Review Logs

1docker compose logs -f api | grep ERROR

Disable Non-Essential Features
- Start with PERSIST_SDK_TRACING
- Consider disabling ADVANCED_ANALYTICS
- Reduce audit log retention

Feature Conflicts

Some features may conflict:

ALLOW_SIGNUP=False with ALLOW_ADMIN_APPROVED_SIGNUP=True
MULTI_ORGANIZATIONS=False with ALLOW_MULTI_ACCOUNT=True

The system will log warnings for invalid combinations.

Security Considerations

Sensitive Features

These features have security implications:

Audit Logging
- Stores sensitive user actions
- Requires secure log storage
- Consider retention policies
Data Import/Export
- Can expose bulk data
- Implement access controls
- Log all export activities
Apps Management
- Third-party code execution
- OAuth token management
- Review app permissions

Recommendations

Enable AUDIT_LOGGING for compliance
Restrict DATA_IMPORT_EXPORT to admins
Review APPS_MANAGEMENT permissions regularly
Use ALLOW_ADMIN_APPROVED_SIGNUP for controlled access

Next Steps

Configure Carrier Network - Set up shipping providers
Set Up Workflows - Automate with feature flags
Manage Billing - Tie features to subscriptions

Getting Started