# Instalare Gata de Plecare Vouchere pe shared hosting cu cPanel

Acest kit este destinat unui cont de shared hosting care oferă **Setup Node.js App / Application Manager**, **Node.js 22**, o bază **MySQL/MariaDB**, SSL și posibilitatea de a rula `npm install`. FTP singur nu poate porni o aplicație Node.js. Dacă în cPanel nu există o funcție pentru aplicații Node.js sau versiunea 22, cere activarea ei furnizorului ori folosește un VPS.

## Ce conține kitul

- aplicația Node.js și interfața PWA;
- `app.cjs`, fișierul de pornire pentru cPanel/Passenger;
- installerul web în 4 pași pentru bază de date, Admin, agenție și SMTP;
- suport MySQL/MariaDB și PostgreSQL;
- ghid, checklist, verificare tehnică și exemple de configurare;
- fără `node_modules`, parole sau date reale de acces.

## 1. Creează adresa aplicației și activează SSL

1. În cPanel deschide **Domains** și creează un subdomeniu, de exemplu `vouchere.gatadeplecare.ro`.
2. Deschide **SSL/TLS Status** și rulează **AutoSSL** dacă certificatul nu este încă activ.
3. Verifică în browser că adresa HTTPS se deschide fără avertisment. HTTPS este obligatoriu pentru camera telefonului și recomandat pentru autentificare.

## 2. Creează baza de date MySQL

1. Deschide **MySQL® Database Wizard**.
2. Creează o bază, de exemplu `vouchere`. cPanel va afișa de obicei numele complet `contcpanel_vouchere`.
3. Creează un utilizator separat, de exemplu `voucherusr`, și generează o parolă lungă.
4. Asociază utilizatorul cu baza și bifează **ALL PRIVILEGES**.
5. Notează exact hostul, portul, numele complet al bazei, utilizatorul complet și parola. Pe majoritatea serverelor cPanel hostul este `localhost`, portul `3306`, iar SSL pentru conexiunea locală rămâne debifat.

## 3. Încarcă fișierele

Varianta recomandată este **File Manager**: încarcă arhiva în `/home/CONT_CPANEL/gata-vouchere` și folosește **Extract**. Directorul aplicației trebuie să conțină direct `app.cjs`, `server.mjs`, `package.json`, `public` și `src`.

Prin FTP, dezarhivează kitul pe calculator și încarcă toate fișierele în mod binar. Activează afișarea fișierelor ascunse pentru a include fișierele care încep cu punct. Nu încărca `node_modules`; dependențele se instalează pe server din cPanel.

Este preferabil ca directorul aplicației să fie în afara `public_html`. Nu încărca niciodată un fișier `data/config.json` provenit de la alt server.

## 4. Creează aplicația Node.js în cPanel

1. Deschide **Setup Node.js App** și apasă **Create Application**.
2. Selectează **Node.js 22** și modul **Production**.
3. La **Application root** scrie `gata-vouchere` fără `/home/CONT_CPANEL/`.
4. La **Application URL** selectează subdomeniul creat.
5. La **Application startup file** scrie `app.cjs`.
6. Creează aplicația și apasă **Run NPM Install**. Dacă ai terminal, poți rula `npm ci --omit=dev` din directorul aplicației.
7. Adaugă în secțiunea **Environment variables**:

   - `APP_URL` = `https://vouchere.domeniul-tau.ro`
   - `TRUST_PROXY` = `1`
   - `COOKIE_SECURE` = `auto`
   - `SESSION_DAYS` = `30`

   Nu seta `PORT`; cPanel/Passenger îl setează automat.

8. Apasă **Restart Application**.

Dacă ai terminal, rulează opțional `npm run cpanel:check`. Trebuie să primești trei mesaje `OK`.

## 5. Rulează installerul web

Deschide `https://vouchere.domeniul-tau.ro/install`. Installerul apare automat cât timp aplicația nu este configurată.

