nibula 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -5,21 +5,35 @@ All notable changes to Nibula are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.4.1] - 2026-08-03
+## [1.5.0] - 2026-08-04
 
 ### Added
-- `nginx.conf` header now documents the full setup: package install,
-  certificate issuance with `certbot --cert-name`, auto-renew, and the
-  `sites-available` → `sites-enabled` steps.
-- Troubleshooting table covering the errors whose message points elsewhere
-  than the actual cause: `nginx -t` without sudo, wrong certificate name,
-  certificate not covering the domain, nginx < 1.25, missing `404.html`,
-  DNS not pointing to the server.
+- `nginx.conf` now covers **both backends** with no manual edits. `/api` is
+  proxied to Node on `127.0.0.1:3000`; if Node is unreachable, the request is
+  retried through the PHP front controller via the internal `@php_backend`
+  location. The same file works for a Node deployment and a PHP one.
+- `nginx.conf` header now documents the PHP-FPM requirement, the version-agnostic
+  socket, and the errors specific to a PHP deployment.
 
 ### Changed
-- Certificates are now issued with `--cert-name SITE_NAME`, so the directory
-  under `/etc/letsencrypt/live/` matches the site name and `YOUR_CERTIFICATE`
-  is easier to fill in.
+- PHP is invoked through `SCRIPT_FILENAME` instead of by URL, so `.php` requests
+  keep returning 404 even on a PHP deployment and no source file is ever
+  reachable by name.
+- `fastcgi_pass` targets the version-agnostic socket `unix:/run/php/php-fpm.sock`
+  instead of a versioned path, so the config survives PHP upgrades.
+- `web.config` is now blocked anywhere in the tree, not only at the document root.
+- `docs/Backend.md` is limited to writing endpoints: routing, `public` vs
+  `protected`, the `Response` helper and configuration. Examples are Node-only,
+  with a note that PHP behaves identically. Hosting and server requirements
+  moved to `docs/Deploy.md`.
+- `docs/Deploy.md` rewritten around where a site can be published and what each
+  target requires, including why shared hosting cannot run the Node backend.
+
+### Removed
+- `docs/Nginx.md` — the setup steps live in the `nginx.conf` header, where they
+  are read at the moment they are needed.
+- `src/backend/backend-node.service.example` — the systemd unit is documented
+  in `docs/Deploy.md` instead of shipped as a file.
 
 ## [1.4.0] - 2026-08-03
 

package/docs/Backend.md

@@ -1,46 +1,24 @@
 # Backend
 
-Nibula ships **two interchangeable backends** in `src/backend/` — a **PHP** one
-and a **Node.js** one. You pick which to use when you scaffold a project
-(`nib new`). Both provide the same REST API: same routing, same `Response`
-envelope, same `X-Api-Key` auth, same CORS model, same file-based rate limiter.
-Only the language differs.
-
-> **Server requirement** — where each backend can run:
->
-> | Host | PHP | Node.js |
-> |---|---|---|
-> | Apache (shared hosting, VPS) | ✅ | ⚠️ needs a persistent process (VPS only) |
-> | Nginx (VPS) | ⚠️ works, but the shipped `nginx.conf` targets Node — needs a manual `fastcgi_pass` block | ✅ (Nginx reverse-proxies to Node) |
-> | IIS (Windows Server) | ✅ FastCGI | ✅ via ARR reverse proxy |
-> | Static hosting (Netlify, Vercel, GitHub Pages, Cloudflare Pages) | ❌ | ❌ |
->
-> Typical shared hosting can run **PHP** but not a long-running Node process, so
-> choose PHP there. On a VPS you control, either works.
-
-The backend lives in `src/backend/` and is copied to the output directory
-automatically at build time.
-
-## Choosing a backend
-
-When you run `nib new`, the scaffolder asks three questions: language, CSS
-framework, and **backend**. Pick Node.js or PHP.
-
-- **If you pick Node**, Composer is never run — you get an npm-only setup, and
-  the backend's dependency (`mysql2`, used only if you touch the database) is
-  added to the **root** `package.json` and installed into the root `node_modules`.
-- **If you pick PHP**, Composer dependencies are installed as before, and no Node
-  backend files are added.
-
-**Only the backend you choose is copied into the project.** A Node project
-contains no PHP files; a PHP project contains no `.js` backend files. Shared,
+Nibula ships **two interchangeable backends** — PHP and Node.js. You pick one
+when you scaffold a project with `nib new`, and **only that one is copied into
+your project**: a Node project contains no PHP files and vice versa. Shared,
 backend-agnostic files (SQL migrations, `.htaccess`, `web.config`) are always
 included.
 
+Both provide the same REST API: same routing, same `Response` envelope, same
+`X-Api-Key` auth, same CORS model, same rate limiter. Only the syntax differs.
+
+> **The examples below are in JavaScript (the Node backend).** If you chose PHP,
+> everything works exactly the same way — same routing, same variables, same
+> `Response` helper, same behaviour. Only the syntax differs.
+
+For **where each backend can run** and how to deploy it, see `docs/Deploy.md`.
+
 ## Structure
 
