Skip to content

App Management

The startapp command handles all app creation and installation.

Create New Apps

Minimal Django App (Default)

rhamaa startapp blog
Creates standard Django app in apps/blog/ using django-admin startapp.

Wagtail App

rhamaa startapp pages --type wagtail
Creates Wagtail-ready app with models, templates, and admin configuration.

Install Prebuilt Apps

Basic Installation

rhamaa startapp iot --prebuild mqtt
Downloads and installs MQTT app from GitHub into apps/iot/.

Available Options

  • --list - Show available prebuilt apps
  • --force - Overwrite existing app
  • --type - App template type (minimal/wagtail)

Examples

# List all prebuilt apps
rhamaa startapp --list

# Install with force overwrite
rhamaa startapp users --prebuild users --force

Listing Available Apps

View All Apps

rhamaa startapp --list

This displays a formatted table showing:

  • App Name: The identifier used for installation
  • Description: Brief description of the app's functionality
  • Category: The app's category (IoT, Authentication, Content, etc.)

Example Output

┌──────────────┬────────────────────────────────────┬─────────────────┐
│ App Name     │ Description                        │ Category        │
├──────────────┼────────────────────────────────────┼─────────────────┤
│ mqtt         │ IoT MQTT integration for Wagtail  │ IoT             │
│ users        │ Advanced user management system    │ Authentication  │
│ articles     │ Blog and article management        │ Content         │
│ lms          │ Complete LMS solution for Wagtail │ Education       │
└──────────────┴────────────────────────────────────┴─────────────────┘

Installation Process

When you install an app, Rhamaa CLI performs these steps:

1. Project Validation

  • Checks if you're in a Wagtail project directory
  • Looks for manage.py or other Django project indicators
  • Displays error if not in a valid project

2. App Availability Check

  • Verifies the app exists in the registry
  • Shows error message if app is not found
  • Suggests using --list to see available apps

3. Existing App Check

  • Checks if app already exists in apps/ directory
  • Prompts to use --force flag if app exists
  • Skips installation unless forced

4. Download Process

  • Downloads the app repository from GitHub
  • Shows progress bar with download status
  • Handles network errors gracefully

5. Extraction and Installation

  • Extracts the downloaded repository
  • Places app files in apps/<app_name>/ directory
  • Cleans up temporary files
  • Shows installation success message

Post-Installation Steps

After installing an app, you need to:

1. Add to INSTALLED_APPS

Edit your Django settings file:

# settings/base.py or settings.py
INSTALLED_APPS = [
    # ... existing apps
    'apps.mqtt',  # Add your installed app
]

2. Run Migrations

python manage.py makemigrations
python manage.py migrate

3. Collect Static Files (if needed)

python manage.py collectstatic

4. Additional Configuration

Check the app's README file for specific configuration requirements:

cat apps/mqtt/README.md

App Directory Structure

Installed apps are placed in the apps/ directory:

your_project/
├── apps/
│   ├── __init__.py
│   ├── mqtt/
│   │   ├── __init__.py
│   │   ├── models.py
│   │   ├── views.py
│   │   ├── admin.py
│   │   ├── urls.py
│   │   ├── templates/
│   │   ├── static/
│   │   └── README.md
│   └── users/
│       ├── __init__.py
│       ├── models.py
│       └── ...
└── manage.py

Force Installation

When to Use --force

Use the --force flag when you want to:

  • Reinstall an app with updates
  • Overwrite a corrupted installation
  • Replace a modified app with the original

Example

rhamaa startapp mqtt --prebuild mqtt --force

What Happens

  • Removes the existing app directory
  • Downloads and installs the fresh version
  • Preserves your project's other files

Data Loss Warning

Using --force will delete any local modifications to the app. Make sure to backup any custom changes.

Error Handling

Common Errors and Solutions

"Not a Wagtail Project"

Error: This doesn't appear to be a Wagtail project.
Please run this command from the root of your Wagtail project.

Solution: Navigate to your project's root directory (where manage.py is located).

"App Not Found"

Error: App 'myapp' not found in registry.
Use 'rhamaa add --list' to see available apps.

Solution: Check available apps with rhamaa startapp --list and use the correct app name.

"App Already Exists"

Warning: App 'mqtt' already exists in apps/ directory.
Use --force flag to overwrite existing app.

Solution: Use rhamaa add mqtt --force to reinstall.

"Download Failed"

Failed to download repository.
Please check your internet connection and try again.

Solution: Check your internet connection and GitHub access.

Best Practices

Before Installation

  1. Backup Your Project: Especially when using --force
  2. Check Dependencies: Review app requirements
  3. Plan Integration: Understand how the app fits your project

After Installation

  1. Read Documentation: Check the app's README file
  2. Test Functionality: Verify the app works as expected
  3. Customize Settings: Configure app-specific settings
  4. Update Requirements: Add any new dependencies

App Management

  1. Keep Apps Updated: Reinstall apps periodically for updates
  2. Document Usage: Note which apps you've installed
  3. Version Control: Commit apps to your repository
  4. Environment Consistency: Install same apps across environments

Integration Examples

Blog Setup

rhamaa start MyBlog
cd MyBlog
rhamaa startapp articles --prebuild articles
rhamaa startapp users --prebuild users
# Configure and run migrations

IoT Dashboard

rhamaa start IoTDashboard
cd IoTDashboard
rhamaa startapp iot --prebuild mqtt
rhamaa startapp users --prebuild users
# Configure MQTT settings

Educational Platform

rhamaa start EduPlatform
cd EduPlatform
rhamaa startapp lms --prebuild lms
rhamaa startapp users --prebuild users
rhamaa startapp articles --prebuild articles
# Configure LMS settings

Next Steps