Skip to content

Admin GUI Manual

This manual explains how to use the Django Admin interface for managing MyCyclingCity.

Accessing the Admin Interface

  1. Navigate to: http://your-domain/admin/
  2. Log in with your superuser credentials
  3. You'll see the admin dashboard with all available models

Main Sections

The admin interface is organized into the following sections:

MCC Core API & Models

Core functionality for cyclists, groups, and mileage tracking.

Group Types

  • Purpose: Define types of groups (e.g., classes, teams)
  • Key Fields:
  • name: Group type name
  • description: Description of the group type
  • is_active: Enable/disable group type
  • Usage: Create group types before creating groups

Groups

  • Purpose: Manage cycling groups (classes, teams, etc.)
  • Key Fields:
  • name: Group name
  • group_type: Type of group
  • school_name: Associated school
  • distance_total: Total kilometers traveled
  • is_active: Active status
  • Features:
  • View aggregated mileage
  • Track group progress
  • Manage group hierarchy (parent/child groups)

Cyclists

  • Purpose: Manage individual cyclists
  • Key Fields:
  • user: Associated Django user
  • id_tag: RFID tag identifier
  • coin_conversion_factor: Coins per kilometer
  • distance_total: Total kilometers
  • coins_total: Total coins earned
  • Features:
  • Link cyclists to users
  • Configure coin conversion
  • View cycling statistics

Travel Tracks

  • Purpose: Manage travel routes and tracks
  • Key Fields:
  • name: Track name
  • gpx_file: GPX route file
  • distance_km: Track distance
  • milestones: Associated milestones
  • Usage: Upload GPX files to create travel tracks

Milestones

  • Purpose: Define milestones along travel tracks
  • Key Fields:
  • name: Milestone name
  • travel_track: Associated track
  • position_km: Position on track
  • is_locked: Lock status
  • Features:
  • Track group progress toward milestones
  • Award achievements

Events

  • Purpose: Manage cycling events
  • Key Fields:
  • name: Event name
  • start_date: Event start
  • end_date: Event end
  • groups: Participating groups
  • Usage: Create and manage cycling events

IoT Management

Device and firmware management for ESP32 devices.

Devices

  • Purpose: Manage ESP32 tachometer devices
  • Key Fields:
  • name: Device identifier
  • display_name: Human-readable name
  • group: Associated group
  • distance_total: Total device mileage
  • last_active: Last activity timestamp
  • Features:
  • Monitor device status
  • View device statistics
  • Configure device settings

Device Configurations

  • Purpose: Server-side device configuration
  • Key Fields:
  • device: Associated device
  • device_specific_api_key: Device API key
  • send_interval_seconds: Data transmission interval
  • wheel_size: Wheel circumference
  • Features:
  • Configure device parameters remotely
  • API key management
  • Configuration synchronization

Firmware Images

  • Purpose: Manage firmware versions for OTA updates
  • Key Fields:
  • version: Firmware version
  • file: Firmware binary
  • is_active: Active version
  • release_notes: Version notes
  • Usage: Upload firmware for automatic device updates

Device Health

  • Purpose: Monitor device health status
  • Key Fields:
  • device: Associated device
  • status: Health status (online/offline/warning/error)
  • last_heartbeat: Last heartbeat timestamp
  • consecutive_failures: Error count
  • Features:
  • Real-time device monitoring
  • Health status tracking
  • Error reporting

MCC Game Interface

Game room and session management.

Game Rooms

  • Purpose: Manage multiplayer game rooms
  • Key Fields:
  • room_code: Unique room identifier
  • is_active: Room status
  • master_session_key: Master session
  • device_assignments: Cyclist-device mappings
  • Features:
  • View active game rooms
  • Monitor room activity
  • Manage room state

Game Sessions

  • Purpose: Track individual game sessions
  • Key Fields:
  • session_key: Session identifier
  • room_code: Associated room
  • expire_date: Session expiration
  • Features:
  • Monitor active sessions
  • Cleanup expired sessions
  • Debug game state

Kiosk Management

Kiosk device and playlist management.

Kiosk Devices

  • Purpose: Manage kiosk display devices
  • Key Fields:
  • uid: Unique device identifier
  • name: Device name
  • is_active: Active status
  • Usage: Configure kiosk displays

Historical Reports & Analytics

Analyses and reports for historical data.

Analytics Dashboard

  • Purpose: Overview of analyses and statistics
  • Features:
  • Group statistics
  • Mileage trends
  • Time period analyses
  • Export functions
  • Access: /admin/analytics/

