# Környezet Cheat Sheet

Ez a jegyzet arra való, hogy pár hét vagy hónap múlva gyorsan vissza lehessen nézni, hogyan működik a Fogyasztó Barát Shopify app környezete: mi fut lokálisan, mi fut a szerveren, mikor kell build, mikor kell Shopify deploy, és hogyan érdemes feltölteni az appot.

Fontos: ez a jegyzet már a public app verzióra vonatkozik. A régi custom app külön létezik tesztelési / korábbi használati célra, de ezt a projektet és ezt a hostot nem az szolgálja ki.

## Rövid fejbeni modell

- A kód nálam van, ebben a projektben.
- Az éles public app a saját szerveren fut: `https://shopify-public.fogyasztobarat.hu`
- A Shopify nem a teljes kódot tárolja, hanem az app konfigurációját.
- A szerveren Node.js appként fut az alkalmazás, cPanel + Passenger indítja.
- A szerver nem közvetlenül a nyers `app/...` fájlokat futtatja, hanem a buildelt kimenetet.

PHP-s fejjel:

- PHP-nál gyakran feltöltöm a fájlt, és már fut is.
- Itt forrást módosítok, buildet készítek, majd a Node app a buildelt kimenetet futtatja.

## Mi hol van?

Lokális projekt:

```text
C:\Users\csord\Documents\Codex projects\fogyasztobarat-app-public
```

Éles szerveres app mappa:

```text
/home/jutasa/public_html/shopify-public.fogyasztobarat.hu
```

Éles app URL:

```text
https://shopify-public.fogyasztobarat.hu
```

cPanel Node log:

```text
/home/jutasa/logs/... (a public Node app Passenger logja, a pontos fájlnevet cPanelben nézd meg)
```

## Mi a dev?

```bash
shopify app dev
```

Ez a helyi fejlesztői mód.

Ilyenkor:

- lokálisan fut az app,
- figyeli a változásokat,
- fejlesztői / tunnel URL-t használhat,
- gyors tesztelésre való.

Ez nem az éles szerveres futás.

## Mi az éles / szerveres futás?

Az éles public app a saját szerveren fut:

```text
https://shopify-public.fogyasztobarat.hu
```

Itt:

- a projekt fel van töltve a szerverre,
- Node.js appként fut,
- a Passenger indítja,
- a Shopify ide irányítja a felhasználót.

## Mi a build?

Forrásfájlok például:

```text
app/
extensions/
prisma/
public/
```

Buildelt kimenet:

```text
build/server/
build/client/
```

Ha kódot vagy UI-t módosítok, attól a szerveren még nem változik semmi, amíg nincs új build és restart.

## Hol módosítsak?

App működés / route / API módosítás:

```text
app/routes/
app/services/
app/
```

Landing / login oldal design:

```text
app/routes/_index...
```

vagy az ehhez tartozó CSS fájl.

Shopify app konfiguráció:

```text
shopify.app.toml
```

Extensionök:

```text
extensions/
```

## Fogyasztó Barát oldali automatikus Shopify frissítés

Fontos: nem csak a Shopify app admin felületéről lehet szabályzatot frissíteni.

A Fogyasztó Barát oldalon két folyamat is automatikusan meghívja a Shopify appot:

```text
ajax/public.php
pages/generate-all-docs-ajax.php
```

Ezek akkor futnak, amikor:

- egy dokumentum közzététele történik,
- vagy tömeges dokumentumgenerálás fut.

Ilyenkor a Fogyasztó Barát backend elküldi a Shopify appnak az érintett shopot, widget ID-t és dokumentumtípust. A Shopify app ez alapján frissíti a megfelelő Shopify szabályzat / policy tartalmat.

A Shopify app oldali endpoint:

```text
POST https://shopify-public.fogyasztobarat.hu/api/policies/refresh
```

Gyakorlati jelentés:

- ha Fogyasztó Barát oldalon közzéteszünk egy dokumentumot, a Shopify oldali policy is frissülhet automatikusan,
- ha tömeges generálás fut, a kapott dokumentumtípus alapján szintén elindulhat a Shopify frissítés,
- ehhez a shopnál telepítve kell lennie az appnak, és mentve kell lennie a megfelelő Widget ID-nak.

Ezek az automatikus hívások a Fogyasztó Barát oldali adatbázisban is naplózásra kerülnek:

```text
agrgen_shopify_policy_refresh_logs
```

Ennek célja, hogy később visszakereshető legyen, mikor melyik shopnál, melyik widget ID-val, milyen dokumentumtípusra futott Shopify policy refresh, és milyen eredménnyel tért vissza.

## Shopify dev és deploy különbsége

```bash
shopify app dev
```

- Helyi fejlesztésre való.
- Lokálisan futtatja az appot.
- Figyeli a változásokat.
- Nem az éles szervert frissíti.

```bash
shopify app deploy
```

- A Shopify oldali app-konfigurációt frissíti.
- Ilyen például: app URL, redirect URL, scope-ok, webhookok, extension konfiguráció, verziókiadás.
- Nem a saját szerverre tölti fel a kódot.

