Headless LMS Guide: Static WP-CLI Generation and Nginx Optimization

I recently worked with an online university that was running its curriculum on a standard WordPress setup. They had over 25,000 active students. During exam week, the server collapsed.

Every time a student clicked on a lesson, the database had to run dozens of queries. It checked if the user was logged in, loaded lesson details, looked up progress trackers, and updated user meta tables. Multiplying this by thousands of students loading heavy video and quiz pages at the same time, the server completely ran out of memory.

They were using a heavy Learning Management System (LMS) plugin that loaded complex PHP code on every single click. The typical solution is to buy a bigger, more expensive server. But that is just a temporary fix.

I sat down with their engineering team and proposed a better path. We decided to decouple the platform. We kept WordPress as a headless content manager for teachers to write courses. Then, we built a custom automation system using WP-CLI to compile all those courses into static HTML files.

For the user-facing side, we needed a clean, beautiful, and accessible frontend design. I chose the Edomi - Bootstrap 5 Education, Learning Courses HTML Template because it has pre-built layouts for course grids, lessons, instructor profiles, and quizzes. It is built on clean Bootstrap 5, which allowed us to inject our static course content without dealing with heavy framework overhead.

In this guide, I will show you how to build this headless LMS architecture. We will develop a custom WP-CLI command to compile your courses, write Nginx routing rules to serve the files, and create a lightweight client-side script to track student progress without slowing down the server.

The Decoupled LMS Architecture

Before we look at the code, let us look at how the data flows. In a traditional WordPress LMS, everything is dynamic:

[Student Browser] -> [Server PHP Engine] -> [MySQL Database Query] -> [Generate HTML] -> [Back to Student]

This path repeats on every lesson click. It is incredibly slow and expensive for your server.

In our decoupled static architecture, the data flow changes completely:

1. Content Creation: Teachers write lessons, upload videos, and build quizzes in the WordPress dashboard.
2. Static Compilation: When a course is published, a custom WP-CLI script runs. It pulls the course structure, lessons, and content, and compiles them into a static folder structure.
3. High-Speed Delivery: Students load pure HTML, CSS, and JS files served directly from Nginx or a CDN.
4. Local Progress Tracking: Student progress (which lessons they completed) is stored in the browser's local storage and synced asynchronously with a microservice API, keeping database load near zero.

To understand how WP-CLI works under the hood and how to register commands on your server, you can review the WP-CLI Handbook.

Part 1: Developing the Custom WP-CLI Compiler

Let us build the PHP code for our custom compiler. This code runs on your server. It registers a brand new command: wp lms compile.

