create-amoxi-app 0.6.1 → 0.7.0

package/index.js

@@ -11,6 +11,7 @@
  *
  * No dependencies; works on Windows, macOS and Linux.
  */
+const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
@@ -271,6 +272,15 @@ async function main() {
     engines: { node: '>=22' },
   };
   fs.writeFileSync(path.join(target, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`);
+  // Production requires a session secret. This one lets `npm start` run on this machine; the file is
+  // git-ignored and kept out of Docker images, so each server sets its own AMOXI_SESSION_SECRET.
+  fs.writeFileSync(
+    path.join(target, '.env.production.local'),
+    `# Generated by create-amoxi-app for running \`npm start\` on this machine. Git and Docker ignore this file:\n` +
+      `# set AMOXI_SESSION_SECRET on each server (the same value on every instance).\n` +
+      `AMOXI_SESSION_SECRET=${crypto.randomBytes(32).toString('hex')}\n`,
+    { mode: 0o600 },
+  );
   // Every file is written: from here on the project stays, even if installing fails.
   unfinished = undefined;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-amoxi-app",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Create an Amoxi app: npx create-amoxi-app@latest my-app",
   "keywords": [
     "amoxi",

package/templates/agent/README.md

@@ -13,7 +13,9 @@ Created with `create-amoxi-app`.
 
 ## Configuration
 
-No environment variables are required. Settings come from `application.json`, then `application-<profile>.json`, then `.env` files, then environment variables. The profile is `production` under `npm start` and `development` under `npm run dev`.
+Settings come from `application.json`, then `application-<profile>.json`, then `.env` files, then environment variables. The profile is `production` under `npm start` and `development` under `npm run dev`.
+
+Production needs one secret, `AMOXI_SESSION_SECRET`, which encrypts session cookies: 32 or more random characters, the same on every instance, never committed. `create-amoxi-app` put one in `.env.production.local` so `npm start` works on this machine; that file is git-ignored and kept out of Docker images, so set the variable on each server (for Docker: `docker run -e AMOXI_SESSION_SECRET=...`).
 
 ## Deploy
 

package/templates/shared/Dockerfile

@@ -1,6 +1,6 @@
 # syntax=docker/dockerfile:1
 #   docker build -t {{APP_NAME}} .
-#   docker run -p 8080:8080 {{APP_NAME}}
+#   docker run -p 8080:8080 -e AMOXI_SESSION_SECRET=<32+ random characters> {{APP_NAME}}
 
 FROM node:22-alpine AS build
 WORKDIR /app

package/templates/shared/README.md

@@ -13,7 +13,9 @@ Created with `create-amoxi-app`.
 
 ## Configuration
 
-No environment variables are required. Settings come from `application.json`, then `application-<profile>.json`, then `.env` files, then environment variables. The profile is `production` under `npm start` and `development` under `npm run dev`.
+Settings come from `application.json`, then `application-<profile>.json`, then `.env` files, then environment variables. The profile is `production` under `npm start` and `development` under `npm run dev`.
+
+Production needs one secret, `AMOXI_SESSION_SECRET`, which encrypts session cookies: 32 or more random characters, the same on every instance, never committed. `create-amoxi-app` put one in `.env.production.local` so `npm start` works on this machine; that file is git-ignored and kept out of Docker images, so set the variable on each server (for Docker: `docker run -e AMOXI_SESSION_SECRET=...`).
 
 ## Deploy
 

package/templates/shared/_env.example

@@ -1,4 +1,11 @@
-# Optional settings. Nothing here is required: the app runs without any environment variables.
+# Settings from the environment. Development needs none. Production needs AMOXI_SESSION_SECRET.
 # Copy to .env.local for local overrides (git-ignored), or set them in your hosting environment.
 # Any configuration key works; dots become underscores, e.g. server.port:
 # SERVER_PORT=8080
+
+# Required in production: encrypts session cookies. 32+ random characters, the same on every instance,
+# never committed. Generate one with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+# (create-amoxi-app put one in .env.production.local so `npm start` works on this machine.)
+# AMOXI_SESSION_SECRET=
+# Behind a load balancer or proxy that terminates TLS, so client IPs and HTTPS are seen correctly:
+# SERVER_TRUSTPROXY=true