@studiometa/forge-cli 0.5.2 → 0.5.3

package/README.md

@@ -121,6 +121,7 @@ forge config delete                            # Delete all stored config
 ```bash
 forge servers list                  # List all servers
 forge servers get <id>              # Get server details
+forge servers public-key <id>       # Print the public key of the forge user, for the git host
 forge servers reboot <id>           # Reboot a server
 forge servers create --name <name> --ip-address <ip> [--php-version php84 --database mariadb1011]
                                     # Create a server (Custom VPS by default)
@@ -155,6 +156,7 @@ forge sites apply --file site.json          # Make the site match the file
   },
   "database": { "name": "example", "user": "example" },
   "env": { "APP_ENV": "production" },
+  "nginx": "nginx.conf",
   "workers": [{ "command": "php artisan queue:work database --queue=default", "processes": 4 }],
   "schedule": [{ "command": "php artisan schedule:run", "frequency": "minutely" }]
 }
@@ -165,11 +167,44 @@ forge sites apply --file site.json          # Make the site match the file
 | `server`, `domain`                          | Find the server and the site by exact name (never a partial match, with or without `--exact`). `server` can also be an ID                                                              |
 | `type`, `php`, `webDirectory`, `repository` | Create the site when it is missing (`type` is then required) and wait until Forge installs it. On an existing site, update `php`, `webDirectory` and the branch                        |
 | `aliases`                                   | Add the missing aliases. Never remove one                                                                                                                                              |
-| `database`                                  | Create the database and the user when they are missing. A new user gets a random password, written only into the site `.env` (`DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`)             |
+| `database`                                  | Create the database and the user when they are missing. A new user gets a random password, written only into the site `.env` (`DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`, see below)  |
 | `env`                                       | Add the missing keys to the site `.env`. A key with another value on Forge is reported, never overwritten                                                                              |
+| `nginx`                                     | Nginx file, relative to the site file, with Forge template variables. Rendered for the site and written when it differs from Forge (see below)                                         |
 | `workers`                                   | Forge background processes of the site. Create the missing ones, delete the ones of the site that the file does not declare. The directory defaults to the site root                   |
 | `schedule`                                  | Forge scheduled jobs of the site (`minutely`, `hourly`, `nightly`, `weekly`, `monthly`, `reboot`, or `custom` with `cron`). A relative `artisan` becomes the absolute path of the site |
 
+For an application that does not read the Laravel names, `database.env` maps the database name, the user and the password to other `.env` keys. Each key is optional and defaults to the Laravel name. Other values, such as the host, go in `env`:
+
+```json
+{
+  "database": {
+    "name": "example",
+    "user": "example",
+    "env": { "name": "DB_NAME", "user": "DB_USER", "password": "DB_PASSWD" }
+  },
+  "env": { "DB_SERVER": "127.0.0.1" }
+}
+```
+
+`nginx` points to an Nginx file that uses the variables of [Forge Nginx templates](https://forge.laravel.com/docs/servers/nginx-templates). `apply` renders the file locally with the values of the site, so one file works on any server, without a template on the server:
+
+| Variable                                        | Value                                                                                                    |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `{{SITE}}`, `{{SITE_ID}}`, `{{USER}}`           | Site name (`www.example.com`), site ID (`456`), site user (`forge`)                                      |
+| `{{DOMAINS}}`                                   | Site name and aliases, separated by spaces                                                               |
+| `{{ROOT_PATH}}`, `{{PATH}}`, `{{DIRECTORY}}`    | Site root, web directory (`/home/forge/www.example.com/public`) and its relative path (`/public`)        |
+| `{{PROXY_PASS}}`                                | PHP-FPM socket, e.g. `unix:/var/run/php/php8.3-fpm.sock` (`php8.3-fpm-<user>.sock` for an isolated site) |
+| `{{PORT}}`, `{{PORT_V6}}`                       | `80` and `[::]:80` (with `default_server` for the site named `default`)                                  |
+| `{{SERVER_PUBLIC_IP}}`, `{{SERVER_PRIVATE_IP}}` | IP addresses of the server (empty when there is no private IP)                                           |
+
+Spaces inside the braces are allowed (`{{ SITE_ID }}`). An unknown variable is an error (exit `3`). On a new site, `apply` writes the file after Forge installs the site. On an existing site, the plan shows the diff from Forge to the rendered file (CRLF and the final newline do not count), and `apply` writes it. When `apply` also changes the site or its aliases, it reads the site again and renders the file with the new values. Forge returns the full `server` block on old servers and only its content on recent ones: write the file in the same form as `forge nginx get` prints it.
+
+Forge clones the repository when it creates the site, with the key of the `forge` user of the server. Add this key to the git host (for example as a deploy key) before `apply` creates the site:
+
+```bash
+forge servers public-key web-1 > server.pub   # The key only; --format json gives { "public_key": "..." }
+```
+
 A worker or a scheduled job matches the file when its command, directory, processes (or frequency) and user are the same. Commands are compared after normalization: quotes (`'database'` and `database`), repeated spaces and a relative `artisan` (`php artisan` and `php /home/forge/www.example.com/artisan`) do not count as differences. Forge cannot update a worker: a changed worker is created again, then the old one is deleted.
 
 `workers` and `schedule` delete what the file does not declare, so `apply` deletes only what surely belongs to the site, because a server often hosts several sites:

package/dist/cli.js

@@ -4,7 +4,7 @@ import { STORAGE_PROVIDER_TYPES } from "@studiometa/forge-api";
 import { PHP_CONFIG_TYPES, RESTARTABLE_SERVICES, activateCertificate, createAuditLogger, createBackupConfig, createCommand, createDaemon, createDatabase, createDatabaseUser, createDomain, createMonitor, createNginxTemplate, createRedirectRule, createScheduledJob, createSecurityRule, createServer, createSite, createSshKey, createStorageProvider, deleteBackupConfig, deleteDaemon, deleteDatabaseUser, deleteMonitor, deleteNginxTemplate, deleteRedirectRule, deleteScheduledJob, deleteSecurityRule, deleteSshKey, deleteStorageProvider, deploySiteAndWait, disablePhpOpcache, enablePhpOpcache, getBackupConfig, getCertificate, getCommand, getDaemon, getDaemonLog, getDatabase, getDatabaseUser, getDeploymentLog, getDeploymentScript, getEnv, getFirewallRule, getMonitor, getNginxConfig, getNginxTemplate, getPhpConfig, getPhpMaxExecutionTime, getPhpMaxUploadSize, getPhpOpcache, getRecipe, getRedirectRule, getScheduledJob, getSecurityRule, getServer, getSite, getSshKey, getStorageProvider, getUser, listBackupConfigs, listCommands, listDaemons, listDatabaseUsers, listDatabases, listDeployments, listFirewallRules, listMonitors, listNginxTemplates, listPhpVersions, listRecipes, listRedirectRules, listScheduledJobs, listSecurityRules, listServers, listServices, listSites, listSshKeys, listStorageProviders, matchByName, rebootServer, restartDaemon, restartService, runRecipe, updateBackupConfig, updateDaemon, updateDatabaseUser, updateDeploymentScript, updateEnv, updateNginxConfig, updateNginxTemplate, updatePhpConfig, updatePhpMaxExecutionTime, updatePhpMaxUploadSize, updateRecipe, updateSecurityRule, updateSite } from "@studiometa/forge-core";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, posix } from "node:path";
+import { dirname, join, posix, resolve } from "node:path";
 import { diff } from "node:util";
 import { createHash, randomBytes } from "node:crypto";
 import * as v from "valibot";
@@ -460,7 +460,7 @@ _forge_completions() {
 
   # Subcommands for each command
   local config_cmds="set get delete"
-  local servers_cmds="list ls get create reboot"
+  local servers_cmds="list ls get public-key create reboot"
   local sites_cmds="list ls get apply"
   local deployments_cmds="list ls deploy logs log script update-script"
   local databases_cmds="list ls get"
@@ -672,6 +672,7 @@ _forge() {
             'list:List all servers'
             'ls:List all servers (alias)'
             'get:Get server details'
+            'public-key:Print the public key of the forge user'
             'create:Create a server'
             'reboot:Reboot a server'
           )
@@ -1030,6 +1031,7 @@ complete -c forge -f -n "__fish_seen_subcommand_from config" -a "delete" -d "Del
 complete -c forge -f -n "__fish_seen_subcommand_from servers s" -a "list" -d "List all servers"
 complete -c forge -f -n "__fish_seen_subcommand_from servers s" -a "ls" -d "List all servers (alias)"
 complete -c forge -f -n "__fish_seen_subcommand_from servers s" -a "get" -d "Get server details"
+complete -c forge -f -n "__fish_seen_subcommand_from servers s" -a "public-key" -d "Print the public key of the forge user"
 complete -c forge -f -n "__fish_seen_subcommand_from servers s" -a "create" -d "Create a server"
 complete -c forge -f -n "__fish_seen_subcommand_from servers s" -a "reboot" -d "Reboot a server"
 
@@ -4290,6 +4292,23 @@ async function serversGet(args, ctx) {
 		ctx.formatter.output(result.data);
 	}, ctx.formatter);
 }
+/**
+* Print the public key of the `forge` user of a server (`~/.ssh/id_rsa.pub`), the key that
+* Forge uses to clone repositories: add it to the git host before you create a site.
+*/
+async function serversPublicKey(args, ctx) {
+	const [server] = args;
+	if (!server) exitWithValidationError("server_id", "forge servers public-key <server_id>", ctx.formatter);
+	await runCommand(async () => {
+		const token = ctx.getToken();
+		const execCtx = ctx.createExecutorContext(token);
+		const result = await getServer({ server_id: await resolveServerId(server, execCtx) }, execCtx);
+		const key = result.data.local_public_key?.trim();
+		if (!key) throw new ApiError(`Server ${result.data.name} has no public key yet`, 404, ["Wait until Forge provisions the server"]);
+		if (ctx.formatter.isJson()) ctx.formatter.output({ public_key: key });
+		else console.log(key);
+	}, ctx.formatter);
+}
 var CREATE_USAGE$1 = "forge servers create --name <name> --ip-address <ip> [options]";
 /**
 * Create a server. Defaults to a Custom VPS app server on Ubuntu 26.04.
@@ -4363,6 +4382,7 @@ var handleServersCommand = createCommandRouter({
 		list: serversList,
 		ls: serversList,
 		get: [serversGet, "args"],
+		"public-key": [serversPublicKey, "args"],
 		create: serversCreate,
 		reboot: [serversReboot, "args"]
 	},
@@ -4402,6 +4422,27 @@ ${colors.bold("OPTIONS:")}
 ${colors.bold("EXAMPLES:")}
   forge servers get 123
   forge servers get 123 --format json
+`);
+	else if (subcommand === "public-key") console.log(`
+${colors.bold("forge servers public-key")} - Print the public key of the forge user
+
+${colors.bold("USAGE:")}
+  forge servers public-key <server_id> [options]
+
+${colors.bold("ARGUMENTS:")}
+  <server_id>         Server ID or name (required)
+
+${colors.bold("OPTIONS:")}
+  -f, --format <fmt>  Output format: json ({ "public_key": "..." }), human (the key only)
+
+Forge clones repositories as the forge user, with this key (~/.ssh/id_rsa.pub).
+Add it to the git host (e.g. as a deploy key) before you create a site with a
+repository. It is not the key of GET /servers/{id}/key: that key lets Forge
+connect to the server.
+
+${colors.bold("EXAMPLES:")}
+  forge servers public-key 123
+  forge servers public-key 123 > server.pub
 `);
 	else if (subcommand === "create") console.log(`
 ${colors.bold("forge servers create")} - Create a server
@@ -4456,6 +4497,7 @@ ${colors.bold("ALIASES:")}
 ${colors.bold("SUBCOMMANDS:")}
   list, ls            List all servers
   get <id>            Get server details
+  public-key <id>     Print the public key of the forge user
   create              Create a server (requires --name, and --ip-address for custom)
   reboot <id>         Reboot a server
 
@@ -4849,6 +4891,14 @@ function planAliases(file, site, changes) {
 		name: alias
 	});
 }
+/** The .env keys of a new database user, from `database.env` or the Laravel names. */
+function databaseEnvKeys(database) {
+	return {
+		name: database.env?.name ?? "DB_DATABASE",
+		user: database.env?.user ?? "DB_USERNAME",
+		password: database.env?.password ?? "DB_PASSWORD"
+	};
+}
 /**
 * Plan the database and its user. Returns the names of the .env keys that get generated values.
 */
@@ -4867,10 +4917,11 @@ function planDatabase(file, state, changes, warnings) {
 			name: user,
 			database: name
 		});
+		const keys = databaseEnvKeys(file.database);
 		return [
-			"DB_DATABASE",
-			"DB_USERNAME",
-			"DB_PASSWORD"
+			keys.name,
+			keys.user,
+			keys.password
 		];
 	}
 	if (!databaseExists) warnings.push(`Database user ${user} exists: apply does not give it access to the new database ${name}.`);
@@ -4884,10 +4935,29 @@ function planEnv(file, state, generated, changes, warnings) {
 		if (!remote.has(key)) keys.push(key);
 		else if (remote.get(key) !== String(value)) warnings.push(`.env key ${key} has another value on Forge: apply does not overwrite it.`);
 	}
-	if (keys.length > 0 || generated.length > 0) changes.push({
-		action: "add-env",
-		keys,
-		generated
+	if (keys.length > 0 || generated.length > 0) {
+		const password = file.database && generated.length > 0 ? databaseEnvKeys(file.database).password : void 0;
+		changes.push({
+			action: "add-env",
+			keys,
+			generated,
+			...password ? { password } : {}
+		});
+	}
+}
+function planNginx(file, state, changes) {
+	if (file.nginxTemplate === void 0) return;
+	if (!state.nginx) {
+		changes.push({
+			action: "update-nginx",
+			diff: null
+		});
+		return;
+	}
+	const diff = unifiedDiff(state.nginx.remote, state.nginx.rendered);
+	if (diff) changes.push({
+		action: "update-nginx",
+		diff
 	});
 }
 function describeOwnership(ownership) {
@@ -5010,6 +5080,7 @@ function buildPlan(file, state) {
 	planAliases(file, state.site, changes);
 	const generated = planDatabase(file, state, changes, warnings);
 	if (file.env || generated.length > 0) planEnv(file, state, generated, changes, warnings);
+	planNginx(file, state, changes);
 	planWorkers(file, state, changes, warnings);
 	planSchedule(file, state, changes, warnings);
 	return {
@@ -5033,7 +5104,8 @@ function describeChange(change) {
 		case "add-alias": return `+ add alias ${change.name}`;
 		case "create-database": return `+ create database ${change.name}`;
 		case "create-database-user": return `+ create database user ${change.name} for ${change.database} (password: ${GENERATED})`;
-		case "add-env": return `+ add .env keys: ${[...change.keys, ...change.generated.map((key) => key === "DB_PASSWORD" ? `${key}=${GENERATED}` : key)].join(", ")}`;
+		case "add-env": return `+ add .env keys: ${[...change.keys, ...change.generated.map((key) => key === change.password ? `${key}=${GENERATED}` : key)].join(", ")}`;
+		case "update-nginx": return change.diff === null ? "~ write Nginx configuration (rendered once the site exists)" : `~ update Nginx configuration:\n${change.diff}`;
 		case "create-worker": return `+ create worker: ${change.command} (directory: ${change.directory}, processes: ${change.processes})`;
 		case "delete-worker": return `- delete worker ${change.id}: ${change.command} (directory: ${quoted(change.directory)}, processes: ${change.processes})`;
 		case "create-job": return `+ create scheduled job: ${change.command} (${change.frequency}${change.cron ? ` ${change.cron}` : ""})`;
@@ -5041,6 +5113,82 @@ function describeChange(change) {
 	}
 }
 //#endregion
+//#region src/commands/sites/apply/nginx.ts
+/** The variables of Forge Nginx templates. Forge accepts spaces inside the braces. */
+var NGINX_VARIABLES = [
+	"DIRECTORY",
+	"DOMAINS",
+	"PATH",
+	"PORT",
+	"PORT_V6",
+	"PROXY_PASS",
+	"ROOT_PATH",
+	"SERVER_PUBLIC_IP",
+	"SERVER_PRIVATE_IP",
+	"SITE",
+	"SITE_ID",
+	"USER"
+];
+/** The variables that need the server, not only the site. */
+var SERVER_VARIABLES = /* @__PURE__ */ new Set(["SERVER_PUBLIC_IP", "SERVER_PRIVATE_IP"]);
+var VARIABLE = /\{\{\s*([^{}]*?)\s*\}\}/g;
+/** The names of the variables in a template, each once, in order. */
+function templateVariables(template) {
+	return [...new Set([...template.matchAll(VARIABLE)].map((match) => match[1]))];
+}
+/**
+* Exit with a validation error when the template has a variable that Forge does not define.
+*/
+function assertNginxTemplate(template, source) {
+	const known = new Set(NGINX_VARIABLES);
+	const unknown = templateVariables(template).filter((name) => !known.has(name));
+	if (unknown.length > 0) throw new ValidationError(`Nginx file ${source} has unknown variables: ${unknown.map((name) => `{{${name}}}`).join(", ")}`, "nginx", [`Supported variables: ${NGINX_VARIABLES.map((name) => `{{${name}}}`).join(", ")}`]);
+}
+/** True when rendering the template needs the attributes of the server. */
+function needsServer(template) {
+	return templateVariables(template).some((name) => SERVER_VARIABLES.has(name));
+}
+/** `PHP 8.3`, `php83` and `php8.3` all give `8.3`. */
+function phpSocketVersion(version) {
+	const digits = version.replaceAll(/\D/g, "");
+	if (digits.length < 2) throw new ValidationError(`Cannot read the PHP version ${version} of the site`, "nginx");
+	return `${digits[0]}.${digits.slice(1)}`;
+}
+/**
+* The value of each variable for a site, as Forge renders its templates.
+* A server is needed only for the `SERVER_*` variables.
+*/
+function nginxValues(site, server = null) {
+	const root = siteWorkDirectory(site);
+	const path = isPathInside(site.web_directory, root) ? normalizePath(site.web_directory) : normalizePath(`${root}/${site.web_directory}`);
+	const directory = path === root ? "/" : path.slice(root.length);
+	const defaultServer = site.name === "default" ? " default_server" : "";
+	const isolated = site.isolated ? `-${site.user}` : "";
+	return {
+		DIRECTORY: directory,
+		DOMAINS: [site.name, ...site.aliases ?? []].join(" "),
+		PATH: path,
+		PORT: `80${defaultServer}`,
+		PORT_V6: `[::]:80${defaultServer}`,
+		get PROXY_PASS() {
+			return `unix:/var/run/php/php${phpSocketVersion(site.php_version)}-fpm${isolated}.sock`;
+		},
+		ROOT_PATH: root,
+		SERVER_PUBLIC_IP: server?.ip_address ?? "",
+		SERVER_PRIVATE_IP: server?.private_ip_address ?? "",
+		SITE: site.name,
+		SITE_ID: String(site.id),
+		USER: site.user
+	};
+}
+/**
+* Replace each variable of the template with its value for the site.
+*/
+function renderNginx(template, site, server = null) {
+	const values = nginxValues(site, server);
+	return template.replaceAll(VARIABLE, (match, name) => name in values ? values[name] : match);
+}
+//#endregion
 //#region src/commands/sites/apply/apply.ts
 /**
 * Read the state of Forge for a site file, and run a plan against Forge.
@@ -5090,6 +5238,7 @@ async function readRemoteState(file, serverId, ctx) {
 			site_id: siteId
 		}, ctx)).data.map((d) => d.id) : []);
 	}
+	if (file.nginxTemplate !== void 0) state.nginx = site ? await readNginx(file.nginxTemplate, serverId, site, ctx) : null;
 	if (file.schedule) {
 		const siteJobs = siteId ? (await listScheduledJobs({
 			server_id: serverId,
@@ -5102,6 +5251,18 @@ async function readRemoteState(file, serverId, ctx) {
 	return state;
 }
 /**
+* Read the Nginx configuration of a site on Forge and render the Nginx file for the site.
+*/
+async function readNginx(template, serverId, site, ctx) {
+	return {
+		remote: (await getNginxConfig({
+			server_id: serverId,
+			site_id: String(site.id)
+		}, ctx)).data,
+		rendered: renderNginx(template, site, needsServer(template) ? (await getServer({ server_id: serverId }, ctx)).data : null)
+	};
+}
+/**
 * Exit with a validation error when the site does not exist and the site file cannot create it.
 */
 function assertCanCreateSite(file, state) {
@@ -5138,10 +5299,12 @@ function setEnvValues(content, values) {
 	for (const [name, value] of pending) result.push(`${name}=${formatEnvValue(value)}`);
 	return `${result.join("\n")}\n`;
 }
+/** Forge clones the repository with the key of the server: the git host must accept it. */
+var REPOSITORY_HINT = (serverId) => `Check that the git host accepts the key of the server: forge servers public-key ${serverId}`;
 var defaultSleep = (ms) => new Promise((resolve) => {
 	setTimeout(resolve, ms);
 });
-async function waitForSite(serverId, siteId, ctx, options) {
+async function waitForSite(file, serverId, siteId, ctx, options) {
 	const sleep = options.sleep ?? defaultSleep;
 	const interval = options.pollIntervalMs ?? 5e3;
 	const timeout = options.timeoutMs ?? 6e5;
@@ -5151,7 +5314,7 @@ async function waitForSite(serverId, siteId, ctx, options) {
 			site_id: siteId
 		}, ctx)).data;
 		if (site.status === "installed") return;
-		if (waited >= timeout) throw new ApplyError(`Site ${site.name} is still ${site.status} on Forge`, ["Run forge sites apply again once the site is installed"]);
+		if (waited >= timeout) throw new ApplyError(`Site ${site.name} is still ${site.status} on Forge`, ["Run forge sites apply again once the site is installed", ...file.repository ? [REPOSITORY_HINT(serverId)] : []]);
 		await sleep(interval);
 	}
 }
@@ -5182,9 +5345,10 @@ async function applyDatabase(file, plan, state, serverId, ctx, options) {
 			...databaseId === void 0 ? {} : { database_ids: [databaseId] }
 		}, ctx);
 		ids.database_user_id = String(user.data.id);
-		env.set("DB_DATABASE", change.database);
-		env.set("DB_USERNAME", change.name);
-		env.set("DB_PASSWORD", password);
+		const keys = databaseEnvKeys(file.database);
+		env.set(keys.name, change.database);
+		env.set(keys.user, change.name);
+		env.set(keys.password, password);
 	}
 	if (databaseId !== void 0) ids.database_id = databaseId;
 	return {
@@ -5193,6 +5357,29 @@ async function applyDatabase(file, plan, state, serverId, ctx, options) {
 	};
 }
 /**
+* Write the rendered Nginx file when it differs from Forge. After a change of the site or its
+* aliases, read the site again: the web directory and the domains are template variables.
+*/
+async function applyNginx(template, plan, serverId, site, ctx, options) {
+	const siteChanged = plan.changes.some((change) => change.action === "update-site" || change.action === "add-alias");
+	if (!plan.changes.some((change) => change.action === "update-nginx") && !siteChanged) return;
+	const params = {
+		server_id: serverId,
+		site_id: String(site.id)
+	};
+	const { remote, rendered } = await readNginx(template, serverId, siteChanged ? (await getSite(params, ctx)).data : site, ctx);
+	const diff = unifiedDiff(remote, rendered);
+	if (!diff) return;
+	options.onChange?.({
+		action: "update-nginx",
+		diff
+	});
+	await updateNginxConfig({
+		...params,
+		content: rendered
+	}, ctx);
+}
+/**
 * Run the changes of a plan for a site that exists.
 */
 async function applyChanges(file, plan, state, serverId, site, generatedEnv, ctx, options) {
@@ -5250,6 +5437,7 @@ async function applyChanges(file, plan, state, serverId, site, generatedEnv, ctx
 			content: setEnvValues(content, env)
 		}, ctx);
 	}
+	if (file.nginxTemplate !== void 0) await applyNginx(file.nginxTemplate, plan, serverId, site, ctx, options);
 	for (const change of creations) {
 		options.onChange?.(change);
 		if (change.action === "create-worker") await createDaemon({
@@ -5309,7 +5497,7 @@ async function applySiteFile(file, serverId, ctx, options = {}) {
 			...settings.branch ? { branch: settings.branch } : {},
 			...database.ids
 		}, ctx);
-		await waitForSite(serverId, String(created.data.id), ctx, options);
+		await waitForSite(file, serverId, String(created.data.id), ctx, options);
 		state = await readRemoteState(file, serverId, ctx);
 		plan = buildPlan(file, state);
 	}
@@ -5364,6 +5552,17 @@ var ScheduledJobSchema = v.pipe(v.strictObject({
 	frequency: v.picklist(SCHEDULE_FREQUENCIES),
 	cron: v.optional(text)
 }), v.check((job) => job.frequency === "custom" === (job.cron !== void 0), "cron is required with the custom frequency, and only with it"));
+var envName = v.pipe(v.string(), v.regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "invalid .env variable name"));
+/** The .env keys that a new database user gets. Default: the Laravel names. */
+var DatabaseEnvSchema = v.pipe(v.strictObject({
+	name: v.optional(envName),
+	user: v.optional(envName),
+	password: v.optional(envName)
+}), v.check((env) => (/* @__PURE__ */ new Set([
+	env.name ?? "DB_DATABASE",
+	env.user ?? "DB_USERNAME",
+	env.password ?? "DB_PASSWORD"
+])).size === 3, "the .env keys of the database must be different"));
 var SiteFileSchema = v.strictObject({
 	$schema: v.optional(v.string()),
 	server: v.union([text, v.pipe(v.number(), v.integer(), v.minValue(1))]),
@@ -5379,13 +5578,15 @@ var SiteFileSchema = v.strictObject({
 	})),
 	database: v.optional(v.strictObject({
 		name: text,
-		user: text
+		user: text,
+		env: v.optional(DatabaseEnvSchema)
 	})),
-	env: v.optional(v.record(v.pipe(v.string(), v.regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "invalid .env variable name")), v.union([
+	env: v.optional(v.record(envName, v.union([
 		v.string(),
 		v.number(),
 		v.boolean()
 	]))),
+	nginx: v.optional(text),
 	workers: v.optional(v.array(WorkerSchema)),
 	schedule: v.optional(v.array(ScheduledJobSchema))
 });
@@ -5403,7 +5604,8 @@ function parseSiteFile(data, source = "site file") {
 	return result.output;
 }
 /**
-* Read and validate a site file from disk.
+* Read and validate a site file from disk, with its Nginx file: a relative `nginx` path is
+* read against the folder of the site file.
 */
 function readSiteFile(path) {
 	let content;
@@ -5418,7 +5620,17 @@ function readSiteFile(path) {
 	} catch (error) {
 		throw new ValidationError(`Site file ${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, "file");
 	}
