Moodle - Developer Guide

Learn how to deploy Moodle on AWS with our step-by-step guide. It walks you through launching the Meetrix Moodle AMI with CloudFormation, pointing your domain at it, logging in for the first time, connecting outgoing email, and keeping the server healthy once it runs. If you already run a stack from the earlier image, it also shows how to move your site to the patched release.

Moodle is the open-source learning management system behind courses at schools, universities and companies around the world. Teachers build courses from assignments, quizzes, forums and H5P content, and Moodle keeps the gradebook and completion records for every learner. If you are still choosing a platform, our Moodle vs Open edX vs Canvas comparison covers how much work each one takes to self-host. Running Moodle in your own AWS account keeps courses, learners and grades on infrastructure you control.

Launching the AMI

Step 1: Find and Select Moodle AMI

1. Log in to your AWS Management Console.
2. Navigate to 'Moodle' in AWS Marketplace.

Step 2: Initial Setup & Configuration

1. Click the "Continue to Subscribe" button.
2. After subscribing, accept the terms and click "Accept Terms".
3. Wait a few minutes until processing completes, then click "Continue to Configuration".
4. Select "CloudFormation script to deploy Moodle" as the fulfillment option and choose your region. Click "Continue to Launch".
5. From the "Choose Action" dropdown, select "Launch CloudFormation" and click "Launch".

Create CloudFormation Stack

Step 1: Create a stack

1. Ensure the "Template is ready" option is selected under "Prepare template".
2. Click "Next".

Step 2: Specify stack options

1. Provide a unique "Stack name".
2. Enter the "AdminEmail". It becomes the email of the Moodle admin account and the site's support contact, and it is used for SSL certificate generation.
3. Enter an "AdminPassword". This is the password for the Moodle admin account you log in with. Use 8-64 characters made of letters, digits and !@#%^*_+=.,- only, and store it securely.
4. Enter a value for "DeploymentName".
5. Provide a public domain for "DomainName". Moodle will automatically set up SSL if the domain is hosted on Route 53 in the same account. If that is not possible, Moodle stays on its IP address over HTTP and you set up SSL manually.
6. Choose an instance type "InstanceType" (Recommended: t3a.small).
7. Select your preferred "KeyName".
8. For "S3Bucket", enter the name of an existing S3 bucket in the same region to turn on daily database backups, or keep the default yours3bucket to leave them off.
9. Set "SSHLocation" to 0.0.0.0/0, or restrict it to your own IP range.
10. Keep "SubnetCidrBlock" as 10.0.0.0/24.
11. Keep "VpcCidrBlock" as 10.0.0.0/16.
12. Click "Next".

Step 3: Configure stack options

1. Choose "Roll back all stack resources" and "Delete all newly created resources" under "Stack failure options".
2. Click "Next".

Step 4: Review

Review and verify the parameters you've entered.

1. Tick "I acknowledge that AWS CloudFormation might create IAM resources with custom names".
2. Click "Submit".

Afterward, you'll be directed to the CloudFormation stacks page. The stack stays in CREATE_IN_PROGRESS until Moodle has finished its first-boot setup, so once it shows CREATE_COMPLETE (usually about 5 minutes), Moodle is ready to use. During first boot the server generates a new database password and site identifier for your deployment, sets the admin password and email you entered, and requests the SSL certificate.

Update DNS

Step 1: Copy IP Address

Copy the public IP labeled "PublicIp" in the "Outputs" tab. It is an Elastic IP, so it stays the same when you stop and start the instance.

Step 2: Update DNS

1. Go to AWS Route 53 and navigate to "Hosted Zones".
2. Click Create record.
3. Add a record name matching the DomainName you entered, keep the record type as A, and paste the copied PublicIp into the value textbox.
4. Click "Create records".

Access Moodle

Once the DNS record resolves, open the "DashboardUrl" from the Outputs tab. If SSL could not be issued at launch, Moodle stays on "DashboardUrlIp" over plain HTTP until you complete Generate SSL Manually.

Click "Log in", enter the username admin and the AdminPassword you set in the stack parameters, then click "Log in" again.

