Skip to main content

​
Overview

This guide covers common issues you may encounter with ipMoodle and their solutions. For each problem, we provide diagnostic steps and resolution procedures.

​
Container Issues

​
Containers Won’t Start

Diagnostic steps:
# Check container logs
docker compose logs

# Check specific container
docker logs moodle_app
Common causes and solutions:
  1. Port already in use 
    # Check what's using port 80
sudo lsof -i :80

# Kill the process or change the port in docker-compose.yml
ports:
  - "8080:80"  # Use port 8080 instead
  2. Database connection failure 
    # Verify database is running
docker compose up -d db

# Check database logs
docker logs moodle_db

# Verify environment variables
docker exec moodle_app env | grep MOODLE_DB
  3. Missing environment variables 
    # Ensure .env file exists
ls -la .env

# Verify contents
cat .env
Diagnostic steps:
# Check restart count
docker inspect moodle_db | grep RestartCount

# View database logs
docker logs moodle_db
Solutions:
  1. Corrupted database data 
    # Stop all services
docker compose down

# Backup and remove db_data
mv ./db_data ./db_data.backup

# Restart (will create fresh database)
docker compose up -d db

# Restore from backup if available
  2. Insufficient memory 
    # Check system memory
free -h

# Add memory limits to docker-compose.yml
db:
  deploy:
    resources:
      limits:
        memory: 2G

​
Containers Running But Unresponsive

Diagnostic steps:
# Check if PHP-FPM is running
docker exec moodle_app ps aux | grep php-fpm

# Test internal connectivity
docker exec moodle_web curl -I http://app:9000
Solutions:
  1. PHP-FPM process crashed 
    # Restart the container
docker restart moodle_app

# Check for errors
docker logs moodle_app --tail 100
  2. Memory limit exceeded 
    # Check PHP memory setting
docker exec moodle_app php -i | grep memory_limit

# Increase limit in Dockerfile and rebuild
RUN echo 'memory_limit=1024M' > /usr/local/etc/php/conf.d/moodle.ini

docker compose build --no-cache
docker compose up -d

​
Network Issues

​
Cannot Access Moodle from Browser

1

Verify containers are running

docker compose ps
All containers should show status “Up”
2

Test local connectivity

curl -I http://localhost
Should return HTTP 200 or 301
3

Check firewall rules

# For UFW
sudo ufw status
sudo ufw allow 80/tcp

# For firewalld
sudo firewall-cmd --list-ports
sudo firewall-cmd --add-port=80/tcp --permanent
sudo firewall-cmd --reload
4

Verify port mapping

docker port moodle_web
Should show: 80/tcp -> 0.0.0.0:80
5

Check Nginx configuration

docker exec moodle_web nginx -t
Should return “syntax is ok”
If running on a cloud platform (AWS, GCP, Azure), ensure security groups or firewall rules allow inbound traffic on port 80.

​
Internal Container Communication Failure

Symptom: Application cannot connect to database 
# Test database connectivity
docker exec moodle_app nc -zv db 5432

# Check network configuration
docker network inspect moodleip_moodle-net

# Verify both containers are on same network
docker inspect moodle_app | grep NetworkMode
docker inspect moodle_db | grep NetworkMode
Solution: 
# Recreate network
docker compose down
docker network rm moodleip_moodle-net
docker compose up -d

​
Database Issues

​
Database Connection Errors

Diagnostic:
# Check if database is running
docker ps | grep moodle_db

# Check database logs
docker logs moodle_db | grep -i error

# Verify credentials
docker exec moodle_app env | grep MOODLE_DB
Solution:
# Verify environment variables match
cat .env

# Restart database
docker restart moodle_db

# Wait for database to be ready
sleep 10

# Test connection
docker exec moodle_app nc -zv db 5432
Solution:
# Create database manually
docker exec moodle_db psql -U moodle -c "CREATE DATABASE moodle;"

# Verify
docker exec moodle_db psql -U moodle -c "\l" | grep moodle
Diagnostic:
# Check active connections
docker exec moodle_db psql -U moodle -d moodle -c "SELECT count(*) FROM pg_stat_activity;"
Solution:
# Increase max_connections in PostgreSQL
docker exec moodle_db psql -U moodle -c "ALTER SYSTEM SET max_connections = 200;"

# Restart database
docker restart moodle_db

​
Permission Issues

​
File Permission Errors

Symptoms:
  • Cannot upload files
  • Cannot install plugins
  • Cannot update Moodle