We create this code as a custom plugin inside your WordPress directory: wp-content/plugins/lms-compiler/lms-compiler.php.

]
         * : Compile a specific course ID. If not set, all courses will compile.
         
         * [--output_path=<path>]
         * : Define where to save the compiled HTML files.
         
         * ## EXAMPLES
         
         *     wp lms compile --course_id=45 --output_path=/var/www/html/static-courses
         
         * @alias compile
         */
        public function __invoke( $args, $assoc_args ) {
            $course_id = isset( $assoc_args['course_id'] ) ? intval( $assoc_args['course_id'] ) : 0;
            $output_path = isset( $assoc_args['output_path'] ) ? rtrim( $assoc_args['output_path'], '/' ) : '/var/www/static-lms';

        WP_CLI::line( "Starting static compilation pipeline..." );

        // Ensure output directory exists
        if ( ! file_exists( $output_path ) ) {
            if ( ! mkdir( $output_path, 0755, true ) ) {
                WP_CLI::error( "Failed to create output directory: $output_path" );
            }
        }

        // Define query arguments
        $query_args = array(
            'post_type'      => 'course',
            'post_status'    => 'publish',
            'posts_per_page' => -1,
        );

        if ( $course_id > 0 ) {
            $query_args['p'] = $course_id;
        }

        $courses_query = new WP_Query( $query_args );

        if ( ! $courses_query->have_posts() ) {
            WP_CLI::error( "No published courses found." );
        }

        $count = 0;
        while ( $courses_query->have_posts() ) {
            $courses_query->the_post();
            $current_course_id = get_the_ID();
            $course_slug = get_post_field( 'post_name', $current_course_id );

            WP_CLI::line( "Compiling course: " . get_the_title() . " (ID: $current_course_id)" );

            // Create directory for this specific course
            $course_dir = $output_path . '/' . $course_slug;
            if ( ! file_exists( $course_dir ) ) {
                mkdir( $course_dir, 0755, true );
            }

            // Compile Course Main Page
            $this->compile_course_landing( $current_course_id, $course_dir );

            // Fetch and compile all lessons for this course
            $this->compile_course_lessons( $current_course_id, $course_dir );

            $count++;
        }

        wp_reset_postdata();
        WP_CLI::success( "Successfully compiled $count course(s) to $output_path!" );
    }

    /**
     * Compiles the main landing page of the course.
     */
    private function compile_course_landing( $course_id, $course_dir ) {
        $title = get_the_title( $course_id );
        $content = apply_filters( 'the_content', get_post_field( 'post_content', $course_id ) );
        $price = get_post_meta( $course_id, 'course_price', true ) ?: 'Free';
        $duration = get_post_meta( $course_id, 'course_duration', true ) ?: 'Self-paced';

        // Load our base landing template layout
        $template = $this->get_template( 'course-landing' );

        if ( ! $template ) {
            WP_CLI::warning( "Landing template missing. Skipping compilation for Course ID: $course_id" );
            return;
        }

        // Replace template placeholders with real WordPress post data
        $html = str_replace(
            array( '{{COURSE_TITLE}}', '{{COURSE_CONTENT}}', '{{COURSE_PRICE}}', '{{COURSE_DURATION}}', '{{COURSE_ID}}' ),
            array( esc_html( $title ), $content, esc_html( $price ), esc_html( $duration ), $course_id ),
            $template
        );

        file_put_contents( $course_dir . '/index.html', $html );
        WP_CLI::log( " -> Compiled landing: index.html" );
    }

    /**
     * Compiles all lessons linked to a specific course.
     */
    private function compile_course_lessons( $course_id, $course_dir ) {
        // Get lessons associated with this course (assuming post relationship or meta lookup)
        $lessons = new WP_Query( array(
            'post_type'      => 'lesson',
            'post_status'    => 'publish',
            'posts_per_page' => -1,
            'meta_query'     => array(
                array(
                    'key'   => '_associated_course_id',
                    'value' => $course_id,
                )
            ),
            'orderby'        => 'menu_order',
            'order'          => 'ASC'
        ) );

        if ( ! $lessons->have_posts() ) {
            WP_CLI::log( " -> No lessons found for this course." );
            wp_reset_postdata();
            return;
        }

        // Make a directory to hold individual lessons
        $lessons_dir = $course_dir . '/lessons';
        if ( ! file_exists( $lessons_dir ) ) {
            mkdir( $lessons_dir, 0755, true );
        }

        $template = $this->get_template( 'lesson-view' );

        if ( ! $template ) {
            WP_CLI::warning( "Lesson template missing. Skipping lessons for Course ID: $course_id" );
            wp_reset_postdata();
            return;
        }

        while ( $lessons->have_posts() ) {
            $lessons->the_post();
            $lesson_id = get_the_ID();
            $lesson_slug = get_post_field( 'post_name', $lesson_id );
            $lesson_title = get_the_title();
            $lesson_content = apply_filters( 'the_content', get_the_content() );
            $video_url = get_post_meta( $lesson_id, 'lesson_video_url', true ) ?: '';

            // Build a basic list of sibling lessons for navigation sidebar
            $sidebar_html = $this->build_lessons_sidebar( $course_id, $lesson_id );

            // Replace lesson template placeholders
            $html = str_replace(
                array( '{{LESSON_TITLE}}', '{{LESSON_CONTENT}}', '{{VIDEO_URL}}', '{{LESSON_SIDEBAR}}', '{{LESSON_ID}}', '{{COURSE_ID}}' ),
                array( esc_html( $lesson_title ), $lesson_content, esc_url( $video_url ), $sidebar_html, $lesson_id, $course_id ),
                $template
            );

            file_put_contents( $lessons_dir . '/' . $lesson_slug . '.html', $html );
            WP_CLI::log( "   -> Compiled lesson: /lessons/{$lesson_slug}.html" );
        }

        wp_reset_postdata();
    }

    /**
     * Builds a simple HTML sidebar navigation for the lessons.
     */
    private function build_lessons_sidebar( $course_id, $current_lesson_id ) {
        $lessons = new WP_Query( array(
            'post_type'      => 'lesson',
            'post_status'    => 'publish',
            'posts_per_page' => -1,
            'meta_query'     => array(
                array(
                    'key'   => '_associated_course_id',
                    'value' => $course_id,
                )
            ),
            'orderby'        => 'menu_order',
            'order'          => 'ASC'
        ) );

        $html = '<div class="lesson-sidebar-list list-group">';
        while ( $lessons->have_posts() ) {
            $lessons->the_post();
            $lesson_id = get_the_ID();
            $slug = get_post_field( 'post_name', $lesson_id );
            $active_class = ( $lesson_id === $current_lesson_id ) ? 'active' : '';

            // Generate tracking ID for CSS/JS access
            $html .= sprintf(
                '<a href="../lessons/%s.html">',
                esc_attr( $slug ),
                esc_attr( $active_class ),
                intval( $lesson_id )
            );
            $html .= '<span class="status-dot me-2"></span>';
            $html .= esc_html( get_the_title() );
            $html .= '</a>';
        }
        $html .= '</div>';

        wp_reset_postdata();
        return $html;
    }

    /**
     * Loads base HTML template files from plugin folder.
     */
    private function get_template( $name ) {
        $path = plugin_dir_path( __FILE__ ) . 'templates/' . $name . '.html';
        if ( file_exists( $path ) ) {
            return file_get_contents( $path );
        }
        return false;
    }
}

