Upgrading an existing Joomla website—especially when migrating from Joomla 3.x to 4.x or 5.x—can introduce a range of issues related to templates, modules, JavaScript behavior, fonts, and PHP compatibility. When Joomla is deployed using Docker on Ubuntu 24.04 LTS, these challenges are compounded by containerized file systems, PHP version constraints, and logging distribution across multiple layers.

This paper provides a practical, production-oriented guide for safely upgrading Joomla in a Dockerized Ubuntu 24.04 LTS environment, with a strong emphasis on diagnosing and resolving errors using structured log analysis.

Upgrading an Existing Joomla Website with Docker on Ubuntu 24.04 LTS

Fixing Template, Module, JavaScript, Font Issues, and Examining Error Logs

1. Introduction

Upgrading an existing Joomla website—especially when migrating from Joomla 3.x to 4.x or 5.x—can introduce a range of issues related to templates, modules, JavaScript behavior, fonts, and PHP compatibility. When Joomla is deployed using Docker on Ubuntu 24.04 LTS, these challenges are compounded by containerized file systems, PHP version constraints, and logging distribution across multiple layers.

This paper provides a practical, production-oriented guide for safely upgrading Joomla in a Dockerized Ubuntu 24.04 LTS environment, with a strong emphasis on diagnosing and resolving errors using structured log analysis.

2. Recommended Technology Stack

Component	Recommended Version
Joomla	4.4.x or 5.x
PHP	8.1 or 8.2
Web Server	Apache 2.4
Database	MySQL 8.0
OS	Ubuntu 24.04 LTS
Containerization	Docker + Docker Compose

3. Dockerized Joomla Environment

Sample Docker Compose Configuration

version: "3.9" services: joomla: image: joomla:5.0-php8.2-apache container_name: joomla_app ports: - "8080:80" volumes: - ./joomla:/var/www/html environment: JOOMLA_DB_HOST: db JOOMLA_DB_USER: joomla JOOMLA_DB_PASSWORD: joomla_pass JOOMLA_DB_NAME: joomla_db depends_on: - db db: image: mysql:8.0 container_name: joomla_db environment: MYSQL_ROOT_PASSWORD: rootpass MYSQL_DATABASE: joomla_db MYSQL_USER: joomla MYSQL_PASSWORD: joomla_pass volumes: - dbdata:/var/lib/mysql volumes: dbdata:

4. Safe Upgrade Strategy

4.1 Full Backup (Mandatory)

docker exec -it joomla_app bash tar -czvf /tmp/site_backup.tar.gz /var/www/html mysqldump -u joomla -p joomla_db > /tmp/db_backup.sql

4.2 Pre-Upgrade Checks

From Administrator → System → Pre-Update Check:

• Verify PHP compatibility
• Verify database compatibility
• Identify incompatible extensions

Disable all third-party extensions before proceeding.

5. Template Issues and Resolutions

5.1 Incompatible Templates

Symptoms:

• Blank page (WSOD)
• Broken layout
• Missing styles

Resolution:

• Switch temporarily to Cassiopeia (Site) and Atum (Admin)
• Remove or rename template overrides:

/templates/your_template/html/

5.2 Bootstrap Conflicts

Joomla 4/5 uses Bootstrap 5. Legacy templates may load Bootstrap 3 or 4.

Resolution:

• Remove hardcoded Bootstrap files
• Use Joomla Web Asset Manager:

$wa = $this->getWebAssetManager(); $wa->useStyle('bootstrap'); $wa->useScript('bootstrap');

6. Module Compatibility Issues

Common Causes

• Deprecated module types
• Legacy layout overrides
• Removed parameters

Resolution Steps

1. Discover missing modules:
   System → Manage → Extensions → Discover
2. Remove module overrides:

/templates/your_template/html/mod_*

3. Replace deprecated modules with Joomla core equivalents.

7. JavaScript Issues After Upgrade

7.1 jQuery Not Loaded

Joomla 4+ does not auto-load jQuery.

use Joomla\CMS\Factory; $wa = Factory::getApplication()->getDocument()->getWebAssetManager(); $wa->useScript('jquery');

7.2 MooTools Deprecation

Errors such as:

MooTools is not defined

Resolution: Rewrite legacy JavaScript using vanilla JS or jQuery.

7.3 JavaScript Load Order

Enable:

• Move JavaScript to bottom
• Deferred loading

