Apache .htaccess to NGINX Translation Prompt
Translate an Apache vhost or .htaccess (RewriteRules, auth, headers, directory rules) into a correct NGINX server block — preserving behavior and flagging the rules that have no clean NGINX equivalent.
- Target user
- Engineers migrating a site from Apache to NGINX
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior engineer who has migrated dozens of sites from Apache to NGINX. You know NGINX has no per-directory `.htaccess` — everything lives in the server config — and you translate `mod_rewrite` to `rewrite`/`try_files` while preserving exact behavior.
I will provide:
- The Apache config or `.htaccess` to translate: [PASTE APACHE CONFIG]
- What the app is (WordPress, PHP app, static, framework with a front controller): [DESCRIBE APP]
- How PHP/the backend runs (php-fpm socket/port, proxied app): [DESCRIBE BACKEND]
Translate it:
1. **Map directive by directive.** For each Apache rule produce the NGINX equivalent, or state "no direct equivalent" and the closest pattern. Cover at minimum:
- `RewriteRule`/`RewriteCond` → `rewrite`, `return`, or (preferably) `try_files` for front-controller patterns.
- `DirectoryIndex` → `index`.
- `<Files>`/`<Directory>` access → `location` blocks (NGINX has no per-dir config).
- `Header set` → `add_header` (note the `always` flag and inheritance rules).
- `AuthType Basic` / `.htpasswd` → `auth_basic` + `auth_basic_user_file`.
- `Deny`/`Require ip` → `allow`/`deny`.
- `mod_deflate` → `gzip`.
2. **Prefer `try_files` over rewrite** for clean-URL front controllers (e.g. `try_files $uri $uri/ /index.php?$query_string`), explaining why it's simpler and faster than translated RewriteConds.
3. **PHP handling** — the `location ~ \.php$` block with `fastcgi_pass`, `fastcgi_param SCRIPT_FILENAME`, and a security note on blocking PHP execution in upload dirs.
4. **Behavioral gotchas** — `.htaccess` is per-request and per-directory; flag any rule whose semantics shift when hoisted into the server block, and any redirect that changes from internal to external.
Output: (a) a side-by-side translation table (Apache rule → NGINX directive → note), (b) the assembled `server {}` block, (c) a test plan: the URLs/redirects to curl and compare against the old Apache behavior, behind `nginx -t`. Don't hot-edit prod; validate and reload.
Why this prompt works
The deepest Apache-to-NGINX trap is architectural, not syntactic: .htaccess is per-directory and evaluated per request, while NGINX has one central config. A blind rule-by-rule port can hoist a directory-scoped Deny into a server-wide one, or turn an internal rewrite into an external redirect. The prompt makes the model flag exactly these semantic shifts instead of producing a syntactically valid but behaviorally wrong config.
It also steers away from the lazy translation: most mod_rewrite front-controller logic becomes a single clean try_files line in NGINX, which is faster and far more readable than a literal port of stacked RewriteConds. Demanding that preference produces idiomatic NGINX, not transliterated Apache.
The side-by-side table plus a curl-based comparison against the old Apache behavior keeps a human in the loop. You verify each redirect and protected path matches the original before cutover, behind nginx -t, so the migration doesn’t quietly change who can reach what.