Diagnostic: 
# Check ownership
docker exec moodle_app ls -la /var/www/html | head -20
docker exec moodle_app ls -la /var/www/moodledata | head -20
Solution: 
# Fix ownership and permissions
docker exec moodle_app chown -R www-data:www-data /var/www/html
docker exec moodle_app chown -R www-data:www-data /var/www/moodledata
docker exec moodle_app chmod -R 755 /var/www/html

# Verify
docker exec moodle_app ls -la /var/www/html | head -5
Permission issues commonly occur after manually copying files or extracting archives on the host system.

​
Cron Issues

​
Cron Jobs Not Running

# Check container status
docker ps | grep moodle_cron

# Check cron logs
docker logs moodle_cron --tail 50

# Verify crontab
docker exec moodle_cron cat /var/spool/cron/crontabs/www-data

# Run cron manually to see errors
docker exec moodle_cron /usr/local/bin/php /var/www/html/admin/cli/cron.php

# Check Moodle logs for cron errors
docker exec moodle_app tail -f /var/www/moodledata/cron.log
Common issues:
  1. Cron runs but produces errors
    • Check PHP memory limit
    • Verify file permissions
    • Review Moodle scheduled tasks in admin panel
  2. Cron container exits 
    # Check for syntax errors in cron command
docker compose logs cron

# Restart cron container
docker restart moodle_cron

​
Performance Issues

​
Slow Page Load Times

1

Check resource usage

docker stats --no-stream
2

Enable Moodle caching

Navigate to: Site administration → Plugins → Caching → ConfigurationEnable all recommended cache stores
3

Optimize database

docker exec moodle_db psql -U moodle -d moodle -c "VACUUM ANALYZE;"
4

Check for slow queries

docker exec moodle_db psql -U moodle -d moodle -c "
  SELECT query, calls, total_time, mean_time
  FROM pg_stat_statements
  ORDER BY mean_time DESC
  LIMIT 10;
"
5

Increase PHP resources

Edit Dockerfile:
RUN { \
    echo 'memory_limit=1024M'; \
    echo 'max_execution_time=300'; \
} > /usr/local/etc/php/conf.d/moodle.ini
Rebuild:
docker compose build --no-cache
docker compose up -d

​
High Memory Usage

# Identify memory-hungry containers
docker stats --no-stream --format "table {{.Name}}\t{{.MemUsage}}\t{{.MemPerc}}"

# Check system memory
free -h

# Review PHP memory settings
docker exec moodle_app php -i | grep memory_limit

# Clear Moodle cache
docker exec moodle_app /usr/local/bin/php /var/www/html/admin/cli/purge_caches.php

​
Disk Space Issues

​
Running Out of Disk Space

# Check disk usage
df -h

# Check volume sizes
du -sh ./html ./moodledata ./db_data

# Find large files
find ./moodledata -type f -size +100M -exec ls -lh {} \;

# Remove old Docker images
docker image prune -a

# Clean Docker system
docker system prune -a --volumes

# Remove old Moodle temp files
docker exec moodle_app find /var/www/moodledata/temp -type f -mtime +7 -delete

# Vacuum database
docker exec moodle_db psql -U moodle -d moodle -c "VACUUM FULL;"

​
Upgrade Issues

​
Errors After Moodle Upgrade

# Run Moodle upgrade CLI
docker exec moodle_app /usr/local/bin/php /var/www/html/admin/cli/upgrade.php

# Check database schema
docker exec moodle_app /usr/local/bin/php /var/www/html/admin/cli/check_database_schema.php
  1. Navigate to: Site administration → Notifications
  2. Review plugin status
  3. Disable incompatible plugins
  4. Check for plugin updates

​
Emergency Recovery

​
Complete System Failure

1

Stop all containers

docker compose down
2

Backup current state

cp -r ./html ./html.backup
cp -r ./moodledata ./moodledata.backup
cp -r ./db_data ./db_data.backup
3

Remove containers and volumes

docker compose down -v
docker system prune -a
4

Restore from backup

Follow the restore procedures in Backup & Restore
5

Restart services

docker compose up -d
Only perform complete system recovery as a last resort. Always attempt targeted troubleshooting first.

​
Getting Help

If you’ve tried the solutions above and still experience issues:
  1. Check Moodle logs for detailed error messages
  2. Review Docker logs for all containers
  3. Verify system requirements meet Moodle’s needs
  4. Search Moodle forums for similar issues
  5. Check Docker documentation for container-specific problems

​
Useful Debugging Commands

# Complete system status
docker compose ps
docker stats --no-stream
df -h
free -h

# All container logs
docker compose logs --tail=100

# Network diagnostics
docker network ls
docker network inspect moodleip_moodle-net

# Container inspection
docker inspect moodle_app | grep -A 10 "NetworkSettings"

Build docs developers (and LLMs) love

Get started for freeTalk to us