To set the admin's name or change the password later, open the user menu in the top-right corner, go to Profile and click "Edit profile". Click "Update profile" to save your changes.

Then go to the "Site administration" tab, where you can configure courses, users, appearance and plugins. To run live classes inside a course, see our guide to adding Jitsi video calls to Moodle.

Configure Outgoing Email

Moodle sends password resets, enrolment messages and forum notifications by email. The image has no local mail server, so connect an SMTP provider such as Amazon SES, Google Workspace, Microsoft 365 or SendGrid after your first login.

1. Go to Site administration > Server > Email > Outgoing mail configuration.
2. Enter SMTP hosts as host:port, for example email-smtp.us-east-1.amazonaws.com:587.
3. Set SMTP security to TLS for port 587 or SSL for port 465.
4. Enter the SMTP username and SMTP password from your provider.
5. Check the No-reply address. It defaults to noreply@ followed by your DomainName.
6. Click "Save changes", then use "Test outgoing mail configuration" on the same page to send yourself a test message.

Generate SSL Manually

Moodle automatically tries to set up SSL during first boot when a Route 53-hosted domain is provided. If your domain is hosted elsewhere, or the request failed, follow these steps to generate SSL manually.

Step 1: Copy IP Address

1. Follow the Update DNS steps above, if not already done. The domain must point at the server before the certificate can be issued.
2. Copy the Public IP indicated as "PublicIp" in the "Outputs" tab.

Step 2: Log in to the server

1. Open the terminal and go to the directory where your private key is located.
2. Run the following command, replacing the key name and IP address.
3. Type "yes" and press Enter to confirm.

ssh -i <your key name> ubuntu@<Public IP address>

Step 3: Generate SSL

Request the certificate, then switch Moodle's address from the IP to https and your domain:

sudo bash /root/certificate_generate_standalone.sh

sudo /opt/scripts/setdomain.sh

The second command updates Moodle's configured address and clears its caches. Moodle only answers on that address, so from now on open the site through the DashboardUrl rather than the IP.

Check Server Logs

Step 1: Log in to the server

ssh -i <your key name> ubuntu@<Public IP address>

Step 2: Check the logs

Moodle runs on nginx with PHP 8.5-FPM. PHP errors from Moodle appear in the nginx error log as "FastCGI sent in stderr" lines:

sudo tail -f /var/log/nginx/error.log

The PHP-FPM log records the PHP process manager itself, such as workers restarting or reaching their limit:

sudo tail -f /var/log/php8.5-fpm.log

To see what happened during first boot, including whether the SSL certificate was issued, read the end of the cloud-init log:

sudo tail -n 50 /var/log/cloud-init-output.log

Step 3: Restart the services

If Moodle stops responding, restart PHP, the web server and the database together, then confirm the server is on the patched PHP version:

sudo systemctl restart php8.5-fpm nginx mariadb

php -v

Scheduled Tasks and Backups

Moodle relies on its cron job for emails, grade updates, course completion and cleanup. The image already runs it every minute from /etc/cron.d/moodle, so there is nothing to set up. If Site administration warns that cron has not run recently, run it once by hand to see any errors:

sudo -u www-data php /var/www/html/moodle/admin/cli/cron.php

If you entered an S3 bucket in the S3Bucket parameter, the server uploads a compressed database dump to the moodle-dbbackup/ folder of that bucket every day at 02:00 UTC. To take a backup straight away, run:

sudo /opt/scripts/dbbackup.sh

Shutting Down Moodle

1. In CloudFormation, click the link labeled "Instance" in the "Resources" tab to open the EC2 instance.
2. Stop the Moodle instance from the Instance state dropdown. You can restart it later as needed.

Remove Moodle

Delete the CloudFormation stack from the AWS Management Console under "CloudFormation Stacks" by clicking "Delete". This deletes the instance and its volume, including every course and uploaded file, so back up what you need first.

Upgrades

When a new version is available in AWS Marketplace, launch a new stack from it, move your site across with the steps below, and delete the old stack once the new one is working.

Move an Existing Site to the New Release

