Index of every page on this site: llms.txt
All skills
Run it yourself

Use this skill whenever creating, configuring, or hardening Apache .htaccess files in a Bolt CMS repository. Implements the production two-tier .htaccess architecture: root-level HTTPS redirection and ./public directory forwarding for web hosts, plus public/.htaccess protection — an allowlist for theme/, files/ and thumbs/ (only built assets and accepted upload types are served, everything else is 403), a safety-net deny list for sources, configs, dumps and .env files elsewhere in public/, and security headers for static files (HSTS, nosniff, sandboxed uploads).

  • 4 files
  • 64.1 KB
  • Updated last month
  • GitHub
Use this Skill: https://skilld.dev/gh/vondry/bolt-skills/bolt-htaccess

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈146 tokens for metadata: the name and description. ≈7.7k when used: this file.

Description uses 7.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈584 characters, or 7.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Bolt CMS Apache .htaccess Configuration & Source Code Hardening

In Bolt CMS deployments running on Apache (such as shared hosting, VPS setups, or traditional virtual hosts), proper .htaccess configuration is critical for both routing and security.

This skill documents the production-tested two-tier .htaccess architecture established across active Bolt CMS installations:

  1. Root /.htaccess: Enforces HTTPS and transparently routes all requests into the ./public/ document root.
  2. Public /public/.htaccess: Hardens Symfony's front controller rewrite rules, enforces UTF-8 character encoding, serves only known static files from the theme, upload and thumbnail folders (allowlist), denies sources, configuration, dumps and .env* files everywhere else, and sends security headers with the files Apache serves itself.

Pages rendered by Symfony get their security headers from nelmio_security; that configuration, secrets and the rest of the application hardening are in bolt-security-hardening.


Architecture Overview

Project Root (/)
├── .htaccess                       # Tier 1: HTTPS redirect & rewrite traffic into public/
├── .env, composer.json, src/, ...  # Protected behind project root (never exposed)
└── public/                         # Web Document Root
    ├── .htaccess                   # Tier 2: front controller, allowlist, deny list, headers
    ├── index.php                   # Front controller entrypoint
    ├── assets/                     # Bolt admin assets (deny list applies)
    ├── files/                      # Uploads — allowlist: accepted upload types only, sandboxed
    ├── thumbs/                     # Thumbnails — allowlist: same types; missing ones go to Bolt
    └── theme/<theme_name>/         # Theme — allowlist: only css/, js/, img/, images/, fonts/
        ├── css/index.css           # ✅ served
        ├── js/app.js               # ✅ served
        ├── img/logo.svg            # ✅ served
        ├── js/src/app.ts           # 🛑 403 (not a static file type)
        ├── theme.yaml              # 🛑 403 (outside the public folders)
        ├── index.twig              # 🛑 403
        ├── package.json            # 🛑 403
        ├── rollup.config.js        # 🛑 403
        └── node_modules/           # 🛑 403

The Core Problems Solved

Problem 1: Unpointed DocumentRoot (Root Directory Exposure)

Many shared hosting providers (e.g. Wedos, Český hosting, Active24, cPanel) default the domain's document root to the project root directory rather than ./public/.

Without a root /.htaccess:

  • Visitors must type example.com/public/ to reach the website.
  • Sensitive root files (.env, composer.json, composer.lock, src/, config/bolt/, var/) could be browsed and downloaded over plain HTTP if Apache directory indexing or direct file access is allowed.

Problem 2: Bolt Theme Source Code Leakage (public/theme/)

In Bolt CMS, theme assets and templates reside under public/theme/<themename>/. Modern frontend workflows bundle development files alongside the theme: Twig templates, theme.yaml, package.json, tsconfig.json, TypeScript and SCSS sources, bundler configs, node_modules/, docs, design files and .DS_Store.

By default, Symfony's public/.htaccess rule (RewriteCond %{REQUEST_FILENAME} !-f) tells Apache: if a requested file exists on disk, serve it directly — https://example.com/theme/<themename>/theme.yaml and …/package.json download for anyone.

Problem 3: Scripts in Uploads (public/files/)

Uploads are served from the site's own origin. An .html or .svg file uploaded by an editor (or placed there over SFTP) runs its scripts as the site when opened directly — next to a logged-in administrator's session (stored XSS).

Why an allowlist, not only a deny list

