Fix for Issue1182

ENVEXAMPLE

@@ -1,6 +1,7 @@
 # App Setup
 NODE_ENV=production                     # Set to 'development' or 'production' as required
-JWT_SECRET=a9Z$kLq7^f03GzNw!bP9dH4xV6sT2yXl3O8vR@uYq3          # Replace with a secure JWT secret key
+JWT_SECRET=TkcGHojOW6vSFoiw/5BIvUI9Zq3L/j08V0/YgsdOqbzNPxYAUCtQGqkGsKfXjOmZ         
+# Replace with a secure JWT secret key
 DB_NAME=maxun                           # Your PostgreSQL database name
 DB_USER=postgres                        # PostgreSQL username
 DB_PASSWORD=postgres                    # PostgreSQL password

SETUP.md

@@ -2,6 +2,7 @@
 1. Create a root folder for your project (e.g. 'maxun')
 2. Create a file named `.env` in the root folder of the project
 3. Example env file can be viewed [here](https://github.com/getmaxun/maxun/blob/master/ENVEXAMPLE). Copy all content of example env to your `.env` file.
+*OPTIONAL* Instead of copying the example by hand, you can generate a complete `.env` by running `bash docs/generate-env.sh` from the root of a cloned Maxun repo. It writes `.env` into the current directory.
 4. Choose your installation method below
 
 ### Docker Compose

docs/generate-env.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+#
+# Generates a .env file with freshly generated secrets.
+#
+#   ./docs/generate-env.sh          # writes ./.env
+#   ./docs/generate-env.sh --print  # prints to stdout instead
+#
+# Every generated value is hex or base64, neither of which contains "$".
+# A literal "$" in a value would be read by Docker Compose as a variable
+# reference and silently dropped, so avoid one if you edit these by hand.
+
+set -euo pipefail
+
+OUT=".env"
+PRINT_ONLY=0
+
+for arg in "$@"; do
+  case "$arg" in
+    --print) PRINT_ONLY=1 ;;
+    -h|--help) sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "unknown option: $arg" >&2; exit 1 ;;
+  esac
+done
+
+if ! command -v openssl >/dev/null 2>&1; then
+  echo "openssl is required but was not found on PATH." >&2
+  exit 1
+fi
+
+if [ "$PRINT_ONLY" -eq 0 ] && { [ -e "$OUT" ] || [ -L "$OUT" ]; }; then
+  echo "$OUT already exists. Move or delete it first, or use --print." >&2
+  exit 1
+fi
+
+# ENCRYPTION_KEY must be exactly 64 hex characters; the others are free-form.
+JWT_SECRET="$(openssl rand -base64 48)"
+DB_PASSWORD="$(openssl rand -base64 24)"
+ENCRYPTION_KEY="$(openssl rand -hex 32)"
+SESSION_SECRET="$(openssl rand -base64 48)"
+MINIO_SECRET_KEY="$(openssl rand -base64 24)"
+
+render() {
+cat <<ENV
+# Generated by docs/generate-env.sh
+#
+# Secrets below are freshly generated. Replace the URLs with your own domain
+# before starting the stack.
+#
+# Do not put a literal dollar sign in any value: Docker Compose reads it as a
+# variable reference and silently drops it. Double it to escape one.
+
+NODE_ENV=production
+JWT_SECRET=${JWT_SECRET}
+DB_NAME=maxun
+DB_USER=postgres
+DB_PASSWORD=${DB_PASSWORD}
+DB_HOST=postgres
+DB_PORT=5432
+ENCRYPTION_KEY=${ENCRYPTION_KEY}
+SESSION_SECRET=${SESSION_SECRET}
+MINIO_ENDPOINT=minio
+MINIO_PORT=9000
+MINIO_CONSOLE_PORT=9001
+MINIO_ACCESS_KEY=minio
+MINIO_SECRET_KEY=${MINIO_SECRET_KEY}
+REDIS_HOST=maxun-redis
+REDIS_PORT=6379
+REDIS_PASSWORD=
+BACKEND_PORT=8080
+FRONTEND_PORT=5173
+BACKEND_URL=https://maxun.my.domain
+PUBLIC_URL=https://maxun.my.domain
+VITE_BACKEND_URL=https://maxun.my.domain
+VITE_PUBLIC_URL=https://maxun.my.domain
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+GOOGLE_REDIRECT_URI=
+AIRTABLE_CLIENT_ID=
+AIRTABLE_REDIRECT_URI=
+MAXUN_TELEMETRY=true
+ENV
+}
+
+if [ "$PRINT_ONLY" -eq 1 ]; then
+  render
+else
+  (umask 077; render > "$OUT")
+  chmod 600 "$OUT"
+  echo "Wrote $OUT with generated secrets."
+  echo "Edit the BACKEND_URL / PUBLIC_URL lines to match your domain before starting."
+fi

docs/self-hosting-docker.md

@@ -15,40 +15,80 @@ For this guide, we assume that before you start, you have a dedicated docker fol
 1. Change directory into your docker folder `cd /home/$USER/Docker/`
 2. Create a new directory for maxun and all the required sub-folders for our docker services `mkdir -p maxun/{db,minio,redis}`
 3. Change directory to enter the newly created folder `cd maxun`