-The structure below shows both backends for reference; **your project will have
-only one side of each pair** (plus the shared files).
+The tree below shows both backends for reference; your project will have only
+one side of each pair.
 
 ```
 src/backend/
@@ -48,152 +26,56 @@ src/backend/
 │   ├── public/       # Endpoints accessible without an API key
 │   └── protected/    # Endpoints requiring the X-Api-Key header
 ├── _core/            # Framework internals (routing, modules) — do not edit
-│   ├── index.php     # PHP front controller            (PHP project)
-│   ├── index.js      # Node front controller + server   (Node project)
+│   ├── index.php     # PHP front controller           (PHP project)
+│   ├── index.js      # Node front controller + server (Node project)
 │   ├── init.php / init.js
 │   └── modules/      # Response, RateLimiter
 ├── database/
-│   ├── Database.php  # PDO singleton                    (PHP project)
-│   ├── Database.js   # mysql2 pool singleton            (Node project)
+│   ├── Database.php  # PDO singleton                  (PHP project)
+│   ├── Database.js   # mysql2 pool singleton          (Node project)
 │   └── migrations/   # shared
-├── package.json          # Node project only — backend deps + start script
-├── example.config.php    # PHP project only  — versioned template
-├── example.config.js     # Node project only — versioned template
-├── config.php            # PHP project only  — generated on setup, never commit
-└── config.js             # Node project only — generated on setup, never commit
-```
-
-> `config.php` / `config.js` are generated automatically by `nib new` (a copy of
-> the matching `example.config.*`) and are git-ignored, so your secrets stay
-> local. The `example.config.*` file is versioned as a secret-free reference. If
-> `config.*` is ever missing (e.g. after a fresh clone), copy the example to it.
-
-> **Where do the Node backend's dependencies live?** In the **root**
-> `node_modules`, not in `src/backend` — so your source tree stays clean (no
-> `src/backend/node_modules` locally). On the server you install them into
-> `out/backend` instead; see `docs/Deploy.md`.
-
-## Key difference: how each backend runs
-
-- **PHP** is executed **per request** by the web server through PHP-FPM (or
-  FastCGI/mod_php). There is no process to keep alive.
-- **Node** is a **long-running process** that *is* the server, listening on
-  `127.0.0.1:3000`. The web server (Nginx/Apache/IIS) **reverse-proxies** `/api`
-  to it. You start it once and keep it alive (systemd/pm2). See `docs/Deploy.md`.
-
-## Configuration
-
-`config.php` / `config.js` work like a `.env` file — they hold secrets and
-environment settings that stay local and out of version control. Same keys in
-both, just PHP-array vs JS-object syntax.
-
-### config.php <small>(`src/backend/`)</small>
-```php
-// Default key for protected endpoints without a specific key in CUSTOM_ENDPOINT_KEYS
-'GENERAL_API_KEY' => 'DEFAULT_KEY',
-
-// Per-endpoint keys. For subfolder endpoints use the relative path ('subfolder/endpoint')
-'CUSTOM_ENDPOINT_KEYS' => [
-    'subfolder/endpoint'    => 'custom-key',
-],
-
-'GENERAL_ALLOWED_ORIGINS' => [
-    '*',
-    // 'https://example.com',
-],
-
-'CUSTOM_ENDPOINT_ORIGINS' => [
-    'subfolder/endpoint'    => ['https://app.example.com'],
-],
-
-// Database configuration
-'DB_HOST' => '127.0.0.1',
-'DB_NAME' => 'example_db',
-'DB_USER' => 'root',
-'DB_PASS' => '',
-```
-
-### config.js <small>(`src/backend/`)</small>
-```js
-module.exports = {
-    GENERAL_API_KEY: 'DEFAULT_KEY',
-    CUSTOM_ENDPOINT_KEYS: {
-        'subfolder/endpoint': 'custom-key',
-    },
-    GENERAL_ALLOWED_ORIGINS: ['*' /*, 'https://example.com' */],
-    CUSTOM_ENDPOINT_ORIGINS: {
-        'subfolder/endpoint': ['https://app.example.com'],
-    },
-    DB_HOST: '127.0.0.1',
-    DB_NAME: 'example_db',
-    DB_USER: 'root',
-    DB_PASS: '',
-    APP_ENV: 'production', // anything other than 'production' = verbose errors
-};
+├── example.config.php / example.config.js   # versioned template
+└── config.php / config.js                   # generated on setup, never commit
 ```
 
