Subscription Upgrade Script - Usage Guide¶

The upgrade-subscription.sh script allows upgrading user subscriptions with support for both CLI and Docker execution patterns.

Execution Environments¶

The script automatically detects and adapts to three execution environments:

CLI Execution: Running locally with uv and local environment
Docker Inside: Running inside the Docker container
Docker Outside: Running via docker exec to an existing container

Usage Examples¶

CLI Execution (Local Development)¶

# Basic upgrade - user 123 to STARTER monthly plan
./scripts/upgrade-subscription.sh 123 STARTER

# Upgrade to TRADER with annual billing
./scripts/upgrade-subscription.sh 123 TRADER --billing-period ANNUAL

# Upgrade to PRO with auto-confirmation (no prompts)
./scripts/upgrade-subscription.sh 456 PRO --confirm

# Using environment variables
USER_ID=123 PLAN_TIER=STARTER BILLING_PERIOD=ANNUAL ./scripts/upgrade-subscription.sh

# Auto-confirm using environment variable
USER_ID=789 PLAN_TIER=PRO CONFIRM=yes ./scripts/upgrade-subscription.sh

Docker Execution (Production)¶

# Execute via docker exec (script auto-detects container)
./scripts/upgrade-subscription.sh 123 TRADER

# Execute with specific container name
./scripts/upgrade-subscription.sh 456 PRO --container my_katbot_api

# Execute inside container (if you're already inside)
./scripts/upgrade-subscription.sh 789 STARTER --confirm

Administrative Usage¶

# Batch upgrades using environment variables in a loop
for user_id in 123 456 789; do
    USER_ID=$user_id PLAN_TIER=STARTER CONFIRM=yes ./scripts/upgrade-subscription.sh
done

# Upgrade with detailed logging
./scripts/upgrade-subscription.sh 123 PRO 2>&1 | tee upgrade-log.txt

Configuration Options¶

Command Line Arguments¶

USER_ID: ID of the user to upgrade (required)
PLAN_TIER: Target plan tier - STARTER, TRADER, or PRO (required)
-b, --billing-period: Billing period - MONTHLY or ANNUAL (default: MONTHLY)
-c, --confirm: Skip confirmation prompt
--container: Docker container name (default: katbot_api)
-h, --help: Show help message

Environment Variables¶

USER_ID: User ID to upgrade (required if not provided as argument)
PLAN_TIER: Target plan tier (required if not provided as argument)
BILLING_PERIOD: Billing period (default: MONTHLY)
CONFIRM: Set to "yes" or "--confirm" to skip confirmation
DOCKER_CONTAINER_NAME: Docker container name (default: katbot_api)

Plan Information¶

Plan Hierarchy¶

Upgrades are only allowed to higher tiers: - FREE → STARTER, TRADER, or PRO - STARTER → TRADER or PRO
- TRADER → PRO - PRO → (already at highest tier)

Plan Features¶

STARTER: 15 recommendations, 15 paper trades, 5 live trades
TRADER: Enhanced trading capabilities with more limits
PRO: Full feature access with priority support and SLA

Billing Periods¶

MONTHLY: Monthly billing cycle
ANNUAL: Annual billing cycle (typically discounted)

Logging¶

CLI Mode: Logs to PROJECT_DIR/logs/upgrade-subscription.log
Docker Mode: Logs to container's /tmp/upgrade-subscription.log
Docker Exec Mode: Copies logs from container to host after execution

Environment Detection¶

The script automatically detects the execution environment:

Docker Inside: Checks for /.dockerenv file
Docker Outside: Checks if Docker is available and container exists
CLI: Falls back to local execution

Files¶

scripts/upgrade-subscription.sh: Main script (supports all environments)
scripts/docker-upgrade-subscription.sh: Docker container wrapper

Error Handling¶

The script provides comprehensive error handling:

Validation: Checks for required arguments and valid plan tiers
User Verification: Confirms user exists before attempting upgrade
Upgrade Path Validation: Prevents downgrades, only allows upgrades to higher tiers
Exit Codes: Returns appropriate exit codes for success (0) or failure (non-zero)
Logging: All operations are logged with timestamps for auditing

Security Considerations¶

The script requires proper authentication to access the database
All operations are logged for audit purposes
Confirmation prompts prevent accidental upgrades (can be bypassed with --confirm)
Input validation prevents injection attacks

Integration with Other Systems¶

This script can be integrated with: - Payment processing systems (call after successful payment) - Customer support tools (manual upgrades) - Automated marketing campaigns (promotional upgrades) - Admin dashboards (bulk operations)

Troubleshooting¶

Common Issues¶

"User not found": Verify the user ID exists in the database
"Cannot downgrade": Use appropriate downgrade procedures or wait for expiration
"Already on plan": User is already subscribed to the target plan tier
Docker connection issues: Ensure the container is running and accessible

Debugging¶

Enable verbose logging by checking the log files:

# View recent upgrade logs
tail -f logs/upgrade-subscription.log

# Check for errors in specific upgrade
grep "ERROR" logs/upgrade-subscription.log