.. include:: /Includes.rst.txt .. _installation: ============ Installation ============ Requirements ============ Before installing DashBash, ensure your TYPO3 installation meets the following requirements: **TYPO3 Version Support** * **TYPO3 v11.5**: 11.5.0 - 11.5.99 * **TYPO3 v12.4**: 12.4.0 - 12.4.99 * **TYPO3 v13.4**: 13.4.0 - 13.4.99 **PHP Requirements** * **PHP**: 7.4.0 or higher * **PHP Extensions**: Standard TYPO3 requirements **Required TYPO3 Extensions** The following system extensions must be installed and activated: * ``typo3/cms-core`` * ``typo3/cms-backend`` * ``typo3/cms-dashboard`` .. note:: The dashboard system extension is required as DashBash extends the TYPO3 dashboard functionality. Installation Methods ==================== Method 1: Composer Installation (Recommended) ---------------------------------------------- For Composer-based TYPO3 installations, use the following command: .. code-block:: bash composer require mrg/dashbash This will: * Download the extension and its dependencies * Register the extension in your TYPO3 installation * Make it available for activation After installation, activate the extension: .. code-block:: bash # Via TYPO3 Console (if available) vendor/bin/typo3 extension:activate dashbash # Or via TYPO3 CLI vendor/bin/typo3 extension:activate dashbash Method 2: TYPO3 Extension Repository (TER) ------------------------------------------- For Classic Mode installations: 1. **Access Extension Manager** * Go to **Admin Tools** > **Extensions** in your TYPO3 backend * Make sure you're in "Get Extensions" mode 2. **Search and Install** * Search for "dashbash" in the extension repository * Click "Import and Install" next to the DashBash extension * The extension will be downloaded and made available 3. **Activate Extension** * Switch to "Installed Extensions" mode * Find "DashBash" in the list * Click the activation icon to enable the extension Method 3: Manual Installation ------------------------------ For development or special deployment scenarios: 1. **Download Extension** * Download the extension from the `TYPO3 Extension Repository `__ * Or clone from the Git repository: ``git clone [repository-url]`` 2. **Place Files** * Extract/copy the extension files to ``typo3conf/ext/dashbash/`` * Ensure proper file permissions are set 3. **Clear Cache** .. code-block:: bash # Clear all caches vendor/bin/typo3 cache:flush 4. **Activate Extension** * Go to **Admin Tools** > **Extensions** * Find "DashBash" and activate it Post-Installation Steps ======================= After successful installation, complete these steps: 1. **Clear System Cache** .. code-block:: bash # Clear all caches to ensure proper loading vendor/bin/typo3 cache:flush 2. **Verify Installation** * Go to **Admin Tools** > **Extensions** * Confirm "DashBash" is listed as active * Check for any error messages 3. **Access Dashboard** * Navigate to the **Dashboard** module * Verify that DashBash widgets are available in the widget selection Initial Configuration ===================== Basic Setup ----------- No initial configuration is required. The extension works out-of-the-box with default settings. Optional Configuration ---------------------- For advanced features, you may configure: **TSConfig Filtering (Optional)** Enable advanced TSConfig management capabilities: .. code-block:: php # In LocalConfiguration.php or AdditionalConfiguration.php $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['dashbash']['enableTsConfigFiltering'] = 1; **Development Logging (Development Only)** For development environments, debug logging is automatically enabled in ``Development/ddev`` context. Troubleshooting Installation ============================= Common Issues ------------- **Extension Not Appearing in Dashboard** 1. Clear all caches: ``vendor/bin/typo3 cache:flush`` 2. Verify dashboard system extension is active 3. Check browser console for JavaScript errors **Composer Installation Fails** 1. Verify your ``composer.json`` allows the required TYPO3 versions 2. Update Composer: ``composer self-update`` 3. Try: ``composer require mrg/dashbash --no-scripts`` **Permission Errors (Manual Installation)** Ensure proper file permissions: .. code-block:: bash # Example for typical web server setup sudo chown -R www-data:www-data typo3conf/ext/dashbash/ sudo chmod -R 755 typo3conf/ext/dashbash/ **JavaScript/CSS Not Loading** 1. Clear browser cache 2. Verify ``Resources/Public/`` folder has proper permissions 3. Check TYPO3's resource handling configuration Database Issues --------------- DashBash uses TYPO3's built-in caching system. If you encounter cache-related issues: .. code-block:: bash # Flush specific cache vendor/bin/typo3 cache:flush --group=system # Or flush all caches vendor/bin/typo3 cache:flush Version Compatibility ====================== **Upgrading from Previous Versions** This is the initial release (v13.0.0), so no upgrade procedures are needed. **TYPO3 Version Upgrades** When upgrading TYPO3: 1. Check compatibility matrix above 2. Update DashBash if needed: ``composer update mrg/dashbash`` 3. Clear all caches after the upgrade **PHP Version Compatibility** * **PHP 7.4**: Fully supported * **PHP 8.0+**: Fully supported * **PHP 8.1+**: Fully supported * **PHP 8.2+**: Fully supported Verification ============ To verify successful installation: 1. **Extension Status** .. code-block:: bash vendor/bin/typo3 extension:list | grep dashbash 2. **Dashboard Access** * Go to **Dashboard** in TYPO3 backend * Click "Add widget" * Verify these widgets are available: - "Number of content elements in the respective languages" - "An entertaining brain game for the TYPO3 backend" 3. **System Reports** * Go to **Admin Tools** > **System** > **Reports** * Check "Status Report" for any DashBash-related issues Next Steps ========== After successful installation: * :ref:`Configure the extension ` for advanced features * :ref:`Learn how to use the widgets ` * :ref:`Review developer documentation ` if you plan to extend functionality The extension is now ready to use! Navigate to the Dashboard module to start adding and using DashBash widgets.