Fontos: a `shopify app deploy` általában a saját gépen fut, nem a szerveren, mert a Shopify CLI lokálisan van telepítve.

## Mit kell feltölteni a szerverre?

Ha szerveren akarok buildelni, akkor nem elég csak a `build` mappát feltölteni. Fel kell tölteni a forrást is.

Feltöltendő:

```text
app/
extensions/
prisma/
public/
docs/                       opcionális
.env                        csak ha szerverre való értékek vannak benne
package.json
package-lock.json
shopify.app.toml
shopify.web.toml
vite.config.js
tsconfig.json
passenger.cjs
```

Nem kell feltölteni:

```text
node_modules/
build/
.git/
.shopify/
.react-router/
.cursor/
.gemini/
.tmp_barat_base64.txt
dev.sqlite
logok
cache-ek
ideiglenes fájlok
Dockerfile
README.md
```

## Prisma mappa és adatbázis: nagyon fontos

Éles szerveren a `prisma` mappát nem szabad vakon törölni.

Szerveren itt van:

```text
/home/jutasa/public_html/shopify-public.fogyasztobarat.hu/prisma
```

Ebben lehet:

```text
schema.prisma
migrations/
dev.sqlite vagy más SQLite adatbázisfájl
```

Fontos különbség:

- a `schema.prisma` és a `migrations/` a projekt részei,
- az SQLite adatbázisfájl viszont éles adat lehet,
- ebben lehetnek Shopify sessionök, install adatok, shop beállítások, widget ID-k.

Ezért frissítéskor:

- a `prisma` mappát ne töröljem vakon,
- az éles `dev.sqlite` / `.sqlite` / `.db` fájlokat ne írjam felül,
- ha bizonytalan vagyok, előbb mentést készítsek róla,
- `build/` törölhető, de a Prisma adatbázis nem.

Gyors ellenőrzés szerveren:

```bash
cd /home/jutasa/public_html/shopify-public.fogyasztobarat.hu
find prisma -name "*.sqlite" -o -name "*.db"
```

Ha talál ilyen fájlt, azt éles adatnak kell tekinteni.

## Windows ZIP készítése feltöltéshez

Ezt a PowerShell parancsot a projekt gyökerében kell futtatni:

```powershell
$pkg="fbarat-app-upload"; Remove-Item $pkg -Recurse -Force -ErrorAction SilentlyContinue; New-Item -ItemType Directory $pkg | Out-Null; Copy-Item app,extensions,prisma,public,docs -Destination $pkg -Recurse; Get-ChildItem "$pkg\prisma" -Recurse -Include *.sqlite,*.db | Remove-Item -Force; Copy-Item package.json,package-lock.json,shopify.app.toml,shopify.web.toml,vite.config.js,tsconfig.json,passenger.cjs,.env -Destination $pkg; Compress-Archive -Path "$pkg\*" -DestinationPath "fbarat-app-upload.zip" -Force
```

Ez létrehozza:

```text
fbarat-app-upload.zip
```

Ezt kell feltölteni cPanel File Managerrel ide:

```text
/home/jutasa/public_html/shopify-public.fogyasztobarat.hu
```

Fontos: a ZIP-ben szándékosan nincs `build` és nincs `node_modules`. Ezeket a szerveren kell létrehozni.

Szintén fontos: a ZIP-készítő parancs a `prisma` mappából kiszedi a `*.sqlite` és `*.db` fájlokat, hogy egy lokális adatbázis véletlenül se írja felül az éles adatbázist.

## Miért ne Windows-on buildeljek élesre?

Volt egy konkrét hiba: a landing oldal betöltött, de a CSS/JS assetek 404-et kaptak.

A böngészőben ilyen hibák voltak:

```text
/assets/route-....css 404
/assets/entry.client-....js 404
/assets/root-....js 404
```

A fájl fizikailag fent volt:

```text
build/client/assets/...
```

A gond az volt, hogy Windows-on készült a build, és a szerver build fájlba Windows útvonal került:

```js
const assetsBuildDirectory = "build\\client";
```

Linux szerveren viszont ez kell:

```js
const assetsBuildDirectory = "build/client";
```

Ezért a biztonságos módszer: a forrást kell feltölteni, és az `npm run build` parancsot az éles Linux szerveren kell futtatni.

## cPanel Node app beállítások

Működő beállítások:

```text
Node.js version: 20.20.0
Application mode: Production
Application root: public_html/shopify-public.fogyasztobarat.hu
Application URL: shopify-public.fogyasztobarat.hu
Startup file: passenger.cjs
Passenger log file: a cPanelben látható public Node app logfájl
```

A jobb oldali extra URL mező maradjon üres.

## passenger.cjs szerepe

A `passenger.cjs` nem parancs, hanem indítófájl.

A cPanel / Passenger ezt használja startup file-ként. Ez indítja el a React Router szervert.

Éles szerveren a tartalma jelenleg ilyen jellegű:

```js
const path = require("path");

const appRoot = __dirname;
process.chdir(appRoot);
process.env.NODE_ENV = process.env.NODE_ENV || "production";

const servePkg = require.resolve("@react-router/serve/package.json");
const serveDir = path.dirname(servePkg);

process.argv = [
  process.argv[0],
  path.join(serveDir, "bin.js"),
  path.join(appRoot, "build/server/index.js"),
];

require(path.join(serveDir, "bin.js"));
```

## Szerveres build és frissítés menete

SSH-ban:

```bash
source /home/jutasa/nodevenv/public_html/shopify-public.fogyasztobarat.hu/20/bin/activate
cd /home/jutasa/public_html/shopify-public.fogyasztobarat.hu
npm install --include=dev
rm -rf build
npm run build
npm run setup
```

Utána cPanelben:

```text
Node.js app restart
```

Ha csak kód változott és a csomagok nem, akkor az `npm install --include=dev` nem mindig kell újra. Tiszta feltöltésnél viszont fusson le.

Frissítéskor ne töröljem a teljes gyökeret vakon. Ezek maradjanak meg:

```text
.htaccess
.well-known/
cgi-bin/
prisma/dev.sqlite vagy bármilyen éles .sqlite/.db adatbázisfájl
```

## Gyors ellenőrzés build után

Ellenőrizni, hogy nem Windows útvonal került-e a buildbe:

```bash
grep -n "assetsBuildDirectory" build/server/index.js
```

Jó Linux szerveres eredmény:

```js
const assetsBuildDirectory = "build/client";
```

Rossz, Windowsról feltöltött buildre utaló eredmény:

```js
const assetsBuildDirectory = "build\\client";
```

Ellenőrizni, hogy a buildelt szerverfájl nem demo fájl-e:

```bash
head -n 20 build/server/index.js
```

Ellenőrizni, hogy az asset fájl tényleg megvan-e:

```bash
ls -la build/client/assets
```

Konkrét asset teszt:

```bash
curl -I https://shopify-public.fogyasztobarat.hu/assets/route-Bqdweacu.css
```

Ha jó, akkor `200 OK` kell.

## npm run setup

Ez nálunk a Prisma miatt kell.

A `package.json` alapján:

```bash
prisma generate && prisma migrate deploy
```

Tehát:

- Prisma kliens generálása,
- adatbázis migrációk futtatása.

## Környezeti változók

cPanelben ezek fontosak:

```text
SHOPIFY_API_KEY
SHOPIFY_API_SECRET
SCOPES
SHOPIFY_APP_URL=https://shopify-public.fogyasztobarat.hu
FB_SHOPIFY_ELIGIBILITY_SECRET
FB_SHOPIFY_POLICY_REFRESH_SECRET
```

Ezeket a cPanel Node app környezeti változói között is érdemes ellenőrizni, nem csak az `.env` fájlban.

## shopify.app.toml fontos részei

Éles szerveres állapotban:

```toml
application_url = "https://shopify-public.fogyasztobarat.hu"

[auth]
redirect_urls = [ "https://shopify-public.fogyasztobarat.hu/auth/callback" ]
```

Ha ezek változnak, akkor általában kell:

```bash
shopify app deploy
```

## Hasznos parancsok

Lokális fejlesztés:

```bash
shopify app dev
```

Shopify konfiguráció deploy:

```bash
shopify app deploy
```

Szerveres Node környezet aktiválása:

```bash
source /home/jutasa/nodevenv/public_html/shopify-public.fogyasztobarat.hu/20/bin/activate
```

Szerveres app mappába belépés:

```bash
cd /home/jutasa/public_html/shopify-public.fogyasztobarat.hu
```

Függőségek telepítése:

```bash
npm install --include=dev
```

Build újragenerálása:

```bash
rm -rf build
npm run build
```

Prisma setup:

```bash
npm run setup
```

Log utolsó 100 sora:

```bash
tail -n 100 /home/jutasa/logs/shopify-app.log
```

Konkrét Passenger hibakód keresése:

```bash
grep -n "ERROR_ID" /home/jutasa/logs/shopify-app.log
```

Auth route teszt:

```bash
curl -I https://shopify-public.fogyasztobarat.hu/auth/login
```

Auth route teszt konkrét shoppal:

```bash
curl -I "https://shopify-public.fogyasztobarat.hu/auth/login?shop=fogyaszto-barat.myshopify.com"
```

Shopify elérés teszt szerverről:

```bash
curl -I https://shopify.com
```

## Ha 1 hónap múlva csak ezt olvasom

- `shopify app dev` = helyi fejlesztés.
- `shopify app deploy` = Shopify oldali config / verzió frissítés.
- Az éles kód a saját szerveren fut.
- Élesre ne Windows buildet töltsek fel.
- Forrást töltsek fel, szerveren futtassam: `npm install --include=dev`, `npm run build`, `npm run setup`.
- Build után restart kell a cPanel Node appon.
- Ha CSS/JS 404 van, első ellenőrzés: `grep -n "assetsBuildDirectory" build/server/index.js`.
- Jó érték Linuxon: `build/client`.
- Rossz érték Windows buildből: `build\\client`.