### Pasul 1 — Baza de date

- Motor: **MySQL / MariaDB**;
- Server/Host: de regulă `localhost`;
- Port: `3306`;
- Nume bază: numele complet afișat de cPanel, de exemplu `contcpanel_vouchere`;
- Utilizator: numele complet, de exemplu `contcpanel_voucherusr`;
- Parolă: parola creată în MySQL Database Wizard;
- SSL bază: de regulă debifat pentru `localhost`.

La **Continuă**, installerul testează conexiunea. Nu trece mai departe până nu apare confirmarea verde. Dacă testul eșuează, verifică prefixele cPanel și dacă utilizatorul a fost asociat bazei cu ALL PRIVILEGES.

### Pasul 2 — Administratorul inițial

Completează numele, utilizatorul, e-mailul și o parolă de minimum 10 caractere. Acest cont are drepturi totale. Parola este salvată cu hash bcrypt, nu în clar.

### Pasul 3 — Agenția și SMTP

Completează numele agenției, website-ul, telefonul și adresa. Pentru o căsuță e-mail creată în cPanel, valorile uzuale sunt:

- server SMTP: `mail.domeniul-tau.ro` sau valoarea din **Connect Devices**;
- port `465` cu **SSL/TLS** sau port `587` cu **STARTTLS**;
- utilizator: adresa completă, de exemplu `vouchere@gatadeplecare.ro`;
- parolă: parola căsuței e-mail;
- adresă expeditor: aceeași adresă autorizată de server;
- Reply-To și e-mail notificări: adresele dorite.

Valorile exacte se găsesc în cPanel la **Email Accounts → Connect Devices**. SMTP poate fi completat și ulterior din **Setări → Server SMTP**.

### Pasul 4 — Confirmare

Bifează confirmarea și apasă **Instalează aplicația**. Se creează automat tabelele, contul Admin și configurația privată `data/config.json`. După succes, installerul se blochează și aplicația afișează autentificarea.

## 6. Verificări după instalare

1. Autentifică-te cu administratorul creat.
2. În **Setări**, salvează și testează SMTP.
3. Emite un voucher de test în RON și unul în EUR.
4. Deschide previzualizarea, descarcă PDF/PNG și trimite e-mailul.
5. Pe telefon, acordă permisiunea camerei și scanează codul prin HTTPS.
6. Emite o serie mică și testează arhiva ZIP înainte de o serie mare de 300 de carduri.

## Erori frecvente

- **Nu există Setup Node.js App:** pachetul nu poate rula doar prin FTP/PHP; cere Node.js hostingului sau folosește VPS.
- **Versiune Node prea veche:** selectează Node.js 22 în aplicația cPanel.
- **Cannot find module:** rulează din nou **Run NPM Install**, apoi Restart Application.
- **Eroare DB access denied:** verifică numele cu prefix cPanel, parola și asocierea utilizatorului cu baza.
- **Eroare la crearea tabelelor:** utilizatorul DB nu are ALL PRIVILEGES.
- **Nu se poate salva configurația:** directorul `data` trebuie să poată fi scris de utilizatorul aplicației; recomandat permisiuni `700` sau `750`.
- **Camera nu pornește:** folosește HTTPS, permite camera și repornește PWA-ul.
- **SMTP respins:** folosește valorile din Connect Devices, adresa completă drept utilizator și aceeași adresă la From.
- **Eroare 503:** verifică logul aplicației din Setup Node.js App, apoi Run NPM Install și Restart Application.

## Backup și actualizare

Din cPanel descarcă periodic:

1. exportul bazei din **phpMyAdmin → Export**;
2. fișierul privat `data/config.json`.

La actualizare, fă întâi backup, păstrează `data/config.json`, înlocuiește fișierele aplicației, rulează **Run NPM Install** și apoi **Restart Application**. Nu accesa din nou `/install`; configurația existentă este detectată automat, iar schema bazei este actualizată fără ștergerea voucherelor.