Fix: Wagtail Admin Static Files Missing In NixOS

by Alex Johnson 49 views

Introduction

Are you experiencing issues with missing admin static files when building Wagtail from the GitHub source in python313Packages? This article dives into a critical bug affecting Wagtail installations within the NixOS environment. Specifically, we're addressing the problem where CSS and JavaScript files are absent when building Wagtail from the GitHub source, rendering the admin interface unusable. This issue, introduced after commit 6a2cb5059ac72716d95a4d73c3697106a6c4ea3d (PR #461519), stems from a switch in the package source from PyPI to GitHub without the necessary static asset compilation step.

Understanding the Issue

The core of the problem lies in how Wagtail's static assets are handled in the Nix build process. When Wagtail is sourced from PyPI, these assets are pre-built and included in the package. However, when building from the GitHub source, these static files need to be compiled using tools like npm or yarn. The recent switch to the GitHub source in Nixpkgs didn't incorporate this compilation step, leading to the missing static files. This means that when you try to run Wagtail, the admin interface lacks styling and JavaScript functionality, effectively breaking the CMS.

Impact on Users

The absence of these static files has a significant impact on Wagtail users within the NixOS ecosystem. Whether you're in a development or production environment, this issue prevents you from using Wagtail effectively. The admin interface, which is crucial for content management, appears broken and unstyled. Moreover, the collectstatic command, essential for deploying Wagtail, fails to find the required assets. This makes the current Wagtail package in nixpkgs essentially unusable without implementing workarounds.

Identifying the Bug

To identify if you are affected by this bug, follow these steps:

  1. Update Nixpkgs: Ensure you are on a nixpkgs revision that includes commit 6a2cb5059ac72716d95a4d73c3697106a6c4ea3d or later.

  2. Create a Shell Environment: Use the following Nix expression to create a shell environment with Wagtail:

    { pkgs ? import <nixpkgs> {} }:
pkgs.mkShell {
  packages = [ pkgs.python3.pkgs.wagtail ];
}

  3. Enter the Shell: Run nix develop to enter the development environment.

  4. Check for Static Files: Execute the following commands to check for the existence of the static files directory:

    python -c "import wagtail; print(wagtail.__file__)"
ls -la $(python -c "import wagtail; print(wagtail.__path__[0])")/admin/static/wagtailadmin/css/

    If the static/ directory does not exist, you are experiencing this issue.

  5. Alternative Verification: Create a Django project with Wagtail and run python manage.py runserver. If you see Django warnings about missing Wagtail admin CSS, this confirms the bug.

Expected Behavior

The expected behavior of the Wagtail package is to include all necessary static files, mirroring the functionality of the PyPI distribution. This means:

  • Running python manage.py runserver should provide a fully functional Wagtail admin interface.
  • python manage.py collectstatic should correctly collect all Wagtail admin static files for deployment.
  • The package should maintain the same file structure as the PyPI package, including the wagtail/admin/static/wagtailadmin/ directory.

Essentially, Wagtail should work out-of-the-box without requiring manual intervention or workarounds.

Temporary Workaround

While a permanent fix is being implemented, a temporary workaround is available. You can override the Wagtail source back to PyPI by adding the following to your Nix configuration:

wagtail-override = python.pkgs.wagtail.overridePythonAttrs (old: {
  src = python.pkgs.fetchPypi {
    pname = "wagtail";
    version = "7.2";
    hash = "sha256-ijnfkIvWSrAp4IvxkfR19UzJFPhKpB6a55tBv0HVXsM=";
  };
});

This override instructs Nix to fetch Wagtail from PyPI, which includes the pre-built static assets. This workaround allows you to continue using Wagtail while the underlying issue is resolved.

Technical Details and Root Cause

The root cause of this issue can be traced back to the switch from PyPI to GitHub as the source for the Wagtail package in nixpkgs. The original code even contained a comment acknowledging this limitation:

# The GitHub source requires some assets to be compiled, which in turn
# requires fixing the upstream package lock. We need to use the PyPI release
# until https://github.com/wagtail/wagtail/pull/13136 gets merged.