-	return parseSiteFile(data, `site file ${path}`);
+	const file = parseSiteFile(data, `site file ${path}`);
+	if (file.nginx) {
+		const nginxPath = resolve(dirname(path), file.nginx);
+		try {
+			file.nginxTemplate = readFileSync(nginxPath, "utf8");
+		} catch (error) {
+			throw new ValidationError(`Cannot read Nginx file ${nginxPath}: ${error instanceof Error ? error.message : String(error)}`, "nginx");
+		}
+		assertNginxTemplate(file.nginxTemplate, nginxPath);
+	}
+	return file;
 }
 //#endregion
 //#region src/commands/sites/apply/handler.ts
@@ -5610,9 +5822,15 @@ ${colors.bold("SITE FILE:")}
   A key that is absent is not managed: apply does not read or change it.
     type, php, webDirectory, repository   Create the site, or update php, web directory, branch
     aliases                               Add missing aliases, never remove one
-    database { name, user }               Create when missing; a new user gets a random
-                                          password, written into the site .env only
+    database { name, user, env }          Create when missing; a new user gets a random
+                                          password, written into the site .env only.
+                                          env maps { name, user, password } to .env keys
+                                          (default DB_DATABASE, DB_USERNAME, DB_PASSWORD)
     env                                   Add missing keys, never overwrite a value
+    nginx                                 Nginx file, relative to the site file, with Forge
+                                          template variables such as {{PATH}}, {{SITE_ID}},
+                                          {{PROXY_PASS}}: rendered for the site, written
+                                          when it differs (an unknown variable exits 3)
     workers, schedule                     Create missing ones, delete the ones of the site
                                           that the file does not declare ([] deletes all)
 
@@ -6493,7 +6711,7 @@ function isVersionRequest({ command, options }) {
 }
 //#endregion
 //#region src/cli.ts
-var VERSION = "0.5.2";
+var VERSION = "0.5.3";
 function showHelp() {
 	console.log(`
 ${colors.bold("forge")} v${VERSION}