URL Rewriting and 301 Redirects: Fixing 404s and Old Links

Inner pages returning 404 after install, or old links breaking after an address change, usually mean URL rewriting is not configured. This guide covers nginx/Apache setup, the URL format switch and 301 behaviour.

After installing KingCMS the home page opens but inner pages return 404, or old links break after you change a category or article address. Both usually come down to URL rewriting and 301 redirects. This guide explains why it happens, how to configure nginx or Apache, how the admin switch works, and why old addresses redirect automatically.

Front-end addresses are not real directories

A front-end address such as /news/hello-world is only a route; there is no such directory on disk. Except for real files (/assets/, images), every request goes to x1/public/index.php, and the application resolves the slug to a category, page, article or product. The site root must therefore point to x1/public/, not to the repository root or x1/.

nginx configuration

Add two blocks to the site's server block: try_files sends unknown paths to index.php, and the location block passes PHP requests to php-fpm.

server {
    listen 80;
    server_name cms.example.com;
    root /var/www/kingcms/x1/public;
    index index.php;
    location / { try_files $uri $uri/ /index.php?$query_string; }
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.4-fpm.sock;
    }
}

Adjust the php-fpm socket to your PHP version. Run nginx -t before reloading.

Apache configuration

Enable mod_rewrite (a2enmod rewrite) and allow .htaccess in the site directory (AllowOverride All). The public/ directory already ships a .htaccess that forwards missing files and directories to index.php and keeps the query string:

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.php [QSA,L]

The "URL format" setting

Admin → Settings → Basic information has a URL format setting. Pretty URLs (/category/article) need the server configuration above; compatibility mode (/?category/article&page=2) works without it. When you switch to pretty URLs and save, the application requests /healthz to verify that rewriting works; if the check fails the save is rejected and the old value is kept — configure the server first, then flip the switch.

301 redirects for old addresses

When a category or article address changes, the application automatically keeps a 301 redirect from the old address to the new one; you do not write redirect rules by hand. If an old link still returns 404, first confirm it came from a rename; if not, check that rewriting is active on the server.

Common problems

Home page works, inner pages 404: on nginx check that try_files points to /index.php; on Apache check mod_rewrite and AllowOverride.
Home page also 404: check that the site root points to x1/public/ and that index.php exists.
Images do not load: images live in x1/data/uploads/, outside the site root; configure a /media/ alias on nginx and disable PHP execution there.
Old link 404 after a rename: confirm the old address really came from a rename; the application adds the 301 automatically.

For installation and server preparation see Installation & Environment; for upgrades see Online Upgrade.