-### API keys
-
-`GENERAL_API_KEY` is the fallback key for all protected endpoints. Use
-`CUSTOM_ENDPOINT_KEYS` to assign a different key to a specific endpoint — for
-subfolder endpoints, use the relative path as the key.
-
-> ⚠️ The API key travels in the `X-Api-Key` header on every request. Use it only
-> for server-to-server calls over HTTPS. Never embed it in frontend code, where
-> it would be publicly visible.
-
-### CORS (allowed origins)
-
-Cross-origin access mirrors the API-key model:
-
-- `GENERAL_ALLOWED_ORIGINS` — the default list of origins allowed to call any
-  endpoint from a browser.
-- `CUSTOM_ENDPOINT_ORIGINS` — overrides the default for a specific endpoint,
-  keyed by the same relative path used in `CUSTOM_ENDPOINT_KEYS`.
-
-Origins must be exact (scheme + host, no trailing slash), e.g.
-`https://example.com`. When a request's `Origin` is in the resolved list, it is
-reflected back in `Access-Control-Allow-Origin` (with `Vary: Origin`). An empty
-list sends no CORS header — the most restrictive setting; same-origin requests
-still work. Use `'*'` as the only element to allow any origin (not recommended
-for protected endpoints).
-
-Resolution order for a given endpoint: `CUSTOM_ENDPOINT_ORIGINS[path]` if
-present, otherwise `GENERAL_ALLOWED_ORIGINS`.
+> `config.php` / `config.js` are created automatically by `nib new` as a copy of
+> the matching `example.config.*`, and are git-ignored so your secrets stay
+> local. If `config.*` is missing (e.g. after a fresh clone), copy the example.
 
 ## How routing works
 
-The file path inside `api/` maps directly to the URL. The `public`/`protected`
+The file path inside `api/` maps directly to the URL. The `public` / `protected`
 folder does **not** appear in the URL — it only decides whether the `X-Api-Key`
-check applies. So `api/public/example-public` and `api/protected/example-protected`
-are both reached at `/api/<endpoint>`:
+check applies:
 
 - `api/public/example-public` → `/api/example-public` (no key)
 - `api/protected/example-protected` → `/api/example-protected` (requires key)
 
-Subfolders **do** appear: `api/public/users/list` → `/api/users/list`. Extra URL
-segments become route parameters. Every endpoint has access to:
+Subfolders **do** appear: `api/public/users/list` → `/api/users/list`.
 
-| Variable / field | Description |
+Extra URL segments become route parameters, resolved from the deepest match
+backwards: `/api/posts/42` looks for `posts/42` first, then falls back to
+`posts` with `42` as a parameter.
+
+Every endpoint receives:
+
+| Field | Description |
 |---|---|
 | `method` | HTTP method (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) |
 | `requestParams` | Extra URL segments (e.g. `/api/posts/42` → `['42']`) |
 
-> If two files share the same path — one in `public/`, one in `protected/` — the
-> public one wins (it is checked first), so the endpoint ends up **without**
-> authentication. Don't duplicate names across the two folders.
+The Node handler also gets `query`, `body` (parsed JSON), `rawBody`, `headers`,
+`config`, `req`, `res`.
 
-> **About the examples below** — the code samples use **JavaScript (the Node
-> backend)** as the reference. That's just the example language: if you chose the
-> **PHP** backend it works exactly the same way, with the same variables, the
-> same `Response` helper and the same behaviour — only the syntax differs. Each
-> section shows the JS version first, with the equivalent PHP right after.
+> ⚠️ If two files share the same path — one in `public/`, one in `protected/` —
+> the public one wins, so the endpoint ends up **without** authentication. Don't
+> duplicate names across the two folders.
 
-## Creating a public endpoint
+## Creating an endpoint
 
-Create a file anywhere inside `api/public/`.
+Create a file anywhere inside `api/public/` or `api/protected/`. For protected
+endpoints the API-key check runs automatically before your file does.
 
-### `api/public/example.js` (Node — reference)
 ```js
 module.exports = ({ method, requestParams, Response }) => {
     if (method !== 'GET') Response.error('Method not allowed', 405);
@@ -202,95 +84,86 @@ module.exports = ({ method, requestParams, Response }) => {
 };
 ```
 
-The Node handler receives a context object: `method`, `requestParams`,
-`Response` (`.success` / `.error` / `.noContent`), plus `query`, `body` (parsed
-JSON), `rawBody`, `headers`, `config`, `req`, `res`.
-
-The same endpoint in PHP — identical logic, PHP syntax:
-```php
-<?php
-declare(strict_types=1);
+## The Response helper
 
-require_once CORE_PATH . '/modules/Response.php';
+Same envelope in both backends.
 
-if ($method !== 'GET') {
-    Response::error('Method not allowed', 405);
-}
+```js
+Response.success(data, code);            // default 200
+Response.error(message, code, details);  // default 400
+Response.noContent();                    // 204
+```
 
-$id = isset($requestParams[0]) ? (int)$requestParams[0] : null;
+Shapes:
 
-Response::success(['id' => $id]);
-```
+- success → `{ "status": "success", "data": ... }`
+- error → `{ "status": "error", "message": "...", "code": ... }` (+ optional `details`)
 
-## Creating a protected endpoint
+## Configuration
 
-Create a file inside `api/protected/`. The API-key check happens automatically
-before your file runs.
+`config.php` / `config.js` work like a `.env` file: they hold secrets and
+environment settings that stay local and out of version control. Same keys in
+both, PHP-array vs JS-object syntax.
 