-4. Create an environment file to save your variables `nano .env` with the following contents:
-```
-NODE_ENV=production
-JWT_SECRET=openssl rand -base64 48
-DB_NAME=maxun
-DB_USER=postgres
-DB_PASSWORD=openssl rand -base64 24
-DB_HOST=postgres
-DB_PORT=5432
-ENCRYPTION_KEY=openssl rand -base64 64
-SESSION_SECRET=openssl rand -base64 48
-MINIO_ENDPOINT=minio
-MINIO_PORT=9000
-MINIO_CONSOLE_PORT=9001
-MINIO_ACCESS_KEY=minio
-MINIO_SECRET_KEY=openssl rand -base64 24
-REDIS_HOST=maxun-redis
-REDIS_PORT=6379
-REDIS_PASSWORD=
-BACKEND_PORT=8080
-FRONTEND_PORT=5173
-BACKEND_URL=https://maxun.my.domain
-PUBLIC_URL=https://maxun.my.domain
-VITE_BACKEND_URL=https://maxun.my.domain
-VITE_PUBLIC_URL=https://maxun.my.domain
-GOOGLE_CLIENT_ID=
-GOOGLE_CLIENT_SECRET=
-GOOGLE_REDIRECT_URI=
-AIRTABLE_CLIENT_ID=
-AIRTABLE_REDIRECT_URI=
-MAXUN_TELEMETRY=true
-```
-5. Ctrl + x, Y, Enter will save your changes
-6. Please be sure to READ this file and change the variables to match your environment!!! i.e. BACKEND_PORT=30000
+4. Create your `.env` file. Use **either** option below.
+
+   **Option A — generate it automatically (recommended)**
+
+   From inside the `maxun` folder you created in step 2 open a terminal that can run bash/.sh file and run the generate-env.sh file:
+
+   ```bash
+   bash generate-env.sh
+   ```
+   -or-
+   ./generate-env (whatever you use to run scripts) 
+
+   It writes `.env` into the current directory, so run it from the same folder
+   your `docker-compose.yml` will live in. Requires `openssl` and bash — on
+   Windows, use WSL or Git Bash.
+
+   **Option B — write it yourself**
+
+   Run each command below and paste its output after the matching `=`:
+
+   ```bash
+   openssl rand -base64 48   # JWT_SECRET
+   openssl rand -base64 24   # DB_PASSWORD
+   openssl rand -hex 32      # ENCRYPTION_KEY  (must be 64 hex characters)
+   openssl rand -base64 48   # SESSION_SECRET
+   openssl rand -base64 24   # MINIO_SECRET_KEY
+   ```
+
+   Then create the file with `nano .env` and paste in the following, replacing
+   each placeholder with the matching output above:
+
+   ```dotenv
+   NODE_ENV=production
+   JWT_SECRET=<output of first command>
+   DB_NAME=maxun
+   DB_USER=postgres
+   DB_PASSWORD=<output of second command>
+   DB_HOST=postgres
+   DB_PORT=5432
+   ENCRYPTION_KEY=<output of third command>
+   SESSION_SECRET=<output of fourth command>
+   MINIO_ENDPOINT=minio
+   MINIO_PORT=9000
+   MINIO_CONSOLE_PORT=9001
+   MINIO_ACCESS_KEY=minio
+   MINIO_SECRET_KEY=<output of fifth command>
+   REDIS_HOST=maxun-redis
+   REDIS_PORT=6379
+   REDIS_PASSWORD=
+   BACKEND_PORT=8080
+   FRONTEND_PORT=5173
+   BACKEND_URL=https://maxun.my.domain
+   PUBLIC_URL=https://maxun.my.domain
+   VITE_BACKEND_URL=https://maxun.my.domain
+   VITE_PUBLIC_URL=https://maxun.my.domain
+   GOOGLE_CLIENT_ID=
+   GOOGLE_CLIENT_SECRET=
+   GOOGLE_REDIRECT_URI=
+   AIRTABLE_CLIENT_ID=
+   AIRTABLE_REDIRECT_URI=
+   MAXUN_TELEMETRY=true
+   ```
+
+   Save with Ctrl + X, Y, Enter.
+
+   > Do not put a literal dollar sign in any value. Docker Compose reads it as
+   > a variable reference and silently drops it, leaving you with a shorter
+   > secret than you pasted. Double it to escape one.
+
+6. Whichever option you used, READ the file and change the variables to match
+   your environment — in particular `BACKEND_URL`, `PUBLIC_URL`,
+   `VITE_BACKEND_URL`, `VITE_PUBLIC_URL`, and any ports you need to change
+   (i.e. `BACKEND_PORT=30000`).
+
 7. Create a file for docker compose `nano docker-compose.yml` with the following contents:
 ```yml
 services:
@@ -123,11 +163,11 @@ services:
     depends_on:
       - backend
 ```
-8. Ctrl + x, Y, Enter will save your changes
-9. This particular setup is "production ready" meaning that maxun is only accessible from localhost. You must configure a reverse proxy to access it!
-10. Start maxun `sudo docker compose up -d` or `sudo docker-compose up -d`
-11. Wait 30 seconds for everything to come up
-12. Access your maxun instance at http://localhost:5173 if using defaults
+7. Ctrl + x, Y, Enter will save your changes
+8. This particular setup is "production ready" meaning that maxun is only accessible from localhost. You must configure a reverse proxy to access it!
+9. Start maxun `sudo docker compose up -d` or `sudo docker-compose up -d`
+10. Wait 30 seconds for everything to come up
+11. Access your maxun instance at http://localhost:5173 if using defaults
 
 ## Next steps
 You will want to configure a reverse proxy. Click on a link below to check out some examples.