Setting up the viewer app

The standalone viewer is a React application deployed to your web root that reads debug.log and query logs directly from the filesystem. It runs independently of WordPress — no wp-load.php, no database queries, no WordPress functions. If WordPress crashes, the viewer still works.

What the viewer does

The viewer provides a browser-based interface for reading error logs and query data without relying on WordPress. It has its own PHP API (api.php) that reads files directly, its own authentication system, and its own rate limiter. This separation means you can diagnose the problem that broke WordPress using the viewer, rather than needing WordPress to work in order to debug it.

Setup wizard

The fastest way to install the viewer is through the admin dashboard.

1. Go to WP Debug Toolkit > Overview.
2. Click Install Viewer (or press I).
3. Enter a password. This is mandatory and must be at least 8 characters. You use this password to log into the viewer — it is separate from your WordPress credentials.
4. Optionally, change the URL slug. The default is /wpdebugtoolkit/. You can set a custom slug like /debug-viewer/ or /wpdt/.
5. Click Install.

WP Debug Toolkit (WPDT) deploys the viewer files to a directory in your web root and confirms the URL where you can access it.

What gets deployed

The setup wizard copies these files to your web root (e.g., /var/www/html/wpdebugtoolkit/):

File	Purpose
index.php	Entry point that loads the React app
React build files (HTML, CSS, JS)	The viewer interface
api.php	Standalone PHP API — reads logs and manages settings without WordPress
config.php	Configuration — log paths, viewer settings, generated during setup
auth.php	Password hash for viewer authentication
rate-limiter.php	SQLite-based brute-force protection
settings-manager.php	SQLite-based viewer settings storage

None of these files depend on WordPress. They use plain PHP and direct filesystem access.

Verifying the installation

After setup, visit the viewer URL in your browser:

(example): https://yoursite.com/wpdebugtoolkit/

You see a login screen. Enter the password you set during installation. After logging in, the viewer displays the error log (or an empty state if no errors have been logged yet).

WP-CLI alternative

Install the viewer from the command line:

wp dbtk viewer setup --password=MySecurePass123

Example output:

Setting up viewer...
Success: Viewer installed at: https://example.com/wpdebugtoolkit/

Check the viewer status:

wp dbtk viewer status

Example output:

+---------------------+----------------------------------------------+
| Field               | Value                                        |
+---------------------+----------------------------------------------+
| Installed           | Yes                                          |
| URL directory       | wpdebugtoolkit                               |
| Password protection | Enabled                                      |
| Full URL            | https://example.com/wpdebugtoolkit/          |
+---------------------+----------------------------------------------+

After setup: repair and redeploy

Repairing permissions

If the viewer stops working after a server migration, hosting change, or manual file transfer, the file permissions may need resetting. Go to Debug Toolkit > Settings > Viewer and click Repair Viewer. This sets directories to 0755 and files to 0644 across the viewer directory.

Redeploying after a plugin update

When you update WPDT, the viewer files on the web root may be outdated. Reinstall the viewer from Debug Toolkit > Settings > Viewer to copy fresh files. Your password, configuration, and settings are preserved — you do not need to reconfigure anything.

Permission elevation

On some hosts, wp-config.php is read-only. WPDT includes automatic permission elevation that temporarily makes the file writable, applies changes (like toggling debug constants), and restores the original permissions. This works on most standard hosting environments. It does not work on hosts that lock wp-config.php at the platform level (like Flywheel). See Permission elevation for details.

For full details on viewer lifecycle management, see Managing the viewer.

Troubleshooting

Permission errors during setup

The PHP process needs write access to your web root directory to create the viewer folder. If setup fails with a permission error:

• Check that the web server user (e.g., www-data, nginx, apache) has write permission on the web root.
• On most setups, the web root is the same directory that contains wp-config.php and wp-content/. Verify with your hosting provider if you are unsure.
• WPDT attempts automatic permission elevation if the web root is not writable. If elevation fails, you need to fix permissions manually or contact your host.
• You can check permissions from the command line:

ls -la /path/to/web/root/

The web root directory needs 755 permissions and should be owned by (or writable by) the web server user.

WordPress in a subfolder

If WordPress is installed in a subdirectory (e.g., https://example.com/blog/), the viewer is deployed relative to the WordPress installation’s web root. The viewer URL reflects the actual deployment location. Check the URL shown in the setup confirmation or run wp dbtk viewer status.

Non-standard web root locations

Some hosting environments use non-standard web root paths. WPDT attempts to detect the web root automatically. If the detection fails, the setup wizard shows an error. Contact your hosting provider to confirm the web root path, then use the DBTK_VIEWER_DIR constant in wp-config.php if you need to override the directory name:

define( 'DBTK_VIEWER_DIR', 'my-debug-viewer' );

Viewer shows a 404 or blank page

• Confirm the viewer directory exists on the server at the expected path.
• Check that index.php is present inside the viewer directory.
• If you use a caching plugin or CDN, clear the cache after installation.
• Some servers require an .htaccess file or nginx rewrite rule. The viewer includes its own .htaccess for Apache. For nginx, you may need to add a try_files directive for the viewer directory.