Stacks launched from the earlier image keep running, but they stay on PHP 8.3 and do not get the security fix. To move to PHP 8.5, launch a new stack from the current version as described above, using the same DomainName, then copy your database and the /var/moodledata folder across. Both images keep Moodle in the same places, so the move is a dump and restore followed by Moodle's own upgrade script. Try it on a test stack first and plan a short maintenance window.

Step 1: Back up the old server

SSH into the old server, put Moodle into maintenance mode, then dump the database and archive the data folder:

sudo -u www-data php /var/www/html/moodle/admin/cli/maintenance.php --enable

sudo mysqldump --single-transaction moodle | gzip > moodle-db.sql.gz

sudo tar -czf moodledata.tar.gz -C /var --exclude=moodledata/cache --exclude=moodledata/localcache --exclude=moodledata/sessions --exclude=moodledata/temp moodledata

Step 2: Copy the backup to the new server

From your own computer, download both files from the old server and upload them to the new one:

scp -i <your key name> ubuntu@<old server IP>:moodle-db.sql.gz .
scp -i <your key name> ubuntu@<old server IP>:moodledata.tar.gz .

scp -i <your key name> moodle-db.sql.gz moodledata.tar.gz ubuntu@<new server IP>:

Step 3: Restore on the new server

SSH into the new server. These commands replace its empty site with yours:

sudo mysql -e "DROP DATABASE moodle; CREATE DATABASE moodle DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

gunzip < moodle-db.sql.gz | sudo mysql moodle

sudo rm -rf /var/moodledata
sudo tar -xzf moodledata.tar.gz -C /var
sudo chown -R www-data:www-data /var/moodledata

If you installed extra plugins on the old site, such as mod_jitsi, install their Moodle 5.3 versions from the Moodle plugins directory on the new server now, before the upgrade. Otherwise Moodle reports them as missing from disk.

Step 4: Upgrade and reopen the site

Run the Moodle upgrade, give the site its own identifier (the earlier image shared one across every deployment), clear the caches and take the site out of maintenance mode:

sudo -u www-data php /var/www/html/moodle/admin/cli/upgrade.php --non-interactive

sudo -u www-data php /var/www/html/moodle/admin/cli/cfg.php --name=siteidentifier --set="$(openssl rand -hex 16)<your domain>"

sudo -u www-data php /var/www/html/moodle/admin/cli/purge_caches.php

sudo -u www-data php /var/www/html/moodle/admin/cli/maintenance.php --disable

Finally, point your domain's A record at the new stack's PublicIp. Your users, courses and passwords come across with the database, so log in with your existing admin account; the AdminPassword from the new stack no longer applies. When everything checks out, delete the old stack.

Troubleshoot

If you face vCPU quota limits, request an increase: How to increase AWS quota.

If you face insufficient capacity errors while creating the stack, try another region or time.

If the stack rolls back with "Received FAILURE signal" or "Failed to receive 1 resource signal(s)", Moodle's first-boot setup did not finish. Launch the stack again. If it fails a second time, choose "Preserve successfully provisioned resources" under "Stack failure options", SSH into the instance and send the end of /var/log/cloud-init-output.log to support.

If the DashboardUrl does not load but the DashboardUrlIp does, the SSL certificate was not issued at launch. Follow Generate SSL Manually.

If password resets and notifications never arrive, outgoing email is not configured yet. See Configure Outgoing Email.

Check whether the instance storage is full. Log into the server and run:

df -h

If the root volume is between 90-100%, resize the EBS volume, then reboot the instance and restart the services.

Conclusion

The Meetrix Moodle Deployment Guide helps you run a patched, self-hosted learning platform in your AWS environment, with courses, learners and grades in a database you control. Whether you're a DevOps engineer, system administrator or an IT lead at a school, this guide provides step-by-step instructions for a secure setup. See the Moodle store page for what the Meetrix image includes, and our overview of deploying Moodle on AWS with Meetrix for sizing and cost. To host your own video classes alongside Moodle, the Jitsi Meet developer guide sets up a Jitsi server on AWS. The Moodle source code and release notes are on GitHub.

Technical Support

Reach out to Meetrix Support (aws@meetrix.io) for assistance with Moodle issues.