Hierarchy Breakdown

  • Purpose: Detailed breakdown of group hierarchy
  • Features:
  • Hierarchical display of groups
  • Aggregated statistics per level
  • Drill-down functionality
  • Access: /admin/analytics/hierarchy/

Session Management

Game session management and monitoring.

Session Dashboard

  • Purpose: Overview of active and past game sessions
  • Features:
  • Display active sessions
  • Monitor session status
  • View session details
  • Session management
  • Access: /admin/game/session/dashboard/

Mgmt (Management)

Server management and system monitoring.

Server Control

  • Purpose: Server status and control
  • Features:
  • Display server status (running/stopped)
  • Start, stop, restart server
  • Display server metrics
  • Health check status
  • Display Gunicorn configuration
  • Access: /admin/server/ or via "Mgmt" → "Server Control"
  • Permission: Superusers only
  • Documentation: See Health Check API for details on external monitoring with monitoring systems

View Application Logs (Log File Viewer)

  • Purpose: Display log files in browser
  • Features:
  • Select log files from data/logs/ directory (development) / /data/var/mcc/logs/ (production)
  • Real-time log display
  • Browse rotated log files
  • Filtering and search
  • Auto-refresh function
  • Access: /admin/logs/ or via "Mgmt" → "View Application Logs"
  • Permission: Superusers only
  • Documentation:
  • Display Log Files in Admin GUI - Overview of log files and using the Log File Viewer
  • Production Logging Setup - Best practices for logging in production

Backup Management

  • Purpose: Create and manage database backups
  • Features:
  • Manual backup creation
  • Display backup list
  • Backup download
  • Backup information (size, date)
  • Access: /admin/backup/ or via "Mgmt" → "Backup Management"
  • Permission: Superusers only

Gunicorn Configuration

  • Purpose: Configure Gunicorn log level and worker configuration
  • Key Fields:
  • log_level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
  • worker_class: Worker class (sync or gthread)
  • workers: Number of worker processes
  • threads: Number of threads per worker (only with gthread)
  • Features:
  • Change log level directly in Admin GUI
  • Adjust worker configuration
  • No environment variables needed
  • Singleton model (only one instance)
  • Access: /admin/mgmt/gunicornconfig/ or via "Mgmt" → "Gunicorn Configuration"
  • Note: Server restart required after changes
  • Documentation:
  • Gunicorn Configuration in Admin GUI - Overview of configuration in Admin Interface
  • Gunicorn Worker Configuration - Details on worker classes, signal handler issues, and performance

Application Logs

Note: Logs are no longer stored in the database. Use the Log File Viewer (see above) instead to display log files.

Documentation: See Display Log Files in Admin GUI and Production Logging Setup for details on the logging system.

Request Logs

  • Purpose: HTTP request logs for performance analysis
  • Features:
  • Display request duration
  • Filter by status codes
  • Endpoint analysis
  • Performance metrics
  • Access: /admin/mgmt/requestlog/ or via "Mgmt" → "Request Logs"

Performance Metrics

  • Purpose: Monitor system performance metrics
  • Features:
  • CPU and memory statistics
  • Request throughput
  • Response times
  • Trend analysis
  • Access: /admin/mgmt/performancemetric/ or via "Mgmt" → "Performance Metrics"

Alert Rules

  • Purpose: Configure alert rules for performance monitoring
  • Features:
  • Define thresholds
  • Configure alert conditions
  • Set up notifications
  • Access: /admin/mgmt/alertrule/ or via "Mgmt" → "Alert Rules"

Maintenance Control

  • Purpose: Activate/deactivate maintenance mode and configure IP whitelist
  • Features:
  • Activate/deactivate maintenance mode
  • Configure IP whitelist (single IPs and CIDR blocks)
  • Allow/deny admin access during maintenance
  • Display current status
  • Check IP status (whether current IP is in whitelist)
  • Access: /admin/maintenance/ or via "Mgmt" → "Maintenance Control"
  • Permission: Superusers only
  • Documentation: See Maintenance Mode Setup for details on configuration, IP whitelist, and Apache integration.

Maintenance Configuration

  • Purpose: Configure IP whitelist and admin access
  • Key Fields:
  • ip_whitelist: IP addresses or CIDR blocks (one per line)
  • allow_admin_during_maintenance: Allow admin access for superusers
  • Access: /admin/mgmt/maintenanceconfig/ or via "Mgmt" → "Maintenance Configurations"
  • Permission: Superusers only
  • Documentation: See Maintenance Mode Setup for details on IP whitelist configuration.

Minecraft Management

Minecraft server management (if enabled).

