deployment guide

DEPLOYMENT.md

@@ -148,5 +148,56 @@ If you see `ERR_CONNECTION_REFUSED` errors for `/_app/immutable/` assets:
 
 ## Environment Variables
 
-If you need to set environment variables, edit the `env` section in `ecosystem.config.cjs` or create a `.env` file in `/floter-design`.
+### Important: VITE_PUBLIC_* Variables
+
+Variables prefixed with `VITE_PUBLIC_` (like `VITE_PUBLIC_CLOUDINARY_CLOUD_NAME`) must be available **at build time**, not just runtime. They are embedded in the client bundle during `npm run build`.
+
+### Setting Up Environment Variables
+
+**1. Create a `.env` file in your project directory:**
+
+```bash
+cd ~/floter-design
+nano .env
+```
+
+Add your environment variables:
+```bash
+# Cloudinary Configuration (required)
+VITE_PUBLIC_CLOUDINARY_CLOUD_NAME=your-actual-cloud-name
+
+# Add any other VITE_PUBLIC_* variables you need
+```
+
+**2. Build with environment variables:**
+
+The `.env` file will be automatically loaded when you run:
+```bash
+npm run build
+```
+
+**3. For runtime-only environment variables** (not prefixed with `VITE_PUBLIC_`):
+
+Edit `ecosystem.config.cjs` and add them to the `env` section:
+```javascript
+env: {
+  NODE_ENV: 'production',
+  PORT: 3001,
+  HOST: '0.0.0.0',
+  // Add other runtime variables here
+}
+```
+
+**4. After updating `.env`, rebuild and restart:**
+
+```bash
+npm run build
+pm2 restart floter-design
+```
+
+**5. Security Note:**
+
+- Never commit `.env` files to git (already in `.gitignore`)
+- The `.env` file should contain your actual secrets
+- `VITE_PUBLIC_*` variables are exposed to the client-side code - don't put secrets there