Vai al contenuto principale

Variabili d'ambiente

Ogni progetto ChurchApps utilizza un file .env per la configurazione locale. Ogni progetto include un file di esempio che copi e personalizzi. Questa pagina descrive le variabili d'ambiente per API, app web e app mobili, incluso come scegliere tra la destinazione demo e quella locale.

Prima di iniziare

  • Installa i prerequisiti per il progetto che ti interessa
  • Clona il repository del progetto su cui vuoi lavorare
  • Consulta la Panoramica del progetto per capire di quali moduli API ha bisogno il tuo progetto

Schema generale​

  1. Cerca dotenv.sample.txt o .env.sample nella radice del progetto.
  2. Copialo come .env.
  3. Modifica i valori secondo necessità.
# Esempio per un progetto con .env.sample
cp .env.sample .env

# Esempio per un progetto con dotenv.sample.txt
cp dotenv.sample.txt .env
Avviso

Non committare mai i file .env nel controllo di versione. Contengono dati sensibili come credenziali del database, chiavi API e segreti JWT. Tutti i progetti ChurchApps includono .env nel file .gitignore, ma verifica sempre prima di committare.

Scegliere la destinazione API​

La decisione più importante riguarda l'indirizzo a cui il frontend invia le chiamate API. Le opzioni sono due:

Opzione 1: API demo (consigliata per lo sviluppo frontend)​

Usa l'ambiente demo condiviso. Non è necessario configurare un'API o un database in locale. Esegue l'ultima versione del codice da main, e i dati di esempio vengono ricaricati ogni notte.

# Schema dell'URL di base
https://api.demo.churchapps.org/{module}

# Esempi di URL dei moduli
https://api.demo.churchapps.org/membership
https://api.demo.churchapps.org/attendance
https://api.demo.churchapps.org/content
https://api.demo.churchapps.org/giving
https://api.demo.churchapps.org/messaging
https://api.demo.churchapps.org/doing
Avviso

L'ambiente di staging (api.staging.churchapps.org, api.staging.lessons.church e gli host correlati) è stato dismesso. Alcuni file .env di esempio potrebbero contenere ancora URL di staging; sostituiscili con i valori demo o locali indicati in questa pagina. Non esiste un'API Lessons condivisa per ambienti non di produzione: esegui LessonsApi in locale (ascolta sulla porta 8090) quando ne hai bisogno.

Opzione 2: API locale​

Esegui il progetto Api sulla tua macchina. Richiede MySQL 8.0+ con i database creati per ciascun modulo. Consulta la guida configurazione locale dell'API.

# Schema dell'URL di base
http://localhost:8084/{module}

# Esempi di URL dei moduli
http://localhost:8084/membership
http://localhost:8084/attendance
http://localhost:8084/content
http://localhost:8084/giving
http://localhost:8084/messaging
http://localhost:8084/doing

Variabili d'ambiente dell'API​

Il progetto Api principale (.env.sample) ha la configurazione più articolata. Ecco le variabili principali:

Impostazioni comuni​

VariabileDescrizioneEsempio
ENVIRONMENTAmbiente di esecuzionedev
SERVER_PORTPorta HTTP per il server di sviluppo locale8084
ENCRYPTION_KEYChiave di cifratura a 192 bit per i dati sensibiliaSecretKeyOfExactly192BitsLength
JWT_SECRETSegreto per la firma dei JSON Web Tokenjwt-secret-dev
FILE_STOREDove archiviare i file caricati (disk o s3)disk
CORS_ORIGINOrigini CORS consentite (* per lo sviluppo locale)*

Connessione al database​

Un unico URL di base indirizza l'API verso MySQL. L'API ricava da questa base un database per modulo (/membership, /attendance, /content, /giving, /messaging, /doing, /reporting).

VariabileEsempio
API_DATABASE_URLmysql://root:password@localhost:3306
Suggerimento

Sostituisci root:password con le tue credenziali MySQL effettive. Ogni database per modulo deve esistere prima di avviare l'API. Usa npm run initdb per creare lo schema di tutti i moduli, oppure npm run initdb:membership per un singolo modulo.

Impostazioni WebSocket​

VariabileDescrizioneEsempio
SOCKET_PORTPorta del server WebSocket8087
SOCKET_URLURL WebSocket a cui si connettono i clientws://localhost:8087

Variabili d'ambiente delle app web​

B1Admin (React + Vite)​

File di esempio: .env.sample

VariabileDescrizioneEsempio (Demo)
REACT_APP_STAGENome dell'ambientedemo
PORTPorta del server di sviluppo3101
REACT_APP_API_BASEUnico URL di base per tutte le API ChurchApps (/membership, /attendance, /content, /giving, /messaging, /doing, /reporting vengono aggiunti automaticamente)https://api.demo.churchapps.org
REACT_APP_CONTENT_ROOTURL di distribuzione dei contenutihttps://democontent.churchapps.org
REACT_APP_GOOGLE_ANALYTICSID di Google Analytics (facoltativo)UA-123456789-1

Per lo sviluppo con API locale, punta l'URL di base al tuo stack locale:

REACT_APP_API_BASE=http://localhost:8084

B1App (Next.js)​

File di esempio: .env.sample

VariabileDescrizioneEsempio (Demo)
NEXT_PUBLIC_API_BASEUnico URL di base per tutte le API ChurchApps (/membership, /attendance, /content, /giving, /messaging, /doing, /reporting vengono aggiunti automaticamente)https://api.demo.churchapps.org
NEXT_PUBLIC_CONTENT_ROOTURL di distribuzione dei contenutihttps://democontent.churchapps.org
NEXT_PUBLIC_GOOGLE_ANALYTICSID di Google Analytics (facoltativo)UA-123456789-1
Info

Next.js richiede il prefisso NEXT_PUBLIC_ per ogni variabile d'ambiente che deve essere disponibile nel browser. Le variabili utilizzate solo lato server non necessitano di questo prefisso.

LessonsApp (Next.js)​

File di esempio: dotenv.sample.txt

VariabileDescrizioneEsempio (LessonsApi locale)
STAGEStage dell'ambiente (lasciala non impostata o imposta dev per lo sviluppo locale)dev
NEXT_PUBLIC_LESSONS_APIURL dell'API Lessonshttp://localhost:8090
NEXT_PUBLIC_CONTENT_ROOTURL di distribuzione dei contenutihttp://localhost:8090/content
NEXT_PUBLIC_API_BASEBase dell'API ChurchApps usata per l'accesso (considerata solo quando STAGE non è impostata o è dev)https://api.demo.churchapps.org

Variabili d'ambiente delle app mobili​

B1Checkin (React Native / Expo)​

File di esempio: dotenv.sample.txt

VariabileDescrizioneEsempio
EXPO_PUBLIC_STAGESeleziona l'insieme di API a cui si connette l'app: dev (API locale su http://127.0.0.1:8084), staging oppure prod (il valore predefinito se non impostata)dev

B1Checkin utilizza solo i moduli API Membership e Attendance, oltre all'URL di distribuzione dei contenuti; i loro indirizzi per ciascun stage sono impostati in src/helpers/EnvironmentHelper.ts.

Info

Expo include nel bundle dell'app solo le variabili con il prefisso EXPO_PUBLIC_. Riavvia il server di sviluppo con yarn start --reset-cache dopo aver modificato .env.


Riferimento rapido: posizione dei file di esempio​

ProgettoFile di esempio
Api.env.sample
B1Admin.env.sample
B1App.env.sample
B1Checkindotenv.sample.txt
LessonsAppdotenv.sample.txt
AskApidotenv.sample.txt