Minecraft Control

  • Purpose: Minecraft worker status and control
  • Features:
  • Display worker status (Minecraft Bridge Worker and Snapshot Worker)
  • Start, stop, restart workers
  • Manage coin synchronization between MyCyclingCity and Minecraft server
  • View and manage outbox events
  • Test RCON connection
  • Trigger manual synchronization
  • Access: /admin/minecraft/ or via "Minecraft Management" → "Minecraft Control"
  • Permission: Superusers only
  • Note: The worker synchronizes coins between the Django database and the Minecraft server via RCON. It does not control the Minecraft server itself.
  • Documentation: See Minecraft Integration for details on coin synchronization, RCON communication, outbox pattern, and configuration.

Common Tasks

Creating a New Cyclist

  1. Navigate to MCC Core API & Models → Cyclists
  2. Click Add Cyclist
  3. Fill in required fields:
  4. user: Select or create Django user
  5. id_tag: Enter RFID tag ID
  6. coin_conversion_factor: Set coins per kilometer
  7. Click Save

Assigning a Device to a Group

  1. Navigate to IoT Management → Devices
  2. Select the device
  3. In the Group field, select the target group
  4. Click Save

Uploading Firmware

  1. Navigate to IoT Management → Firmware Images
  2. Click Add Firmware Image
  3. Fill in:
  4. version: Version number (e.g., "1.2.3")
  5. file: Upload firmware binary (.bin)
  6. is_active: Check if this is the active version
  7. release_notes: Describe changes
  8. Click Save

Configuring Device Settings

  1. Navigate to IoT Management → Device Configurations
  2. Select or create configuration for a device
  3. Configure:
  4. send_interval_seconds: How often device sends data
  5. wheel_size: Wheel circumference in cm
  6. device_specific_api_key: Device authentication key
  7. Click Save

Viewing Device Health

  1. Navigate to IoT Management → Device Health
  2. View status for all devices:
  3. Green: Online and healthy
  4. Yellow: Warning (no recent activity)
  5. Red: Error or offline
  6. Click on a device to see detailed health information

Managing Game Rooms

  1. Navigate to MCC Game Interface → Game Rooms
  2. View all active and inactive rooms
  3. Click on a room to:
  4. View room state
  5. See participants
  6. Monitor game progress
  7. End room if needed

Advanced Features

Bulk Actions

Many admin pages support bulk actions: 1. Select multiple items using checkboxes 2. Choose an action from the dropdown 3. Click Go

  • List Filters: Use sidebar filters to narrow results
  • Search: Use search boxes to find specific items
  • Date Hierarchy: Click date links to filter by time period

Inline Editing

Some models support inline editing: - Edit related objects directly from the parent object - Add new related objects without leaving the page

Custom Actions

Some models have custom admin actions: - Delete Sessions: Bulk delete game sessions - Export Data: Export model data to CSV/JSON - Cleanup: Remove expired or orphaned records

Common Administrative Tasks

Restart Server

  1. Navigate to Mgmt → Server Control
  2. Check current server status
  3. Click Restart Server
  4. Wait until restart is complete

View Log Files

  1. Navigate to Mgmt → View Application Logs
  2. Select a log file from the dropdown menu
  3. The log file is automatically updated (Auto-Refresh)
  4. Use the search function to find specific entries

Create Backup

  1. Navigate to Mgmt → Backup Management
  2. Click Create Backup
  3. Wait until backup is created
  4. Download the backup if needed

Change Gunicorn Log Level

  1. Navigate to Mgmt → Gunicorn Configuration
  2. Select the desired log level
  3. Click Save
  4. Important: Restart the server (see "Restart Server")

View Analytics

  1. Navigate to Historical Reports & Analytics → Analytics Dashboard
  2. Select the desired time period
  3. Select the groups to analyze
  4. Export data if needed

Monitor Session Status

  1. Navigate to Session Management → Session Dashboard
  2. View all active sessions
  3. Click on a session to view details
  4. End sessions if needed

Best Practices

  1. Regular Backups: Always backup before bulk operations
  2. Test Changes: Test configuration changes on a development system first
  3. Monitor Health: Regularly check Device Health status
  4. Cleanup: Periodically clean up expired sessions and old data
  5. Documentation: Document custom configurations and changes

Troubleshooting

Cannot Access Admin

  • Verify you're logged in as a superuser
  • Check ALLOWED_HOSTS in settings
  • Ensure DEBUG=True in development

Changes Not Saving

  • Check for validation errors (red text)
  • Verify required fields are filled
  • Check database permissions

Device Not Appearing

  • Verify device is registered in Devices
  • Check Device Health status
  • Ensure device has sent at least one heartbeat