-### `api/protected/example.js` (Node — reference)
 ```js
-module.exports = ({ method, Response }) => {
-    if (method !== 'GET') Response.error('Method not allowed', 405);
-    Response.success({ visits: 1024 });
+module.exports = {
+    GENERAL_API_KEY: 'DEFAULT_KEY',
+    CUSTOM_ENDPOINT_KEYS: {
+        'subfolder/endpoint': 'custom-key',
+    },
+    GENERAL_ALLOWED_ORIGINS: ['*' /*, 'https://example.com' */],
+    CUSTOM_ENDPOINT_ORIGINS: {
+        'subfolder/endpoint': ['https://app.example.com'],
+    },
+    DB_HOST: '127.0.0.1',
+    DB_NAME: 'example_db',
+    DB_USER: 'root',
+    DB_PASS: '',
+    APP_ENV: 'production', // anything else = verbose errors
 };
 ```
 
-The same endpoint in PHP:
-```php
-<?php
-declare(strict_types=1);
+### API keys
 
-require_once CORE_PATH . '/modules/Response.php';
+`GENERAL_API_KEY` is the fallback for all protected endpoints.
+`CUSTOM_ENDPOINT_KEYS` assigns a different key to a specific endpoint, keyed by
+its relative path (`'subfolder/endpoint'`).
 
-if ($method !== 'GET') {
-    Response::error('Method not allowed', 405);
-}
+> ⚠️ The key travels in the `X-Api-Key` header on every request. Use it only for
+> server-to-server calls over HTTPS. Never embed it in frontend code, where it
+> would be publicly visible.
 
-Response::success(['visits' => 1024]);
-```
+### CORS
 
-To assign a dedicated key, add it to your config:
+Mirrors the API-key model: `GENERAL_ALLOWED_ORIGINS` is the default list,
+`CUSTOM_ENDPOINT_ORIGINS` overrides it per endpoint using the same relative path.
 
-```js
-CUSTOM_ENDPOINT_KEYS: { 'endpoint': 'custom-key' }          // config.js
-```
-```php
-'CUSTOM_ENDPOINT_KEYS' => [ 'endpoint' => 'custom-key' ],   // config.php
-```
+Origins must be exact (scheme + host, no trailing slash). A matching `Origin` is
+reflected in `Access-Control-Allow-Origin` with `Vary: Origin`. An empty list
+sends no CORS header — the most restrictive setting; same-origin requests still
+work. `'*'` as the only element allows any origin (not recommended for protected
+endpoints).
 
-## The Response helper
+Resolution order: `CUSTOM_ENDPOINT_ORIGINS[path]` if present, otherwise
+`GENERAL_ALLOWED_ORIGINS`.
+
+## Database
 
-Identical envelope in both backends — JS shown as reference, PHP works the same:
+Both backends expose a connection singleton reading the same config —
+`database/Database.js` (a `mysql2` pool) or `database/Database.php` (a PDO
+singleton).
 
 ```js
-Response.success(data, code);            // default 200
-Response.error(message, code, details);  // default 400
-Response.noContent();                    // 204
+const pool = Database.getInstance();
+const [rows] = await pool.execute(sql, params);
 ```
-```php
-Response::success($data, $code);            // default 200
-Response::error($message, $code, $details); // default 400
-Response::noContent();                       // 204
-```
-
-Response shapes:
-- success → `{ "status": "success", "data": ... }`
-- error → `{ "status": "error", "message": "...", "code": ... }` (+ optional `details`)
-
-## Database
-
-Both backends expose a connection singleton reading the same config.
 
-- **Node** (reference) — `database/Database.js`, a `mysql2` pool singleton:
-  `const pool = Database.getInstance(); const [rows] = await pool.execute(sql, params);`
-  The `mysql2` driver is installed at scaffold time when you choose Node (it is
-  loaded lazily, so the backend also boots fine without a database).
-- **PHP** — `database/Database.php`, a PDO singleton:
-  `$pdo = Database::getInstance();`
+`mysql2` is installed at scaffold time and loaded lazily, so the backend boots
+fine without a database.
 
 ## Pre-built endpoints
 
 | Route | Method | Description |
 |---|---|---|
-| `/api/example-public` | `GET` | Example endpoint that doesn't require any key |
-| `/api/example-protected` | `GET` | Example endpoint that requires `X-Api-Key` |
+| `/api/example-public` | `GET` | Example endpoint requiring no key |
+| `/api/example-protected` | `GET` | Example endpoint requiring `X-Api-Key` |

package/docs/Deploy.md

@@ -1,135 +1,114 @@
 # Deploy
 
-Nibula builds a static site into `out`. To publish it you upload that folder to a
-web server. What you need depends on **where** you publish and **which backend**
-you chose at scaffold time (PHP or Node.js — see `docs/Backend.md`).
+Nibula builds a static site into `out`. Publishing means uploading that folder to
+a web server. What you need depends on **where** you publish and **which
+backend** you chose (see `docs/Backend.md`).
 
-## Prerequisites
+## The one constraint that decides everything
 
-**PHP backend:** a server with PHP support (Apache, Nginx + PHP-FPM, or IIS +
-FastCGI) and Composer for the backend dependencies. Works on typical shared
-hosting.
+The two backends run in fundamentally different ways:
 