This comment indicates that the maintainers were aware of the need for a static asset compilation step when using the GitHub source. However, the switch was made prematurely without implementing this crucial step. The PyPI releases come with pre-built static files, whereas the GitHub source necessitates running npm or yarn build processes, which are currently absent in the Nix build.

Examining the Logs

The issue manifests itself in several ways. When attempting to access the Wagtail admin interface, you'll notice a complete lack of styling and JavaScript functionality. Examining the logs, you'll likely see errors related to missing CSS files. For instance, running python manage.py runserver will produce warnings like:

WARNINGS:
?: (wagtailadmin.W001) CSS for the Wagtail admin is missing
    HINT:
        Most likely you are running a development (non-packaged) copy of
        Wagtail and have not built the static assets

        File not found: /nix/store/fa3iyp7xm5qrmaj10x58ld26zk46kv9m-python3.13-wagtail-7.2/lib/python3.13/site-packages/wagtail/admin/static/wagtailadmin/css/core.css

This clearly indicates that the necessary CSS files are missing from the Wagtail installation.

Comparing Correct vs. Incorrect Installations

To further illustrate the problem, let's compare the file structure of a Wagtail installation built from PyPI (correct) with one built from the problematic GitHub source (incorrect).

Incorrect (GitHub Source):

$ nix develop
$ python -c "import wagtail; print(wagtail.__file__)"
/nix/store/fa3iyp7xm5qrmaj10x58ld26zk46kv9m-python3.13-wagtail-7.2/lib/python3.13/site-packages/wagtail/__init__.py

$ ls -la /nix/store/fa3iyp7xm5qrmaj10x58ld26zk46kv9m-python3.13-wagtail-7.2/lib/python3.13/site-packages/wagtail/admin/static/wagtailadmin/css/
ls: cannot access '/nix/store/fa3iyp7xm5qrmaj10x58ld26zk46kv9m-python3.13-wagtail-7.2/lib/python3.13/site-packages/wagtail/admin/static/wagtailadmin/css/': No such file or directory

Correct (PyPI Source):

python -c "import wagtail; print(wagtail.__file__)")"
/nix/store/6jdvxpankc4dpmqcis67kkd5hnisjy7m-python3.13-wagtail-7.2/lib/python3.13/site-packages/wagtail/__init__.py
$ ls -la $(python -c "import wagtail; print(wagtail.__path__[0])")/admin/static/wagtailadmin/css/
total 288
dr-xr-xr-x 3 root root   4096 Jan  1  1970 .
dr-xr-xr-x 5 root root   4096 Jan  1  1970 ..
-r--r--r-- 1 root root 280121 Jan  1  1970 core.css
-r--r--r-- 1 root root      0 Jan  1  1970 core.js
dr-xr-xr-x 2 root root   4096 Jan  1  1970 panels

This comparison clearly shows the absence of the static directory and its contents in the incorrect installation, confirming the missing static files issue.

Steps to Resolve the Issue

To resolve this issue, the Nix build process needs to incorporate a step that compiles the static assets when building from the GitHub source. This typically involves using npm or yarn to run the necessary build scripts defined in Wagtail's package.json. The exact steps to implement this within the Nix environment may involve creating a custom build phase that executes these commands.

Notify Maintainers

The maintainers of the nixpkgs package, including @GaetanLepage and @sephii, have been notified about this issue. Addressing this bug is crucial for ensuring a smooth Wagtail experience for NixOS users.

Conclusion

The missing admin static files issue in the Wagtail package within nixpkgs represents a significant problem for users relying on this CMS in a NixOS environment. The switch to the GitHub source without implementing the necessary static asset compilation step has rendered the admin interface unusable. While a temporary workaround exists by overriding the source back to PyPI, a permanent solution requires incorporating a build process that compiles these assets. By understanding the root cause and impact of this bug, we can work towards a more robust and user-friendly Wagtail experience on NixOS.

For more information on Wagtail, you can visit the official Wagtail website at https://wagtail.org/.