Located in Global Configuration → Server.

8. Font and Media Issues

8.1 Broken Font Paths

Docker volume paths often break relative URLs.

Correct format:

url('/media/templates/site/your_template/fonts/font.woff2')

8.2 Google Fonts and Privacy

Self-host fonts to avoid CSP and privacy issues.

8.3 Font Awesome

Joomla 4/5 includes Font Awesome.

$wa->useStyle('fontawesome');

9. Examining Error Logs (Core Diagnostic Section)

9.1 Joomla Application Logs

Location:

/administrator/logs/

Common files:

• error.php
• deprecated.php
• joomla_update.php

tail -f administrator/logs/error.php

9.2 PHP and Apache Logs

docker logs joomla_app --tail=100

Or inside container:

tail -f /var/log/apache2/error.log

Used to detect:

• PHP fatal errors
• Incompatible extensions
• Template syntax errors

9.3 Joomla Debug Mode

Enable:

Global Configuration → System Debug System = YES Error Reporting = Maximum

Reveals:

• SQL errors
• Missing language strings
• Deprecated API usage

9.4 Browser Developer Tools

Use Console and Network tabs to identify:

• JavaScript errors
• Missing JS/CSS
• Font 404 errors
• CSP violations

9.5 Database Errors

System → Maintenance → Database → Fix

Docker database logs:

docker logs joomla_db

9.6 File Permission Errors

chown -R www-data:www-data /var/www/html

10. Structured Troubleshooting Workflow

1. Enable Joomla debug
2. Check PHP/Apache logs
3. Review Joomla logs
4. Inspect browser console
5. Fix database schema
6. Correct permissions
7. Re-enable extensions incrementally

11. Production Hardening

• Disable debug
• Enable caching and Gzip
• Use CSP headers
• Rotate logs
• Maintain staging environment

12. Best Practices for Future Joomla Upgrades

• Use child templates
• Avoid hardcoded JS/CSS
• Use Web Asset Manager
• Keep extensions minimal
• Test upgrades in Docker staging

13. How KeenComputer.com Can Help

KeenComputer.com provides:

• Dockerized Joomla upgrade pipelines
• Template modernization (Bootstrap 5)
• Extension compatibility audits
• JavaScript refactoring
• Centralized logging and monitoring
• Production hardening and CI/CD

14. References and Further Reading

The following books and authoritative resources are recommended to support Joomla upgrades, template modernization, and Docker-based deployment strategies discussed in this paper:

Joomla Development and Administration

1. Rahmel, D. Advanced Joomla!. Apress.
   A comprehensive guide covering advanced Joomla administration, customization, and extension development. Particularly useful for understanding legacy Joomla sites and migration challenges.
2. Grange, S. Joomla! 4 The Book. Open Source Matters.
   An official, community-recommended guide covering Joomla 4 architecture, APIs, templates, and best practices.
3. Keflin, C. Joomla! 4 Templates.
   Focused specifically on Joomla 4 template design, overrides, and Bootstrap 5 integration, making it highly relevant for resolving template and layout issues during upgrades.
4. Joomla Documentation Project. Joomla Official Documentation.
   Authoritative reference for Joomla configuration, upgrades, extension compatibility, and troubleshooting.

Docker and Containerization

5. Stoneman, E. Learn Docker in a Month of Lunches. Manning Publications.
   A practical, hands-on introduction to Docker, ideal for developers and system administrators managing containerized Joomla environments.
6. Nickoloff, J., & Kuenzli, S. Docker in Action (2nd Edition). Manning Publications.
   Provides in-depth coverage of Docker architecture, networking, volumes, and production deployment patterns applicable to Joomla CMS stacks.
7. Kane, S. P., & Matthias, K. Docker: Up & Running. O’Reilly Media.
   Explains Docker fundamentals and operational best practices for running web applications in containers.
8. Öggl, B., & Kofler, M. Docker: Practical Guide for Developers and DevOps. SAP Press.
   A comprehensive reference for building, managing, and troubleshooting Docker-based application infrastructures.

15. Conclusion

Upgrading Joomla in a Dockerized Ubuntu 24.04 LTS environment requires a disciplined approach that combines compatibility planning, structured upgrades, and systematic log analysis. By aligning modern Joomla development practices with containerization best practices, organizations can modernize legacy websites while improving stability, security, and long-term maintainability.