-**Node backend:** Node.js 18+ and the ability to run a long-running process —
-i.e. a VPS you control, not typical shared hosting. No PHP or Composer required.
+- **PHP** is executed **per request** by the web server through PHP-FPM. There is
+  no process to keep alive — the server starts it, it answers, it exits.
+- **Node** **is** the server: a long-running process listening on
+  `127.0.0.1:3000`, which the web server reverse-proxies `/api` to. Something has
+  to start it and keep it alive across reboots and crashes.
 
----
+This is why **shared hosting cannot run the Node backend**. On Aruba, cPanel and
+similar, you upload files into a web root — you have no shell to start a daemon,
+no systemd, and any process you did manage to launch would be killed. If your
+host is shared hosting, choose PHP. It is not a limitation of Nibula.
 
-## Shared hosting (Apache)
+## Where you can publish
 
-The most common option, and the natural home for the **PHP** backend — shared
-hosting can't keep a Node process alive.
+| Target | Frontend | PHP backend | Node backend |
+|---|---|---|---|
+| Shared hosting (Apache — Aruba, cPanel) | ✅ | ✅ | ❌ no persistent process |
+| Windows hosting (IIS) | ✅ | ✅ FastCGI | ⚠️ needs ARR reverse proxy |
+| Your own VPS (Nginx on Ubuntu) | ✅ | ✅ | ✅ |
+| Static hosting (Netlify, Vercel, GitHub Pages) | ✅ | ❌ | ❌ |
 
-Upload the **contents of `out`** to the hosting's web root (often `htdocs`,
-`public_html`, or `www`). Done. `.htaccess` is already inside `out` and Apache
-reads it automatically: directory listing off, 403/404 → `/404.html`, sensitive
-files blocked, backend source sealed, `/api/*` routed.
+Static hosting serves files and nothing else — fine if your site has no `/api`
+endpoints, unusable otherwise.
 
-**Backend routing:** if `mod_proxy` is available, `/api` is reverse-proxied to
-Node on `127.0.0.1:3000`; if not, `/api` is rewritten to the PHP front
-controller. To force PHP on a proxy-enabled server, comment the `mod_proxy`
-block in `.htaccess`.
+## Requirements
 
-## Windows hosting (IIS)
+**PHP backend:** a server with PHP support and Composer for the backend
+dependencies.
 
-Same idea, different server. Upload the contents of `out`; `web.config` is
-already there and read automatically.
+**Node backend:** Node.js 18+ and shell access to run a persistent process — a
+VPS you control.
 
-**Backend routing:** the `ApiToNode` rewrite rule (requires the ARR + URL Rewrite
-modules) reverse-proxies `/api` to Node and wins if present. Remove it to fall
-back to `ApiToPhp`, which rewrites `/api` to the PHP front controller.
+---
 
-## Your own server (Nginx on a VPS)
+## Shared hosting (Apache)
 
-The setup for the **Node** backend. Unlike Apache and IIS, Nginx doesn't read
-per-directory config files — the whole site is defined in one file.
+Upload the **contents of `out`** to the web root (often `htdocs`, `public_html`
+or `www`). Done — `.htaccess` is already inside `out` and Apache reads it
+automatically: directory listing off, 403/404 → `/404.html`, sensitive files
+blocked, backend source sealed, `/api/*` routed.
 
-Nibula ships `nginx.conf` in the project root as a **ready-to-use site file**:
-replace three placeholders, symlink it, reload.
+**Backend routing:** if `mod_proxy` is available, `/api` is proxied to Node on
+`127.0.0.1:3000`; if not — the usual case on shared hosting — `/api` is
+rewritten to the PHP front controller. To force PHP on a proxy-enabled server,
+comment the `mod_proxy` block in `.htaccess`.
 
-```bash
-sudo cp nginx.conf /etc/nginx/sites-available/my-site
-sudo nano /etc/nginx/sites-available/my-site        # YOUR_DOMAIN, SITE_FOLDER, YOUR_CERTIFICATE
-sudo ln -s /etc/nginx/sites-available/my-site /etc/nginx/sites-enabled/
-sudo nginx -t && sudo systemctl reload nginx
-```
+## Windows hosting (IIS)
 
-Full reference, requirements and troubleshooting: **`docs/Nginx.md`**.
+Same idea: upload the contents of `out`, `web.config` is already there and read
+automatically.
 
-## Static hosting (Netlify, Vercel, GitHub Pages)
+**Backend routing:** the `ApiToNode` rule (requires the ARR + URL Rewrite
+modules) proxies `/api` to Node and wins if present. Remove it to fall through
+to `ApiToPhp`, which rewrites `/api` to the PHP front controller.
 
-Frontend only. Neither backend runs there — no PHP, no persistent process. Fine
-if your site has no `/api` endpoints.
+## Your own server (Nginx on a VPS)
+
+Nginx doesn't read per-directory config files — the whole site lives in one file.
+Nibula ships `nginx.conf` in the project root as a ready-to-use site file that
+**covers both backends without edits**: `/api` goes to Node, and if Node is
+unreachable the request falls through to PHP automatically.
 
 ---
 
 ## Starting the Node backend on the server
 
-Unlike PHP, the Node backend is **not** executed by the web server per request —
-it is a process you start and keep alive. After uploading your built `out` folder:
+After uploading `out`:
 