A deny list leaks every file type nobody thought of (.scss, .vue, .bak, a new bundler's config). In the folders that mix public files with sources or uploads, the allowlist serves only what browsers need and answers 403 for everything else, so a forgotten type stays private.

Performance: neither approach costs anything measurable. Apache compiles each pattern once and tests it against a short path in microseconds; re-reading the .htaccess files on every request costs more, and a PHP page takes tens of milliseconds. A missing theme asset even gets cheaper: Apache answers 403 itself instead of booting Bolt for a 404 page.


Step-by-Step Implementation

Step 1: Create or Update Root .htaccess

Create /.htaccess at the root of the project (alongside composer.json and config/) — only when the domain's document root is the project root. If the host lets you point the domain at public/, do that instead and skip this file:

# /.htaccess
RewriteEngine on

# HSTS also on the redirects below (www → canonical host, HTTP → HTTPS): they are answered here,
# before public/.htaccess adds its headers. Browsers ignore the header on plain HTTP.
<IfModule mod_headers.c>
    Header always set Strict-Transport-Security "max-age=31536000"
</IfModule>

# Canonical host: the site answers on one host; the other one redirects to it in a single hop
# (straight to HTTPS). Default: without www — www.example.cz → https://example.cz. For a site whose
# canonical host is www, replace the two lines with (it also redirects localhost and staging hosts —
# add a RewriteCond %{HTTP_HOST} !^(localhost|staging\.) [NC] for those):
#   RewriteCond %{HTTP_HOST} !^www\. [NC]
#   RewriteRule (.*) https://www.%{HTTP_HOST}/$1 [L,R=301]
# The redirects use $1 (the path relative to this folder), not %{REQUEST_URI}: hosts that serve a
# domain from a subfolder of the webroot (WEDOS: www/domains/<domain>/) forward it there with an
# internal rewrite, so REQUEST_URI carries that prefix (www.example.cz/ →
# https://example.cz/domains/example.cz/). Apache keeps the query string.
RewriteCond %{HTTP_HOST} ^www\.(.+)$ [NC]
RewriteRule (.*) https://%1/$1 [L,R=301]

# HTTPS redirect — works both on direct Apache TLS and behind a TLS-terminating proxy:
# redirect when Apache itself did not receive HTTPS AND no proxy reported an HTTPS request.
RewriteCond %{HTTPS} off
RewriteCond %{HTTP:X-Forwarded-Proto} !https
RewriteRule (.*) https://%{HTTP_HOST}/$1 [L,R=301]

# Redirect all traffic to ./public folder
RewriteRule (.*) public/$1 [QSA,L]
Directive Breakdown:
  • HSTS block: the redirects below are answered by this file, before public/.htaccess adds its headers — without it the www → canonical and HTTP → HTTPS redirects carry no Strict-Transport-Security.
  • Canonical host (www → without www): both example.cz and www.example.cz must work, but only one may serve the site. Otherwise every page exists twice (Bolt's canonical link follows the requested host when BOLT_CANONICAL is empty), sessions and HSTS are split between two origins, and the second host is easily forgotten in checks. The rule needs no domain name, so the file is identical in every project; it redirects straight to https://, one hop. Also set BOLT_CANONICAL=https://example.cz (bolt-security-hardening, Step 1). The certificate must cover both hosts (example.cz + www.example.cz, or a wildcard).
  • RewriteEngine on: Initializes the Apache rewrite engine. Without mod_rewrite the file causes an error 500 for every request — the site fails closed instead of exposing the project root.
  • RewriteCond %{HTTPS} off: Apache itself did not receive the request over TLS (plain HTTP on a direct connection — or any request behind a proxy that terminates TLS).
  • RewriteCond %{HTTP:X-Forwarded-Proto} !https: No reverse proxy, load balancer or Cloudflare reported that the visitor used HTTPS. A missing header also matches, so direct HTTP requests are redirected.
  • The two conditions are combined with AND: redirect only when neither Apache nor a proxy saw HTTPS. Do not use ^http$ for the header condition — without a proxy the header is absent, the condition never matches, and plain HTTP is never redirected.
  • RewriteRule (.*) https://%{HTTP_HOST}/$1 [L,R=301]: Issues an HTTP 301 Permanent Redirect to HTTPS. Both redirects build the target from $1, never from %{REQUEST_URI} (Pitfall 9).
  • RewriteRule (.*) public/$1 [QSA,L]: Transparently rewrites the URL into the public/ directory without changing the URL visible in the user's browser. QSA preserves query parameters (?page=2), and L stops further rewriting in the root context.

Document root on public/ (no root file): put the canonical-host and HTTPS rules at the top of the <IfModule mod_rewrite.c> block of public/.htaccess instead:

    RewriteCond %{HTTP_HOST} ^www\.(.+)$ [NC]
    RewriteRule (.*) https://%1/$1 [L,R=301]
    RewriteCond %{HTTPS} off
    RewriteCond %{HTTP:X-Forwarded-Proto} !https
    RewriteRule (.*) https://%{HTTP_HOST}/$1 [L,R=301]

Step 2: Allowlist for theme/, files/ and thumbs/

In public/.htaccess, inside <IfModule mod_rewrite.c> directly after RewriteEngine On and the node_modules / .git rule — before Symfony's front-controller rules:

    # First, right after RewriteEngine On: no front controller and no hosting folder in the
    # requested URL — Symfony would take them as the base URL (Pitfall 10).
    RewriteCond %{THE_REQUEST} ^\S+\s([^?\s]*?)/index\.php(?:/([^?\s]*))?(?:\?\S*)?\s
    RewriteRule ^ https://%{HTTP_HOST}%1/%2 [R=301,L,NE]
    RewriteCond %{THE_REQUEST} ^\S+\s[^?\s]*index\.php
    RewriteRule ^ - [R=404,L]
    RewriteCond %{HTTP_HOST}::%{THE_REQUEST} ^([^:]+)::\S+\s/domains/\1(?:/public)?(?:/([^?\s]*))?(?:\?\S*)?\s [NC]
    RewriteRule ^ https://%1/%2 [R=301,L,NE]

    # Theme build folders: node_modules/ and .git/ are never served.
    RewriteRule (^|/)(node_modules|\.git)(/|$) - [F,L]

    # Only the front controller runs PHP: a forgotten info.php or adminer.php is refused.
    RewriteRule ^(?!index\.php$).+\.php$ - [F,L]

    # theme/<theme>/: the built assets in css/, js/, img/, images/ and fonts/. Templates, theme.yaml,
    # package.json, build configs, TypeScript sources and anything at the theme root are denied.
    RewriteCond $0 !^theme/[^/]+/(css|js|img|images|fonts)/([^/]+/)*[^/]+\.(css|js|avif|gif|ico|jpe?g|png|svg|webp|woff2?|ttf|otf|webmanifest|xml|pdf|mp4|webm)$ [NC]
    RewriteRule ^theme/.* - [F,L]

    # files/ (uploads) and thumbs/ (thumbnails): only the file types an upload may have.
    RewriteCond $0 !\.(avif|gif|ico|jpe?g|png|svg|tiff?|webp|pdf|txt|docx?|xlsx?|pptx?|epub|zip|tgz|mp3|ogg|wav|m4a|mp4|m4v|ogv|webm|wmv|avi)$ [NC]
    RewriteRule ^(files|thumbs)/.* - [F,L]
Folder Served Everything else
theme/<theme>/ files in css/, js/, img/, images/, fonts/ (any depth) with a static type: styles, scripts, images, fonts, webmanifest, xml (browserconfig), pdf, mp4, webm 403 — templates, theme.yaml, package.json, *.config.js, js/src/*.ts, the theme root, node_modules/
files/ the upload types of accept_file_types / accept_media_types (bolt-security-hardening) plus svg for SVGs uploaded earlier 403 — .html, .php, .js, .sql, … even if they get there over SFTP
thumbs/ the same types; a thumbnail that does not exist yet passes on to Bolt, which generates it 403
  • How it works: $0 is the path relative to public/ (theme/acme/css/index.css). The RewriteCond lets allowlisted paths through to the normal rules; every other path under the folder is answered with [F] (403).
  • Theme folders: the convention of bolt-theme-init puts browser files in css/, js/ and img/. A theme that keeps public files elsewhere (a favicon at the theme root, dist/) — move them, or add the folder to the list.
  • Upload types: keep the files/ list in line with accept_file_types in config/bolt/config.yaml. A type the site accepts but this list lacks uploads fine and then answers 403.
  • css/tailwind/index.css (the Tailwind source) stays reachable: it is CSS, contains nothing private, and the allowlist works by folder and type, not by file.
  • PHP: only index.php runs. Any other *.php anywhere in public/ — a phpinfo page, an Adminer copy, a backup script left after an SFTP session — answers 403 instead of executing. Tested on Apache 2.4 with PHP-FPM: /info.php → 403, while /, /index.php, Bolt routes and built assets are served as before.
  • Nginx: the same allowlist for Nginx is in bolt-security-hardening/examples/docker/nginx_security.conf (its PHP location passes only index.php to PHP-FPM).

Step 3: Safety Net for the Rest of public/

The public root, assets/ and bundles/ are not covered by the allowlist. Directly below AddDefaultCharset UTF-8 add the deny list — it also protects the theme a second time:

<IfModule mod_authz_core.c>
    <FilesMatch "(\.(twig|ya?ml|neon|lock|ts|md|psd|ini|sql|sqlite3?|bak|old|orig|swp|log|sh|dist)|^\.DS_Store|^(composer|package|package-lock|tsconfig)\.json|\.config\.[cm]?js)$">
        Require all denied
    </FilesMatch>
    # Environment files (.env, .env.local, …) must never be served, wherever they end up.
    <FilesMatch "^\.env">
        Require all denied
    </FilesMatch>
</IfModule>

(The full template repeats both blocks with Order allow,deny / Deny from all for Apache 2.2.)

Pattern Matched files
twig, ya?ml, neon, md Templates, configuration, docs copied into public/
lock, ^(composer|package|package-lock|tsconfig)\.json, \.config\.[cm]?js, ts Dependency manifests and build tooling
sql, sqlite3?, bak, old, orig, swp, log, sh, dist Database dumps, backups, editor leftovers, logs, scripts
ini .user.ini (per-directory PHP settings on PHP-FPM hosts)
psd, ^\.DS_Store Design sources, macOS folder metadata (lists file names)
^\.env .env, .env.local, .env.prod.local

Step 4: Security Headers for Static Files

Pages rendered by Symfony get X-Frame-Options, nosniff, Referrer-Policy, Permissions-Policy and CSP from nelmio_security (bolt-security-hardening, Step 6). Files Apache serves itself get none of them — add this block after the deny list:

<IfModule mod_headers.c>
    # HTTPS only from now on. Browsers ignore the header on plain HTTP, so sending it always is safe.
    # Add "; includeSubDomains" only when every subdomain has a certificate.
    Header always set Strict-Transport-Security "max-age=31536000"

    # Do not advertise the PHP version.
    Header unset X-Powered-By
    Header always unset X-Powered-By

    # Files Apache serves itself get the basics nelmio_security sends with every page.
    <If "%{REQUEST_FILENAME} !~ m#\.php$#">
        Header always set X-Content-Type-Options "nosniff"
        Header always set Referrer-Policy "strict-origin-when-cross-origin"
    </If>

    # Uploads and thumbnails never run scripts — not even an HTML or SVG file opened directly.
    # PDFs are left out: Chrome refuses to show a PDF under a sandbox policy.
    <If "%{REQUEST_FILENAME} =~ m#/public/(files|thumbs)/# && %{REQUEST_FILENAME} !~ m#\.pdf$#i">
        Header always set Content-Security-Policy "default-src 'none'; img-src 'self' data:; media-src 'self'; style-src 'unsafe-inline'; sandbox"
    </If>
</IfModule>
  • HSTS comes from Apache, not from nelmio's forced_ssl (which loops behind TLS proxies). Start with max-age=31536000; add includeSubDomains / preload only when every subdomain serves HTTPS.
  • Sandboxed uploads: with sandbox, an SVG or HTML file opened directly has no origin and cannot run scripts — it cannot touch the admin session even if a malicious file got into files/. Images embedded with <img> are unaffected.
  • Why the conditions test REQUEST_FILENAME: after the root .htaccess rewrite, Apache's REQUEST_URI is /public/files/…, so ^/files/ would never match; the file path on disk works with both document-root layouts. PHP responses (index.php) are skipped so their nelmio headers are not sent twice.
  • Needs mod_headers (enabled on practically every host); without it the block is skipped.

Step 5: Project-Specific Customization Guidelines

  • More theme folders: add the folder name to (css|js|img|images|fonts) in Step 2 (e.g. dist).
  • More file types in the theme (e.g. json for a web app manifest named manifest.json): add the extension to the theme allowlist — never twig, yaml, ts or json in general.
  • More upload types: add them to accept_file_types (bolt-security-hardening) and to the files/ allowlist together. Never html, htm, js, css, php, phtml, svgz, xml.
  • Another front-end stack (SCSS, Vue, Svelte sources inside the theme): nothing to do — they are not in an allowlisted folder or not a static type.

Step 6: Asset Caching & Expiration (mod_expires.c)

In high-performance production projects, static media assets in public/ are served with aggressive 2-month caching. This is the only mod_expires block of the file: bolt-asset-caching documents the same block (CSS/JS are safe to cache long because partials/_master.twig appends ?v={{ theme.assets_version }}), so never add a second one:

# public/.htaccess

<IfModule mod_expires.c>
    ExpiresActive On

    # Images (uploads in public/files/ and disk thumbnails in public/thumbs/)
    ExpiresByType image/avif "access plus 2 months"
    ExpiresByType image/gif "access plus 2 months"
    ExpiresByType image/jpeg "access plus 2 months"
    ExpiresByType image/png "access plus 2 months"
    ExpiresByType image/svg+xml "access plus 2 months"
    ExpiresByType image/webp "access plus 2 months"
    # Favicons keep a fixed URL (no ?v=), so a shorter lifetime. Apache names .ico
    # image/vnd.microsoft.icon (current mime.types) or image/x-icon (older).
    ExpiresByType image/vnd.microsoft.icon "access plus 1 week"
    ExpiresByType image/x-icon "access plus 1 week"

    # Documents
    ExpiresByType application/pdf "access plus 2 months"

    # Frontend assets (styles, scripts) — cache-busted with ?v={{ theme.assets_version }}.
    # Apache serves .js as text/javascript (newer mime.types) or application/javascript (older).
    ExpiresByType text/css "access plus 2 months"
    ExpiresByType text/javascript "access plus 2 months"
    ExpiresByType application/javascript "access plus 2 months"

    # Fonts
    ExpiresByType font/woff2 "access plus 1 year"
    ExpiresByType font/woff "access plus 1 year"
</IfModule>

Step 7: Full Reference Template for public/.htaccess

The complete, production-verified public/.htaccess file is available at examples/public.htaccess. Tested with Apache 2.4 + PHP-FPM, with the document root on the project root (root .htaccess) and on public/.

Key structural sections:

  1. AddDefaultCharset UTF-8
  2. <FilesMatch …> safety-net deny list and .env* block (Step 3)
  3. <IfModule mod_headers.c> security headers (Step 4)
  4. <IfModule mod_expires.c> asset caching headers (Step 6)
  5. <IfModule mod_rewrite.c>:
    • /index.php/… and /domains/<domain>/… in the requested URL redirected to the clean path (Pitfall 10)
    • node_modules/ and .git/ denied, allowlist for theme/, files/, thumbs/ (Step 2)
    • Base URI detection, Authorization header propagation
    • Symfony's redirection of direct /index.php queries (does not fire on hosts that forward internally — the rules above cover it)
    • Fallback rewrite of all missing files (RewriteCond %{REQUEST_FILENAME} !-f) to %{ENV:BASE}/index.php [END]

Verification & Testing

1. Automated Verification Script

Run the built-in verification script to test both /.htaccess and public/.htaccess:

BOLT_BASE_URL=https://staging.example.cz skills/bolt-htaccess/scripts/verify.sh

The script performs:

  • Root .htaccess Check: Confirms RewriteEngine on, HTTPS redirect rules, the canonical-host redirect (www), and rewrite to ./public.
  • Public .htaccess Check: Confirms AddDefaultCharset UTF-8, the front controller rules and the %{THE_REQUEST} redirects of /index.php/… (Pitfall 10).
  • Allowlist Check: Tests sample paths against the theme and upload allowlists — built assets and accepted uploads pass, templates, configs, sources, the theme root and .html / .php uploads are denied.
  • Safety-net Check: Tests the FilesMatch deny list against sensitive file names, confirms no public asset type is blocked, and that node_modules, .git and .env* are denied.
  • Security Headers Check: HSTS, X-Powered-By removal, nosniff for static files, sandboxed uploads.
  • Live HTTP Check (if BOLT_BASE_URL answers): theme sources and a fake upload path answer 403 / 404, a built asset answers 200, the headers of a static file, /index.php/… redirects to the clean path (Pitfall 10). That last request is sent only when the project's public/.htaccess has the Pitfall 10 rules: on a site without them it would itself poison Bolt's cached links for the cache lifetime. Upload the file before checking the site — if the server's copy lacks the rules, the check fails and its one request has that effect. Run it against Apache — PHP's built-in server and symfony serve ignore .htaccess.

2. Manual HTTP Testing

If the site is running on staging (Apache):

# Theme sources: 403
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/theme/mytheme/theme.yaml
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/theme/mytheme/package.json
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/theme/mytheme/js/src/index.ts
# Built assets: 200
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/theme/mytheme/css/index.css
# Uploads of a forbidden type: 403, whether the file exists or not
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/files/anything.html
# Headers of an upload: Content-Security-Policy … sandbox, X-Content-Type-Options: nosniff
curl -sI https://example.com/files/<an uploaded image> | grep -iE "content-security|nosniff|strict-transport"
# Plain HTTP: 301 to https:// — on both hosts; www: 301 straight to https://example.com/
curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" http://example.com/
curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" http://www.example.com/
curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" https://www.example.com/
# Secrets and the project root: 403 / 404
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/.env
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/var/data/bolt.sqlite

Common Pitfalls & Solutions

Pitfall 1: Over-broad Regex Blocking Compiled Assets

  • Mistake: Writing (\.(js|json|css)) in FilesMatch.
  • Consequence: Breaks the entire frontend because browsers cannot load compiled .js bundles or .css stylesheets.
  • Fix: Target only source files and specific configuration filenames: \.config\.[cm]?js, ^(package|package-lock|tsconfig)\.json, \.ts. Never block generic .js or .css extensions.

Pitfall 2: Infinite Redirect Loop on Front Controller

  • Symptom: Apache logs Request exceeded the limit of 10 internal redirects.
  • Cause: In older Apache versions or without [END] flags, RewriteRule ^index\.php redirects repeatedly.
  • Fix: Keep RewriteCond %{ENV:REDIRECT_STATUS} ="" before the index.php redirect rule and use the [END] flag on Apache 2.4+.

Pitfall 3: Direct SSL vs Proxy SSL

  • Symptom A: On a host without a TLS proxy, http:// URLs are never redirected to https://.
    • Cause: RewriteCond %{HTTP:X-Forwarded-Proto} ^http$ combined (AND) with RewriteCond %{HTTPS} off — without a proxy the header is absent, so the first condition never matches.
  • Symptom B: Behind a TLS-terminating proxy (Cloudflare, load balancer), every request redirects to itself (ERR_TOO_MANY_REDIRECTS).
    • Cause: RewriteCond %{HTTP:X-Forwarded-Proto} ^http$ [OR] + RewriteCond %{HTTPS} off — behind the proxy Apache always sees HTTPS off, so the [OR] matches even for HTTPS visitors.
  • Fix: Redirect only when neither Apache nor the proxy saw HTTPS:
    RewriteCond %{HTTPS} off
    RewriteCond %{HTTP:X-Forwarded-Proto} !https
    RewriteRule (.*) https://%{HTTP_HOST}/$1 [L,R=301]

Pitfall 4: node_modules/ Inside the Public Theme

  • Symptom: https://example.com/theme/<theme>/node_modules/photoswipe/package.json is blocked, but every .js file of every dependency downloads.
  • Cause: FilesMatch matches file names, not folders; the theme's npm install writes node_modules/ into public/.
  • Fix: The RewriteRule (^|/)(node_modules|\.git)(/|$) - [F,L] rule and the theme allowlist, and do not deploy node_modules/ to production (build locally, upload the built css/index.css and js/app.js).

Pitfall 5: A Theme Image or Font Suddenly Answers 403

  • Cause: It lives outside css/, js/, img/, images/, fonts/ (e.g. theme/<theme>/favicon.ico) or has a type the allowlist does not list.
  • Fix: Move the file into an allowlisted folder, or extend the folder / type list (Step 5). Never allow the whole theme.

Pitfall 6: Header Conditions on REQUEST_URI Never Match

  • Cause: After the root .htaccess forwards a request into public/, Apache processes it as /public/files/…; after the front-controller rewrite, as /public/index.php.
  • Fix: Test the file on disk — %{REQUEST_FILENAME} =~ m#/public/(files|thumbs)/# — as the template does.

Pitfall 7: Headers Sent Twice

  • Cause: Header setifempty does not see headers set by PHP-FPM, so nosniff and Referrer-Policy were added to pages that already had them from nelmio.
  • Fix: Limit those headers to non-PHP files (<If "%{REQUEST_FILENAME} !~ m#\.php$#">), as the template does.

Pitfall 8: "Pages Are Sent Uncompressed" on a Local Apache

  • Cause: Neither Bolt nor Symfony compresses responses in any APP_ENV, and a local Apache (serve-apache.sh, MAMP, Homebrew) has no compression configured. The hosts these sites run on compress at server level: Apache / ATS on 185.8.237.11 and the openresty proxy each answered gzip for every page, CSS and JS file (2026-10-22), without any rule in the sites' .htaccess.
  • Fix: None in .htaccess. The template deliberately has no mod_deflate block. Check the production host instead, after the first deployment: curl -s -H 'Accept-Encoding: gzip, br' -D - -o /dev/null https://example.cz/ | grep -i content-encoding. Only a host that answers without Content-Encoding needs compression, and that belongs in its server configuration.

Pitfall 9: Redirects to /domains/<domain>/…

  • Symptom: https://www.example.cz/ answers 301 → https://example.cz/domains/example.cz/ (404), and http://example.cz/page → https://example.cz/domains/example.cz/page. Requests that need no redirect work, so the bug shows only on www or plain-HTTP links. Browsers cache the broken 301, so after the fix test in a private window. Seen on WEDOS, which serves every domain from www/domains/<host>/ (see Pitfall 10).
  • Cause: The redirect target used %{REQUEST_URI}. WEDOS (and other shared hosts) serve an additional domain from www/domains/<domain>/, and the host's www/.htaccess forwards the request there with an internal rewrite. From then on REQUEST_URI is /domains/<domain>/page, not /page.
  • Fix: Build every redirect target from the matched path: RewriteRule (.*) https://%1/$1 [L,R=301] and RewriteRule (.*) https://%{HTTP_HOST}/$1 [L,R=301], as the template does. In a .htaccess, $1 is relative to that file's folder on every layout, and Apache appends the query string. verify.sh section 1 fails on %{REQUEST_URI} in a redirect target. Set BOLT_BASE_URL to the production https:// address to also check the live www redirect.

Pitfall 10: Canonical Links, Sitemap and llms.txt Point at /domains/<domain>/public/index.php/…

  • Symptom: after someone requests https://example.cz/index.php/page (a bot, an old link, a security scanner), the canonical link of /page reads https://example.cz/domains/example.cz/public/index.php/page, and /sitemap.xml and /llms.txt list every URL with that prefix. It fixes itself after a minute and comes back with the next such request. /index.php/<anything> itself answers 200 with the homepage. Seen on WEDOS; a CDN in front keeps the broken llms.txt for its cache lifetime.
  • Cause: Symfony's Request::getBaseUrl() treats the script path (SCRIPT_NAME, here /domains/example.cz/public/index.php) as the base URL whenever the requested path contains index.php, and the folder prefix when the site is requested under /domains/example.cz/public/ directly. Bolt caches canonical paths (caching.canonical in config/bolt/config.yaml), so the next visitors get the poisoned value. Symfony's own /index.php redirect in the template does not fire on such hosts: it requires an empty REDIRECT_STATUS, and the host's forwarding plus the root .htaccess are internal rewrites that set it.
  • Fix: the three %{THE_REQUEST} rules at the top of the rewrite block (Step 2, examples/public.htaccess): /…/index.php/page → 301 /…/page, any other path containing index.php → 404, /domains/<requested host>[/public]/page → 301 /page. THE_REQUEST is the request line as the visitor sent it, so internal rewrites never trigger them and the front controller keeps working. They belong in public/.htaccess, not the root file: a request for /domains/<domain>/public/… reaches public/ without passing the project's root .htaccess. verify.sh section 2 fails without them, section 6 requests /index.php/bolt-htaccess-probe?x=1 and expects a 301 to /bolt-htaccess-probe?x=1 — only when the project's file has the rules, because on an unprotected site that request is itself the trigger (Bolt keeps the poisoned links for caching: canonical in config/bolt/config.yaml, 60 s in the bolt/project skeleton). After deploying, purge the CDN copy of /llms.txt (or wait for its max-age).

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 083eb14. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated last month

README badge

README badge for vondry/bolt-skills/bolt-htaccess