nibula 1.4.1 → 1.5.1

package/.eleventyignore

@@ -1,4 +1 @@
-src/frontend/assets/**
-src/frontend/js/**
-src/frontend/scss/**
-src/backend/**
+src/frontend/assets/**

package/CHANGELOG.md

@@ -5,21 +5,78 @@ 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.1] - 2026-08-05
+
+### Fixed
+- `nib new` no longer creates an empty `routes` folder. Page source folders are
+  created on demand when a page is added, and removed again when the last page
+  in them is deleted — `routes`, `scss/pages` and the JS/TS pages folder alike.
+- Removing a page that doesn't exist reported the skip and then went on to strip
+  its entry from `site.json` and `page-components.njk` anyway. It now stops.
+- `example.config.php` was missing the `APP_ENV` key, so PHP projects had no way
+  to discover the debug switch from the template. Behaviour was unaffected —
+  the code already fell back to `production` — but the key is now visible and
+  documented, and the two templates are identical again.
+- The backend's `dev` script set `APP_ENV` as an environment variable, which
+  neither backend reads. It ran in production mode and produced no debug output.
+  The script is gone; error verbosity is set in `config.js` / `config.php`.
+- `bin/create.js` repeated the `mysql2` version already declared in
+  `src/backend/package.json`. It now reads that file, so the two cannot drift.
+- `docs/Deploy.md` pointed at `backend/backend-node.service.example`, removed in
+  1.5.0. The systemd unit is written out in full instead.
+- `docs/Deploy.md` gave the backend path as `/var/www/backend/SITE_FOLDER`,
+  inverted with respect to the rest of the document.
+
+### Changed
+- Nginx setup steps moved from the `nginx.conf` header into `docs/Deploy.md`,
+  under "Your own server". The header keeps only the three placeholders that
+  appear in the file and a pointer to the docs, so a config copied into
+  `/etc/nginx/sites-available/` no longer carries 60 lines of install
+  instructions that were already followed.
+- `docs/Deploy.md` troubleshooting is now a table, with a row for a 502 on
+  `/api` caused by the Node process not running.
+- `.eleventyignore` reduced to `src/frontend/assets/**`. The `scss`, `js` and
+  `src/backend` entries excluded nothing: the first two are not Eleventy
+  template formats and the third is outside the input directory. The last one
+  was also misleading, since `.eleventy.js` deliberately copies `src/backend`
+  into the build.
+- `docs/Backend.md` documents `APP_ENV` in its own section, including the
+  `display_errors` behaviour specific to PHP, and states explicitly that it is
+  a config key rather than an environment variable.
+
+### Notes
+- Existing projects are unaffected: the scaffolding and template changes apply
+  only to newly created ones.
+
+## [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/README.md

@@ -76,19 +76,6 @@ cd your-project
 nib run
 ```
 
-## 💻 Commands
-
-Run these from anywhere inside a project — except `nib new`, which must be run **outside** a project, in the folder where you want the new one created.
-
-| Command | Description |
-|---|---|
-| `nib new <name>` | Create your new project |
-| `nib run` | Start the dev server and build the output folder at runtime |
-| `nib cli` | Open the page-management assistant |
-| `nib build` | Build the output folder |
-| `nib clean` | Remove the output directory |
-| `nib update` | Update Nibula to the latest version (applies from your next project on) |
-
 ## 📄 Managing pages
 
 Instead of creating and wiring up multiple files by hand, let the interactive assistant do it for you. To create, remove, or rename pages and configure the output path, run:
@@ -99,17 +86,18 @@ nib cli
 
 See [docs/Assistant CLI.md](docs/Assistant%20CLI.md) for details.
 
-## 🌍 Deploying
-
-Nibula builds a static site into your `out` folder, which you upload to a web
-server. Which backend you chose affects deployment:
+## 💻 Commands
 
-- **Node** runs as a long-running service on a VPS; the web server reverse-proxies `/api` to it.
-- **PHP** runs on ordinary shared hosting (Apache/IIS) or a VPS with PHP-FPM — no process to keep alive.
+Run these from anywhere inside a project — except `nib new`, which must be run **outside** a project, in the folder where you want the new one created.
 
-The shipped `.htaccess`, `web.config` and `nginx.conf` cover **both** backends.
-See [docs/Deploy.md](docs/Deploy.md) for the full guide, including how to start
-the Node service on your server.
+| Command | Description |
+|---|---|
+| `nib new <name>` | Create your new project |
+| `nib run` | Start the dev server and build the output folder at runtime |
+| `nib cli` | Open the page-management assistant |
+| `nib build` | Build the output folder |
+| `nib clean` | Remove the output directory |
+| `nib update` | Update Nibula to the latest version (applies from your next project on) |
 
 ## 🙌 Wrapping up
 
@@ -117,4 +105,4 @@ Thanks for giving Nibula a try.
 
 It's a one-person project, so every bit of feedback counts more than you'd think: if something breaks, if the documentation isn't clear, or if a feature is missing, open an [issue](https://github.com/Rhaastrake/Nibula/issues) — even just to tell me what you built with it.
 
-If Nibula was useful to you, leaving a ⭐ on the repository is the easiest way to help other people find it.
+If Nibula was useful to you, leaving a ⭐ on the repository is the easiest way to help other people find it.

package/bin/create.js

@@ -53,11 +53,11 @@ const BACKEND_CHOICES = [
     { label: 'PHP (Can run everywhere)',  value: BACKEND.PHP  },
 ];
 
-// Runtime dependency added to the ROOT package.json when the Node backend is
-// chosen, so it lands in the root node_modules (never in src/backend).
-const NODE_BACKEND_DEPENDENCIES = {
-    mysql2: '^3.11.0',
-};
+// Runtime dependencies for the Node backend, read from the backend's own
+// package.json so the two never drift. They are added to the ROOT package.json
+// when Node is chosen, so they land in the root node_modules (never in
+// src/backend).
+const NODE_BACKEND_DEPENDENCIES = require(path.join(templateDir, 'src/backend/package.json')).dependencies;
 
 // ── COPY CONFIG ───────────────────────────────────────────────────────────────
 

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
+├── example.config.php / example.config.js   # versioned template
+└── config.php / config.js                   # 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
-};
-```
-
-### 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`.
+
+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:
 
-| Variable / field | Description |
+| 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,119 @@ 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 = {
+    // Default key for protected endpoints that don't have a specific key in CUSTOM_ENDPOINT_KEYS
+    GENERAL_API_KEY: 'DEFAULT_KEY',
+
+    // If you want to restrict access to protected endpoints to specific clients, define custom keys per endpoint.
+    // For subfolder endpoints, use the relative path ('subfolder/endpoint')
+    CUSTOM_ENDPOINT_KEYS: {
+        'subfolder/example-protected': 'custom-key',
+    },
+
+    GENERAL_ALLOWED_ORIGINS: [
+        '*',
+        // 'https://example.com',
+    ],
+
+    CUSTOM_ENDPOINT_ORIGINS: {
+        'subfolder/example-protected': ['https://app.example.com'],
+    },
+
+    // Database configuration
+    DB_HOST: '127.0.0.1',
+    DB_NAME: 'example_db',
+    DB_USER: 'root',
+    DB_PASS: '',
+
+    // Environment: 'production' hides error details; anything else = debug.
+    APP_ENV: 'production',
 };
 ```
 
-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`.
 
-Identical envelope in both backends — JS shown as reference, PHP works the same:
+### Error verbosity
 
-```js
-Response.success(data, code);            // default 200
-Response.error(message, code, details);  // default 400
-Response.noContent();                    // 204
-```
-```php
-Response::success($data, $code);            // default 200
-Response::error($message, $code, $details); // default 400
-Response::noContent();                       // 204
-```
+`APP_ENV` decides what an unhandled exception tells the client.
 
-Response shapes:
-- success → `{ "status": "success", "data": ... }`
-- error → `{ "status": "error", "message": "...", "code": ... }` (+ optional `details`)
+| Value | Response to a 500 |
+|---|---|
+| `'production'` (default) | `{"status":"error","message":"Internal server error","code":500}` |
+| anything else | the real exception message, plus `stack` (Node) or `file` and `line` (PHP) |
+
+On PHP it does one extra thing: `'production'` also turns off `display_errors`
+and `error_reporting`, so a stray warning can't be printed before the JSON and
+corrupt the response body.
+
+Set it to something like `'development'` while building, and back to
+`'production'` before you publish. Missing key means `'production'`.
+
+> This is a config key, **not** an environment variable. Setting `APP_ENV` in a
+> shell or in a systemd unit has no effect — both backends read it from
+> `config.js` / `config.php` only.
 
 ## Database
 
-Both backends expose a connection singleton reading the same config.
+Both backends expose a connection singleton reading the same config —
+`database/Database.js` (a `mysql2` pool) or `database/Database.php` (a PDO
+singleton).
+
+```js
+const pool = Database.getInstance();
+const [rows] = await pool.execute(sql, params);
+```
 
-- **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,204 @@
 # 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.
+
+## Where you can publish
+
+| 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) | ✅ | ❌ | ❌ |
+
+Static hosting serves files and nothing else — fine if your site has no `/api`
+endpoints, unusable otherwise.
+
+## Requirements
+
+**PHP backend:** a server with PHP support and Composer for the backend
+dependencies.
+
+**Node backend:** Node.js 18+ and shell access to run a persistent process — a
+VPS you control.
 
 ---
 
 ## Shared hosting (Apache)
 
-The most common option, and the natural home for the **PHP** backend — shared
-hosting can't keep a Node process alive.
+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.
 
-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.
-
-**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`.
+**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`.
 
 ## Windows hosting (IIS)
 
-Same idea, different server. Upload the contents of `out`; `web.config` is
-already there and read automatically.
+Same idea: upload the contents of `out`, `web.config` is already there and read
+automatically.
+
+**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.
 
-**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)
 
-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.
+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.
+
+Upload the contents of `out` to `/var/www/SITE_FOLDER`, then follow the steps
+below.
+
+### 1. Replace
+
+| Placeholder | Where |
+|---|---|
+| `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` | file name in the commands below |
 
-Nibula ships `nginx.conf` in the project root as a **ready-to-use site file**:
-replace three placeholders, symlink it, reload.
+### 2. Install (skip if already present)
 
 ```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
+sudo apt update
+sudo apt install -y nginx certbot python3-certbot-nginx
+```
+
+If you are using PHP as backend:
+
+```bash
+sudo apt install -y php-fpm
+```
+
+### 3. Certificate
+
+```bash
+sudo certbot certonly --nginx --cert-name SITE_NAME -d YOUR_DOMAIN
+sudo systemctl enable --now certbot.timer      # auto-renew every 90 days
 ```
 
-Full reference, requirements and troubleshooting: **`docs/Nginx.md`**.
+### 4. Install the site
 
-## Static hosting (Netlify, Vercel, GitHub Pages)
+```bash
+# Move to nginx folders
+cd /etc/nginx/sites-available
+
+# Create and write a new file
+sudo nano SITE_NAME
+# CTRL + O, ENTER, CTRL + X
 
-Frontend only. Neither backend runs there — no PHP, no persistent process. Fine
-if your site has no `/api` endpoints.
+# 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
+
+| Symptom | Cause |
+|---|---|
+| `cannot load certificate ... Permission denied` | `nginx -t` needs sudo |
+| `cannot load certificate ... No such file` | wrong certificate name |
+| `no alternative certificate subject name` | certificate doesn't cover domain |
+| `unknown directive "http2"` | nginx < 1.25, check with `nginx -v` |
+| NXDOMAIN / timeout during certbot | DNS not pointing here |
+| 500 instead of the 404 page | `404.html` missing |
+| 502 on `/api`, Node deployed | Node process not running |
+| 502 on `/api`, PHP deployed | wrong php-fpm socket path |
 
 ---
 
 ## 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/SITE_FOLDER/backend
    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.
+2. Make sure `config.js` exists in `out/backend/` (copy `example.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
+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
-   `/etc/systemd/system/backend-node.service`, adjust `WorkingDirectory` and the
-   `node` path (`which node`), then:
-```bash
+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.
+   Create `/etc/systemd/system/backend-node.service`:
+
+   ```ini
+   [Unit]
+   Description=Nibula Node backend
+   After=network.target
+
+   [Service]
+   Type=simple
+   User=www-data
+   WorkingDirectory=/var/www/SITE_FOLDER/backend
+   ExecStart=/usr/bin/node /var/www/SITE_FOLDER/backend/_core/index.js
+   Restart=always
+   RestartSec=5
+
+   [Install]
+   WantedBy=multi-user.target
+   ```
+
+   Adjust `WorkingDirectory` and the `node` path (`which node`), then:
+
+   ```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
 
+Read by the Node backend at startup. Set them in the systemd unit with
+`Environment=KEY=value`.
+
 | 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) |
-| `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
+| `PORT` | `3000` | Port Node listens on (must match the proxy target in `nginx.conf`) |
+| `HOST` | `127.0.0.1` | Bind address — keep it local; the web server is the public face |
+| `DOCUMENT_ROOT` | auto (`SITE_FOLDER/`) | Where `404.html` lives; detected as the folder above `backend/` |
 
-Since a given deployment runs only one backend, this is a one-time setup.
+Error verbosity is **not** an environment variable: it is the `APP_ENV` key in
+`config.js` / `config.php`. See `docs/Backend.md`.

package/nginx.conf

@@ -1,42 +1,12 @@
 # =============================================================================
-#  Nibula — default nginx site configuration
-#  Static site + optional HTTP backend on 127.0.0.1:3000. PHP not handled.
+#  Nibula — nginx site configuration
 # -----------------------------------------------------------------------------
-#  REPLACE
+#  Replace the three placeholders below, then follow the setup steps in
+#  docs/Deploy.md → "Your own server (Nginx on a VPS)".
 #
-#    YOUR_DOMAIN        server_name, twice (port 80 and 443)
-#    SITE_FOLDER        document root under /var/www/
-#
-#    YOUR_CERTIFICATE   dir under /etc/letsencrypt/live/ — not always the sam
-#                       as YOUR_DOMAIN. Check: sudo certbot certificates
-#
-#    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
-#     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
-#
-#  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
-#    500 instead of the 404 page                    → 404.html missing
-#    NXDOMAIN / timeout during certbot              → DNS not pointing here
+#    YOUR_DOMAIN        your domain — server_name, twice (port 80 and 443)
+#    SITE_FOLDER        the folder under /var/www/ holding the site
+#    YOUR_CERTIFICATE   the directory name under /etc/letsencrypt/live/
 # =============================================================================
 
 # HTTP (80) configuration
@@ -63,7 +33,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 +65,7 @@ server {
         return 404;
     }
 
-    location ~* ^/(web\.config)$ {
+    location ~* (^|/)web\.config$ {
         return 404;
     }
 
@@ -103,14 +73,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 +89,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.1",
   "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/src/backend/example.config.php

@@ -1,14 +1,21 @@
 <?php
 declare(strict_types=1);
 
+/**
+ * Mirror of src/backend/example.config.js
+ *
+ * Versioned, secret-free template. On setup, copy this file to config.php and
+ * fill in real values. config.php is git-ignored and stays local.
+ */
+
 return [
     // Default key for protected endpoints that don't have a specific key in CUSTOM_ENDPOINT_KEYS
     'GENERAL_API_KEY' => 'DEFAULT_KEY',
 
-    // If you want restrict access to protected endpoints to specific clients, you can define custom keys for each endpoint
+    // If you want to restrict access to protected endpoints to specific clients, define custom keys per endpoint.
     // For subfolder endpoints, use the relative path ('subfolder/endpoint')
     'CUSTOM_ENDPOINT_KEYS' => [
-        'subfolder/example-protected'    => 'custom-key',
+        'subfolder/example-protected' => 'custom-key',
     ],
 
     'GENERAL_ALLOWED_ORIGINS' => [
@@ -17,7 +24,7 @@ return [
     ],
 
     'CUSTOM_ENDPOINT_ORIGINS' => [
-        'subfolder/example-protected'    => ['https://app.example.com'],
+        'subfolder/example-protected' => ['https://app.example.com'],
     ],
 
     // Database configuration
@@ -25,4 +32,7 @@ return [
     'DB_NAME' => 'example_db',
     'DB_USER' => 'root',
     'DB_PASS' => '',
+
+    // Environment: 'production' hides error details; anything else = debug.
+    'APP_ENV' => 'production',
 ];

package/src/backend/package.json

@@ -6,8 +6,7 @@
   "main": "_core/index.js",
   "type": "commonjs",
   "scripts": {
-    "start": "node _core/index.js",
-    "dev": "APP_ENV=development node _core/index.js"
+    "start": "node _core/index.js"
   },
   "engines": {
     "node": ">=18"

package/tools/lib/files.js

@@ -52,6 +52,16 @@ function removeDirectory(target) {
     return true;
 }
 
+function removeDirectoryIfEmpty(target) {
+    try {
+        if (fs.readdirSync(target).length > 0) return false;
+        fs.rmdirSync(target);
+        return true;
+    } catch (error) {
+        return false;
+    }
+}
+
 module.exports = {
     exists,
     readText,
@@ -62,4 +72,5 @@ module.exports = {
     moveFile,
     removeFile,
     removeDirectory,
-};
+    removeDirectoryIfEmpty,
+};

package/tools/lib/pageActions.js

@@ -1,7 +1,7 @@
 const path = require('path');
 const settings = require('../config/settings.json');
 const { PATHS } = require('./paths');
-const { exists, readText, writeText, copyFile, moveFile, removeFile, removeDirectory } = require('./files');
+const { exists, readText, writeText, copyFile, moveFile, removeFile, removeDirectory, removeDirectoryIfEmpty } = require('./files');
 const { log } = require('./logger');
 const { formatText } = require('./text');
 const { languageSettings } = require('./project');
@@ -133,6 +133,12 @@ function removePage(pageName) {
 
     removePageBlock(pageName);
     removeSiteData(pageName);
+
+    const sourceDirectories = [source.style, source.script, source.route].map(file => path.dirname(file));
+
+    for (const directory of sourceDirectories) {
+        if (removeDirectoryIfEmpty(directory)) log('page.fileDeleted', { path: directory });
+    }
 }
 
 module.exports = { addPage, removePage, renamePage };

package/.github/workflows/publish.yml

@@ -1,37 +0,0 @@
-name: Publish to npm
-
-on:
-  release:
-    types: [published]
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  id-token: write
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          registry-url: https://registry.npmjs.org
-
-      - name: Check that package.json matches the tag
-        if: github.event_name == 'release'
-        run: |
-          TAG="${GITHUB_REF_NAME#v}"
-          PKG=$(node -p "require('./package.json').version")
-          if [ "$TAG" != "$PKG" ]; then
-            echo "Tag $TAG does not match package.json version $PKG"
-            exit 1
-          fi
-
-      - run: npm install -g npm@latest
-
-      - run: npm ci
-
-      - run: npm publish --provenance --access public

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