-1. Install the backend's runtime deps (only needed if an endpoint uses the DB):
-```bash
-   cd /var/www/your-site/out/backend
+1. Install the backend's runtime deps:
+   ```bash
+   cd /var/www/backend/SITE_FOLDER
    npm install
-```
-
-2. Make sure `config.js` exists in `out/backend/` (copy `example.config.js` to
-   `config.js` if missing) and fill in your values.
-
-3. Start it — quick test first:
-```bash
-   node _core/index.js
-   # -> [backend-node] listening on http://127.0.0.1:3000 (env: production)
-```
-   Then, from the server, confirm it answers:
-```bash
+   ```
+
+2. Make sure `config.js` exists in `out/backend/` (copy `example.config.js` if
+   missing) and fill in your values.
+
+3. Start it in a new screen:
+   ```bash
+   screen -S node-backend
+   # In the new screen terminal:
+   sudo node /var/www/SITE_FOLDER/backend/_core/index.js
    curl http://127.0.0.1:3000/api/example-public
-```
-
-   > Running `node _core/index.js` directly ties the process to your SSH session —
-   > close the terminal and the backend dies. To try it out without staying stuck
-   > there, use **`screen`** (a detachable terminal):
-   > ```bash
-   > screen -S backend            # open a named session
-   > node _core/index.js          # start the backend inside it
-   > # press Ctrl+A then D to detach — the backend keeps running
-   > # reattach later with:  screen -r backend
-   > ```
-   > `screen` is fine for testing. For production, prefer **systemd** (step 4).
-
-4. To keep it running after logout, use **systemd**. An example unit ships at
-   `backend/backend-node.service.example` — copy it to
+   ```
+4. Exit the screen without closing the process with `CTRL + A`, `D`. To resume the screen type `screen -r node-backend`.
+
+5. For production use **systemd**, which also restarts on crash and reboot. An
+   example unit ships at `backend/backend-node.service.example` — copy it to
    `/etc/systemd/system/backend-node.service`, adjust `WorkingDirectory` and the
    `node` path (`which node`), then:
-```bash
+   ```bash
    sudo systemctl daemon-reload
    sudo systemctl enable --now backend-node
    sudo systemctl status backend-node
-```
-   (`pm2` also works: `pm2 start _core/index.js --name backend-node`.)
-
-The web server then reverse-proxies `/api` to this process. If Node is down the
-proxy returns 502 — there is no automatic PHP fallback.
+   ```
+   (`pm2` works too: `pm2 start _core/index.js --name backend-node`.)
 
 ### Environment variables
 
 | Variable | Default | Purpose |
 |---|---|---|
 | `PORT` | `3000` | Port Node listens on (match your proxy target) |
-| `HOST` | `127.0.0.1` | Bind address (keep it local; the web server is the public face) |
+| `HOST` | `127.0.0.1` | Bind address — keep it local; the web server is the public face |
 | `APP_ENV` | `production` | `production` hides error details; anything else = verbose 500s |
-| `DOCUMENT_ROOT` | auto (`out/`) | Where `404.html` lives; auto-detected as the folder above `backend/` |
-
----
-
-## One config file, one backend
-
-Each server config targets a specific backend, decided at setup time rather than
-at runtime:
-
-- **Apache:** `mod_proxy` present → Node; absent → PHP
-- **IIS:** `ApiToNode` rule present (needs ARR) → Node; remove it for `ApiToPhp`
-- **Nginx:** ships configured for Node; see `docs/Nginx.md` for PHP
-
-Since a given deployment runs only one backend, this is a one-time setup.
+| `DOCUMENT_ROOT` | auto (`SITE_FOLDER/`) | Where `404.html` lives; detected as the folder above `backend/` |

package/nginx.conf

@@ -1,42 +1,49 @@
 # =============================================================================
 #  Nibula — default nginx site configuration
-#  Static site + optional HTTP backend on 127.0.0.1:3000. PHP not handled.
 # -----------------------------------------------------------------------------
-#  REPLACE
+# 1. REPLACE
 #
 #    YOUR_DOMAIN        server_name, twice (port 80 and 443)
 #    SITE_FOLDER        document root under /var/www/
+#    YOUR_CERTIFICATE   dir under /etc/letsencrypt/live/ 
+#    SITE_NAME          commands below file name
 #
-#    YOUR_CERTIFICATE   dir under /etc/letsencrypt/live/ — not always the sam
-#                       as YOUR_DOMAIN. Check: sudo certbot certificates
+# 2. INSTALL (skip if already present)
 #
-#    SITE_NAME          (commands below) name of this file and of the
-#                       certificate; any short name, never appears in URLs
-#
-#
-#  1. INSTALL (skip if already present)
 #     sudo apt update
 #     sudo apt install -y nginx certbot python3-certbot-nginx
-#     nginx -v                        # >= 1.25 for the http2 directive
 #
-#  2. CERTIFICATE (before enabling the site — nginx won't start without it)
-#     dig +short YOUR_DOMAIN A        # must return this server's public IP
+#     If you are using PHP as backend:
+#     sudo apt install -y php-fpm
+#
+# 3. CERTIFICATE
+#
 #     sudo certbot certonly --nginx --cert-name SITE_NAME -d YOUR_DOMAIN
 #     sudo systemctl enable --now certbot.timer      # auto-renew every 90 days
 #
