Guida Installazione — Documentazione RICEVUTE

Installazione e Deploy

Questa guida descrive i passi per installare, configurare e mettere in produzione l'applicazione RICEVUTE in un ambiente LAMP (Linux, Apache/Nginx, PHP, MariaDB/MySQL).

Requisiti Minimi

Server: Linux (Debian/Ubuntu consigliati) o NAS con supporto PHP+MySQL
PHP: 8.0+ con estensioni: pdo_mysql, mbstring, json, openssl
Web Server: Apache o Nginx
Database: MariaDB / MySQL (10.x consigliato)
Stampa: CUPS (opzionale, per stampa comande)
Accesso: SSH per configurazioni e installazioni

1. Clonare il Repository

git clone https://github.com/AlexMaina05/RICEVUTE.git
cd RICEVUTE

2. Configurazione Database

Creare il Database e l'Utente

mysql -u root -p
CREATE DATABASE ristorante_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'app_user'@'localhost' IDENTIFIED BY 'strong_password';
GRANT ALL PRIVILEGES ON ristorante_db.* TO 'app_user'@'localhost';
FLUSH PRIVILEGES;

Importare lo Schema

mysql -u app_user -p ristorante_db < sql/schema.sql

Note sullo Schema

Assicurati che i campi stringa usino utf8mb4
Per indici unici su VARCHAR lunghi usa VARCHAR(191) se il server ha limiti
Se le tabelle hanno vincoli NOT NULL senza seed, inserisci i record minimi

3. Seed Iniziali (Obbligatori)

Se lo schema non inserisce dati iniziali, crea almeno:

1 o più categorie in CATEGORIE
1 reparto in REPARTI (impostare Nome_Stampante_LAN valido)
1 o più tavoli in TAVOLI (o opzione ASPORTO)
Alcuni PRODOTTI correlati a categorie/reparti

Puoi usare phpMyAdmin o INSERT SQL diretti.

4. Configurazione Connessione Database

Modifica il file config/db_connection.php con le tue credenziali:

$servername = getenv('DB_HOST') ?: 'localhost';
$username = getenv('DB_USER') ?: 'app_user';
$password = getenv('DB_PASS') ?: 'strong_password';
$dbname = getenv('DB_NAME') ?: 'ristorante_db';

Consiglio: Mantieni le credenziali fuori dal repository usando variabili d'ambiente.

5. Impostazioni PHP e Webserver

Estensioni PHP Richieste

pdo_mysql
mbstring
json
openssl

Verifica php.ini

memory_limit = 128M
max_execution_time = 60

Permessi

Se exec/shell_exec è disabilitato in disable_functions, la stampa via lp da PHP non funzionerà. Puoi eseguire la stampa tramite worker CLI.

Virtual Host

Configura Apache o Nginx puntando alla cartella del progetto. Per maggiore sicurezza, punta la document root a /path/to/RICEVUTE/public.

6. Configurazione CUPS e Stampanti

Installazione CUPS

sudo apt install cups

Configurazione Stampanti

Accedi a http://localhost:631
Aggiungi le stampanti (rete o locali)
Assicurati che REPARTI.Nome_Stampante_LAN corrisponda al nome della coda CUPS

Test Stampa

echo "test" > /tmp/test_print.txt
lp -d nome_queue /tmp/test_print.txt

Permessi Utente

sudo usermod -aG lpadmin www-data

7. Worker per Processare Comande

Test Manuale

php scripts/worker_process_comande.php --limit=10 --max-tries=5

Opzione 1: Cron (ogni minuto)

* * * * * /usr/bin/php /percorso/REPO/scripts/worker_process_comande.php --limit=20 --max-tries=5 >> /var/log/comande_worker.log 2>&1

Opzione 2: Systemd Timer (Raccomandato)

Crea unità .service e .timer (verifica paths e utente):

sudo systemctl daemon-reload
sudo systemctl enable --now worker_comande.timer
systemctl status worker_comande.service
journalctl -u worker_comande.service -f

8. Test End-to-End

Endpoint Principali

GET api/cerca_prodotto.php?codice=CODICE - Cerca prodotto
GET api/genera_report.php?data=YYYY-MM-DD - Genera report
POST api/salva_ordine.php - Salva ordine
POST api/ripeti_comanda.php - Ripeti comanda

Esempi Curl

# Cerca prodotto
curl -s "http://localhost/api/cerca_prodotto.php?codice=PZ01" | jq

# Salva ordine
curl -s -X POST "http://localhost/api/salva_ordine.php" \
  -H 'Content-Type: application/json' \
  -d '{
    "nome_cliente":"Mario",
    "id_tavolo":1,
    "numero_coperti":2,
    "totale":12.50,
    "dettagli":[
      {"id_prodotto":1,"quantita":2,"prezzo_unitario":3.5}
    ]
  }' | jq

9. Backup e Manutenzione

Esegui mysqldump regolarmente e archivia in posizione sicura
Configura rotazione log (logrotate) per /var/log/comande_worker.log
Verifica i log di systemd via journalctl per problemi worker

10. Sicurezza e Hardening

❌ Non committare credenziali in repo; usa .env e .gitignore
🔒 Servi il sito via HTTPS (Let's Encrypt)
🛡️ Proteggi le pagine admin con sessione e password hash
🍪 Configura cookie sessioni: secure, httponly, samesite
🔐 Proteggi azioni critiche con CSRF token
📁 Limita l'accesso a cartelle sensibili e disabilita directory listing

Troubleshooting Comune

500 API Error

Controlla i log PHP e il file config/db_connection.php

Worker Non Stampa

Esegui manualmente lp -d queue /tmp/file e verifica permessi utente

Problemi Charset

Assicurati che DB e pagine PHP usino utf8mb4

Comande Rimangono in 'pending'

Verifica configurazione CUPS e permessi stampante. Consulta la documentazione completa in docs/INSTALL.md sezione 11.

⚙️ Guida Installazione