// Register our command with WP-CLI
WP_CLI::add_command( 'lms', 'LMS_Static_Compiler_Command' );


}

Why is this approach so powerful?

This script pulls structural data straight out of the database and converts it into individual HTML files. When a student loads a lesson, the server does not run a single line of PHP or make a single database query. Nginx simply serves the pre-compiled HTML file. This reduces server CPU load during traffic spikes to almost zero.

Part 2: HTML Template Layout Structure

For our compiler script to work, we need our base HTML template files. This is where we integrate our clean frontend layout files.

Let us build our lesson-view.html template. We save this file inside our compiler plugin directory: wp-content/plugins/lms-compiler/templates/lesson-view.html.

<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{LESSON_TITLE}} - Static Learning Platform</title>

<link rel="stylesheet" href="/assets/css/bootstrap.min.css">
<link rel="stylesheet" href="/assets/css/style.css">

<style>
    .lesson-container { display: flex; margin-top: 30px; }
    .lesson-sidebar { width: 300px; border-right: 1px solid #ddd; padding-right: 20px; }
    .lesson-body { flex: 1; padding-left: 30px; }
    .video-wrapper { position: relative; padding-bottom: 56.25%; height: 0; margin-bottom: 20px; }
    .video-wrapper iframe { position: absolute; top: 0; left: 0; width: 100%; height: 100%; border-radius: 8px; }
    .status-dot { display: inline-block; width: 10px; height: 10px; border-radius: 50%; background: #ccc; }
    .completed .status-dot { background: #28a745; }
</style>


</head>
<body data-course-id="{{COURSE_ID}}" data-lesson-id="{{LESSON_ID}}">
    <nav class="navbar navbar-expand-lg navbar-dark bg-dark">
        <div class="container-fluid">
            <a href="/">Headless University</a>
            &lt;span class="navbar-text text-white"&gt;Course Portal&lt;/span&gt;
        &lt;/div&gt;
    &lt;/nav&gt;
&amp;lt;div class=&quot;container&quot;&amp;gt;
    &amp;lt;div class=&quot;lesson-container&quot;&amp;gt;

        &amp;lt;aside class=&quot;lesson-sidebar&quot;&amp;gt;
            &amp;lt;h4 class=&quot;mb-3&quot;&amp;gt;Course Modules&amp;lt;/h4&amp;gt;
            {{LESSON_SIDEBAR}}
            &amp;lt;div class=&quot;mt-4&quot;&amp;gt;
                &amp;lt;button id=&quot;mark-complete-btn&quot; class=&quot;btn btn-success w-100&quot;&amp;gt;Mark Lesson Complete&amp;lt;/button&amp;gt;
            &amp;lt;/div&amp;gt;
        &amp;lt;/aside&amp;gt;


        &amp;lt;main class=&quot;lesson-body&quot;&amp;gt;
            &amp;lt;h1 class=&quot;mb-4&quot;&amp;gt;{{LESSON_TITLE}}&amp;lt;/h1&amp;gt;


            &amp;lt;div class=&quot;video-wrapper&quot;&amp;gt;
                &amp;lt;iframe src=&quot;{{VIDEO_URL}}&quot; frameborder=&quot;0&quot; allow=&quot;accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture&quot; allowfullscreen&amp;gt;&amp;lt;/iframe&amp;gt;
            &amp;lt;/div&amp;gt;

            &amp;lt;article class=&quot;lesson-text-content mt-4&quot;&amp;gt;
                {{LESSON_CONTENT}}
            &amp;lt;/article&amp;gt;
        &amp;lt;/main&amp;gt;
    &amp;lt;/div&amp;gt;
&amp;lt;/div&amp;gt;


&amp;lt;script src=&quot;/assets/js/lms-tracker.js&quot;&amp;gt;&amp;lt;/script&amp;gt;


&lt;/body&gt;
&lt;/html&gt;

This template serves as our structural canvas. When our WP-CLI script runs, it swaps the placeholders like {{LESSON_TITLE}} and {{LESSON_CONTENT}} with actual clean HTML from our WordPress database, saving it into our output folder.

Part 3: Caching and Routing with Custom Nginx Configurations

Now that we have static HTML lesson pages generated, we need to instruct our web server on how to handle traffic. We want Nginx to deliver static pages first, but keep dynamic fallback options open in case users attempt to access a course that hasn't been compiled yet.

Here is the custom Nginx server block configuration. It includes file compression rules, custom caching lifetimes for our lesson assets, and automatic fallbacks for missing content:

# Add this file to /etc/nginx/sites-available/static-lms

server {
    listen 80;
    server_name static-lms-university.com;
    root /var/www/static-lms;
    index index.html;
# 1. Enable Brotli or Gzip Compression for fast delivery
gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 6;
gzip_types text/plain text/css text/xml application/json application/javascript application/xml+rss image/svg+xml;

# 2. Manage assets caching
location /assets/ {
    expires 30d;
    add_header Cache-Control "public, max-age=2592000, immutable";
    access_log off;
}

# 3. Main Routing Engine
location / {
    # Check for static HTML page matches first
    # Example: /course-title/lessons/lesson-title -> /course-title/lessons/lesson-title.html
    try_files $uri $uri/ $uri.html @wordpress_fallback;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Content-Type-Options "nosniff";
}

# 4. Fallback Router
# If a course is newly published and not yet compiled, Nginx sends the request 
# back to the headless WordPress backend dynamically.
location @wordpress_fallback {
    proxy_pass http://headless-wp-backend.local;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_redirect off;
}

# Disable logging for favicon and robots.txt to reduce server disk IO load
location = /favicon.ico { access_log off; log_not_found off; }
location = /robots.txt  { access_log off; log_not_found off; }

# Error handling redirect page
error_page 404 /404.html;


}

Why is this fallback rule helpful?

Static compilers are fantastic, but they can take time to run if you have thousands of pages. By using Nginx's try_files with a @wordpress_fallback block, we get the best of both worlds.

If Nginx finds a pre-compiled HTML file on the disk, it returns it instantly (taking less than 5 milliseconds). If a teacher has just published a lesson and the compiler hasn't run yet, Nginx catches the request and passes it to the live WordPress server, so the student never sees a 404 error page.

Part 4: Client-Side Progress Tracking with Vanilla JS

In a standard LMS, when a user clicks "Mark Lesson Complete," the browser sends a request to the server, writes a database row to the wp_usermeta table, and reloads the page. This is a massive waste of resources.

In our static setup, we handle tracking entirely in the browser using the browser's local storage database (IndexedDB or LocalStorage). When a user completes a lesson, we update their local records instantly, refresh the visual sidebar icons without reloading the page, and queue a background sync to update our server database whenever the student has a stable internet connection.

Here is the tracking script: /var/www/static-lms/assets/js/lms-tracker.js.

// lms-tracker.js

(function() {
    // Read identifiers from HTML body tags
    const courseId = document.body.getAttribute('data-course-id');
    const lessonId = document.body.getAttribute('data-lesson-id');
    const completeBtn = document.getElementById('mark-complete-btn');
if (!courseId || !lessonId) return;

// Load current course progress database from LocalStorage
function getProgressData() {
    const data = localStorage.getItem('lms_progress_db');
    return data ? JSON.parse(data) : {};
}

// Save progress updates to LocalStorage
function saveProgressData(data) {
    localStorage.setItem('lms_progress_db', JSON.stringify(data));
}

// Update the visual status icons in the sidebar navigation
function updateSidebarStatus() {
    const progress = getProgressData();
    const completedLessons = progress[courseId] || [];

    const sidebarLinks = document.querySelectorAll('.lesson-sidebar-list a');
    sidebarLinks.forEach(link => {
        const linkLessonId = link.getAttribute('data-lesson-id');
        if (completedLessons.includes(parseInt(linkLessonId))) {
            link.classList.add('completed');
        } else {
            link.classList.remove('completed');
        }
    });
}

// Toggle the completion status for the current lesson
function toggleLessonCompletion() {
    const progress = getProgressData();
    if (!progress[courseId]) {
        progress[courseId] = [];
    }

    const lessonInt = parseInt(lessonId);
    const index = progress[courseId].indexOf(lessonInt);

    if (index === -1) {
        // Mark complete
        progress[courseId].push(lessonInt);
        if (completeBtn) completeBtn.textContent = "Completed (Click to Reset)";
    } else {
        // Remove completion
        progress[courseId].splice(index, 1);
        if (completeBtn) completeBtn.textContent = "Mark Lesson Complete";
    }

    saveProgressData(progress);
    updateSidebarStatus();

    // Push sync queue update to server background sync
    scheduleSyncWithServer(courseId, lessonInt, index === -1);
}

// Queue updates to sync with server when network is stable
function scheduleSyncWithServer(course, lesson, completed) {
    let syncQueue = JSON.parse(localStorage.getItem('lms_sync_queue') || '[]');

    syncQueue.push({
        course_id: course,
        lesson_id: lesson,
        completed: completed,
        timestamp: Date.now()
    });

    localStorage.setItem('lms_sync_queue', JSON.stringify(syncQueue));
    processSyncQueue();
}

// Process the queued sync updates
function processSyncQueue() {
    if (!navigator.onLine) return; // Wait if browser is offline

    const queue = JSON.parse(localStorage.getItem('lms_sync_queue') || '[]');
    if (queue.length === 0) return;

    const nextItem = queue[0];

    // Send a lightweight POST request to our headless API endpoint
    fetch('/api/v1/sync-progress', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(nextItem)
    })
    .then(response => {
        if (response.ok) {
            // Remove the item from queue if sent successfully
            queue.shift();
            localStorage.setItem('lms_sync_queue', JSON.stringify(queue));
            // Continue processing remaining queue items recursively
            processSyncQueue();
        }
    })
    .catch(err => {
        console.warn('Sync server connection failed. Retrying later.', err);
    });
}

// Initialize page visual states
function init() {
    const progress = getProgressData();
    const completedLessons = progress[courseId] || [];

    if (completedLessons.includes(parseInt(lessonId))) {
        if (completeBtn) completeBtn.textContent = "Completed (Click to Reset)";
    }

    updateSidebarStatus();

    if (completeBtn) {
        completeBtn.addEventListener('click', toggleLessonCompletion);
    }

    // Check for pending background syncs
    window.addEventListener('online', processSyncQueue);
    processSyncQueue();
}

init();


})();

Why is this progress tracker so reliable?

• Zero Lag: When a user completes a lesson, the sidebar updates instantly without waiting for a server confirmation.
• Offline Capability: If a student is taking classes in a train tunnel or on an airplane, the completion data saves locally on their device. The moment they reconnect to Wi-Fi, the background script runs and syncs the data back to the server.
• Server Performance: The server only receives a simple REST API call to sync progress data instead of rebuilding an entire dynamic web page with heavy PHP components.

Part 5: Clean Code Assets and Platform Security

When you build a dynamic-to-static pipeline like this, you must ensure that your base template code is clean, original, and free of hidden scripts.

A major pitfall for junior developers is looking for free "nulled" templates from unverified web search results. If you write an automated compiler script over a template downloaded from a random forum, you risk injecting hidden malicious scripts into your entire course archive.

Nulled themes often contain malicious redirect scripts, hidden tracking pixels, and SEO link spam. Because our static compiler runs across all our HTML pages, if our base template contains a single hidden security vulnerability, it will copy that security vulnerability onto every course page we generate. Your site can be flagged as malicious, and Google will drop your domain from search results.

I always recommend getting your layouts from verified, legal sources. If you want a clean baseline for your portal, I recommend going to a trusted resource for your HTML Template download assets.

For our deployment, we obtained our clean, original files from GPLPAL. This guaranteed that the underlying CSS, layout structure, and JavaScript files were pristine and unmodified. It saved us days of auditing dirty source code and kept our client's user data secure.

Part 6: Measuring Performance Improvements

After migrating the university from their heavy dyn-LMS plugin to our headless WP-CLI static compiler setup, we ran standard performance audits to compare metrics.

Here is what we observed after two weeks of load testing and analyzing production logs:

Summary and Best Practices

Static compilation isn't just for blogs or documentation pages. It is a highly viable approach for heavy learning management platforms, online colleges, and course portals.

If your platform is struggling to stay online during busy weeks, consider making these structural adjustments:

1. Decouple your content generation: Keep your favorite CMS (like WordPress) as an editing dashboard, but don't let your visitors access the live PHP database directly.
2. Automate with WP-CLI: Write a custom command-line compiler to output your course catalog, modules, and lessons as static HTML files.
3. Use Nginx as an optimized router: Configure try_files with a dynamic backend fallback so that any pages that haven't compiled yet load without error.
4. Move tracking client-side: Save student course completions in LocalStorage and sync it with your database asynchronously when they are online.
5. Always audit your code base: Start with verified design packages to ensure no hidden malicious code gets compiled into your static files.

By using high-performance assets and separating your database from your actual page delivery pipeline, you can build educational web platforms that load instantly, scale efficiently, and remain highly stable under heavy traffic.