-#  3. INSTALL THE SITE
-#     sudo cp nginx.conf /etc/nginx/sites-available/SITE_NAME
-#     sudo nano /etc/nginx/sites-available/SITE_NAME
-#     sudo ln -s /etc/nginx/sites-available/SITE_NAME /etc/nginx/sites-enabled/
-#     sudo nginx -t && sudo systemctl reload nginx
+# 4. INSTALL THE SITE
+#
+#    Move to nginx folders
+#    cd /etc/nginx/sites-available
+#
+#    Create and write a new file
+#    sudo nano SITE_NAME
+#    CTRL + O, ENTER, CTRL + X
 #
-#  IF IT FAILS
+#    Copy the config to sites-enabled
+#    sudo cp SITE_NAME ../sites-enabled/
+#
+#    Test and reload the nginx configuration
+#    sudo nginx -t && sudo systemctl reload nginx
+#
+# IF IT FAILS
 #    cannot load certificate ... Permission denied  → nginx -t needs sudo
 #    cannot load certificate ... No such file       → wrong certificate name
-#    no alternative certificate subject name        → cert doesn't cover domain
-#    unknown directive "http2"                      → nginx < 1.25
+#    no alternative certificate subject name        → certificate doesn't cover domain
+#    unknown directive "http2"                      → nginx < 1.25, check with nginx -v
 #    500 instead of the 404 page                    → 404.html missing
 #    NXDOMAIN / timeout during certbot              → DNS not pointing here
+#    502 on /api with PHP deployed                  → wrong php-fpm socket path
 # =============================================================================
 
 # HTTP (80) configuration
@@ -63,7 +70,7 @@ server {
     listen      443 ssl;
     listen      [::]:443 ssl;
 
-    # nginx >= 1.25; older: "listen 443 ssl http2;"
+    # nginx >= 1.25;
     http2       on;
 
     server_name YOUR_DOMAIN;
@@ -95,7 +102,7 @@ server {
         return 404;
     }
 
-    location ~* ^/(web\.config)$ {
+    location ~* (^|/)web\.config$ {
         return 404;
     }
 
@@ -103,14 +110,11 @@ server {
         return 404;
     }
 
-    # PHP not handled: without php-fpm these would leak source code.
-    # For PHP sites, replace this block with fastcgi_pass and change
-    # try_files below to: $uri $uri/ /index.php?$query_string
     location ~ \.php$ {
         return 404;
     }
 
-### API backend
+### API backend — Node primary, PHP fallback
     location ^~ /api/ {
         proxy_pass http://127.0.0.1:3000;
         proxy_http_version 1.1;
@@ -122,9 +126,19 @@ server {
         # proxy_read_timeout defaults to 60s; raise only for slow endpoints.
         proxy_connect_timeout 5s;
 
+        proxy_intercept_errors on;
+        error_page 502 504 = @php_backend;
+
         # WebSocket is not enabled; needs a $connection_upgrade map at http level.
     }
 
+    location @php_backend {
+        include fastcgi_params;
+
+        fastcgi_param SCRIPT_FILENAME $document_root/backend/_core/index.php;
+        fastcgi_pass unix:/run/php/php-fpm.sock;
+    }
+
 ### Static files
     location / {
         try_files $uri $uri/ $uri.html =404;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nibula",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "A beginner-friendly static site generator built on Eleventy that stays close to vanilla HTML, CSS and JS — with a page-management CLI, an optional PHP backend, and SEO files generated for you.",
   "keywords": [
     "static-site-generator",

package/docs/Nginx.md

@@ -1,133 +0,0 @@
-# Nginx
-
-`nginx.conf` in the project root is a **ready-to-use site file** for a Nibula
-site on your own server (a VPS). Replace three placeholders, symlink it, reload.
-
-It targets the **Node** backend; see *Using the PHP backend* below for PHP.
-
-## Setup
-
-| Placeholder | Value |
-|---|---|
-| `YOUR_DOMAIN` | your domain — appears twice (port 80 and 443) |
-| `SITE_FOLDER` | document root under `/var/www/` — your uploaded `out` folder |
-| `YOUR_CERTIFICATE` | dir name under `/etc/letsencrypt/live/` — **not always equal to the domain**: a cert may be issued for a different hostname (common with DDNS) or cover several domains. Check with `sudo certbot certificates` |
-
-```bash
-sudo cp nginx.conf /etc/nginx/sites-available/my-site
-sudo nano /etc/nginx/sites-available/my-site        # replace the placeholders
-sudo ln -s /etc/nginx/sites-available/my-site /etc/nginx/sites-enabled/
-sudo nginx -t && sudo systemctl reload nginx
-```
-
-Verify:
-
-```bash
-curl -I http://YOUR_DOMAIN/                # 301 to https
-curl -I https://YOUR_DOMAIN/               # 200
-curl -I https://YOUR_DOMAIN/nonexistent    # 404, not 200 or 500
-```
-
-On RHEL/Alpine there is no `sites-available`; put the file in
-`/etc/nginx/conf.d/` instead.
-
-## Requirements
-
-- A valid certificate covering `YOUR_DOMAIN`
-- `404.html` present in the document root and readable by nginx
-- Nginx ≥ 1.25 for `http2 on;` — on older versions use `listen 443 ssl http2;`
-
-## What it provides
-
-- HTTP → HTTPS redirect on port 80
-- TLS via Let's Encrypt, with the Certbot SSL options included
-- `server_tokens off` and `autoindex off`
-- 403 / 404 → `/404.html`, preserving the original status code
-- Backend source directory (`/backend/`) sealed with `return 404`
-- `web.config`, dotfiles and `.php` blocked
-- Security headers: `X-Content-Type-Options`, `X-Frame-Options`,
-  `Referrer-Policy`, `Strict-Transport-Security`
-- `/api/*` reverse-proxied to the Node backend on `127.0.0.1:3000`
-
-## Certificate renewal
-
-The `/.well-known/acme-challenge/` block is only needed with the **webroot**
-authenticator. If you obtained the certificate with `certbot --nginx`, remove it.
-Check with:
-
-```bash
-grep authenticator /etc/letsencrypt/renewal/YOUR_DOMAIN.conf
-```
-
-When adding a domain to an existing certificate, always pass `--cert-name` **and
-list every domain already covered** — omitted ones are dropped, and without the
-flag Certbot creates a separate certificate instead of expanding.
-
-## HSTS
-
-The file ships with `max-age=300` deliberately. Browsers cache the HSTS policy
-for the whole `max-age` **even after you remove the header**, so a long value
-combined with a broken certificate locks visitors out with no way back.
-
-Raise it to `31536000` once HTTPS is confirmed stable. Add `; includeSubDomains`
-only if every current and future subdomain is served over HTTPS with a valid
-certificate.
-
-## WebSocket
-
-Not enabled by default. If your backend uses socket.io or similar, add a map at
-`http` level (e.g. `/etc/nginx/conf.d/websocket.conf`):
-
-```nginx
-map $http_upgrade $connection_upgrade {
-    default upgrade;
-    ''      close;
-}
-```
-
-and inside `location ^~ /api/`:
-
-```nginx
-proxy_set_header Upgrade    $http_upgrade;
-proxy_set_header Connection $connection_upgrade;
-```
-
-For long-lived connections also raise `proxy_read_timeout`, ideally in a
-dedicated location for the socket path so normal API requests keep the 60s
-default.
-
-## Using the PHP backend
-
-This file targets Node. `.php` requests return 404 by design: without a
-`fastcgi_pass` block Nginx would serve them as plain text and leak source code,
-database credentials included.
-
-For a PHP deployment, replace the `.php` block with:
-
-```nginx
-location ~ \.php$ {
-    include snippets/fastcgi-php.conf;
-    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
-}
-```
-
-and change `try_files` in `location /` to `$uri $uri/ /index.php?$query_string`.
-
-Check the socket path with `ls /run/php/`:
-
-| Distro | Path |
-|---|---|
-| Debian / Ubuntu | `unix:/run/php/php8.3-fpm.sock` |
-| RHEL / Fedora | `unix:/run/php-fpm/php-fpm.sock` |
-| TCP fallback | `127.0.0.1:9000` |
-
-## Troubleshooting
-
-| Symptom | Cause |
-|---|---|
-| `cannot load certificate ... Permission denied` | `nginx -t` run without `sudo` — the certs are root-only |
-| `no alternative certificate subject name matches` | the cert doesn't cover `YOUR_DOMAIN`; check `sudo certbot certificates` |
-| 500 instead of the 404 page | `404.html` missing or unreadable by nginx |
-| `unknown directive "http2"` | Nginx < 1.25 — use `listen 443 ssl http2;` |
-| 502 on `/api/*` | the Node process isn't running; see `docs/Deploy.md` |
-| Site not responding at all | symlink missing in `sites-enabled/`, or nginx not reloaded |

package/src/backend/backend-node.service.example

@@ -1,30 +0,0 @@
-# Example systemd unit to keep the Node backend running on your server.
-#
-# 1. Copy your built site to the server (the `out` folder).
-# 2. Adjust WorkingDirectory below to point at out/backend on your server.
-# 3. Copy this file to /etc/systemd/system/backend-node.service (drop the .example).
-# 4. Enable and start it:
-#       sudo systemctl daemon-reload
-#       sudo systemctl enable --now backend-node
-#       sudo systemctl status backend-node
-#
-# Check the Node path with `which node` and update ExecStart if it isn't /usr/bin/node
-# (nvm installs live elsewhere, e.g. /home/<user>/.nvm/versions/node/<v>/bin/node).
-
-[Unit]
-Description=Nibula Node backend
-After=network.target
-
-[Service]
-Type=simple
-WorkingDirectory=/var/www/your-site/out/backend
-ExecStart=/usr/bin/node _core/index.js
-Environment=PORT=3000
-Environment=HOST=127.0.0.1
-Environment=APP_ENV=production
-Restart=on-failure
-RestartSec=2
-User=www-data
-
-[Install]
-WantedBy=multi-user.target