337 lines
9.2 KiB
Markdown
337 lines
9.2 KiB
Markdown
# Variables d'Environnement - lecoffre-front
|
|
|
|
## Vue d'ensemble
|
|
|
|
Ce document détaille toutes les variables d'environnement utilisées dans l'application lecoffre-front, leur utilisation et leur configuration.
|
|
|
|
## Variables d'environnement supportées
|
|
|
|
### 1. Configuration API Backend
|
|
|
|
#### `NEXT_PUBLIC_BACK_API_PROTOCOL`
|
|
- **Description**: Protocole utilisé pour communiquer avec l'API backend
|
|
- **Valeurs possibles**: `https://`, `http://`
|
|
- **Exemple**: `https://`
|
|
- **Utilisation**: Construction des URLs d'API
|
|
|
|
#### `NEXT_PUBLIC_BACK_API_HOST`
|
|
- **Description**: Nom d'hôte de l'API backend
|
|
- **Exemple**: `api.lecoffre.com`, `dev4.4nkweb.com`
|
|
- **Utilisation**: Construction des URLs d'API
|
|
|
|
#### `NEXT_PUBLIC_BACK_API_PORT`
|
|
- **Description**: Port de l'API backend
|
|
- **Exemple**: `443`, `8080`, `3001`
|
|
- **Utilisation**: Construction des URLs d'API
|
|
- **Note**: Peut être vide pour les ports par défaut (80/443)
|
|
|
|
#### `NEXT_PUBLIC_BACK_API_ROOT_URL`
|
|
- **Description**: Chemin racine de l'API
|
|
- **Exemple**: `/api`, `/`
|
|
- **Utilisation**: Construction des URLs d'API
|
|
|
|
#### `NEXT_PUBLIC_BACK_API_VERSION`
|
|
- **Description**: Version de l'API
|
|
- **Exemple**: `v1`, `v2`
|
|
- **Utilisation**: Construction des URLs d'API
|
|
|
|
### 2. Configuration Frontend
|
|
|
|
#### `NEXT_PUBLIC_FRONT_APP_HOST`
|
|
- **Description**: URL de base de l'application frontend
|
|
- **Exemple**: `https://app.lecoffre.com`
|
|
- **Utilisation**: Redirections et liens internes
|
|
|
|
#### `NEXT_PUBLIC_FRONT_APP_PORT`
|
|
- **Description**: Port de l'application frontend
|
|
- **Exemple**: `443`, `3000`
|
|
- **Utilisation**: Construction des URLs frontend
|
|
|
|
### 3. Intégration IDNot (Authentification)
|
|
|
|
#### `NEXT_PUBLIC_IDNOT_AUTHORIZE_ENDPOINT`
|
|
- **Description**: Point d'entrée pour l'autorisation OAuth
|
|
- **Exemple**: `/oauth/authorize`
|
|
- **Utilisation**: Flux d'authentification
|
|
|
|
#### `NEXT_PUBLIC_IDNOT_CLIENT_ID`
|
|
- **Description**: Identifiant client OAuth
|
|
- **Exemple**: `lecoffre-client-id`
|
|
- **Utilisation**: Authentification OAuth
|
|
|
|
#### `NEXT_PUBLIC_IDNOT_BASE_URL`
|
|
- **Description**: URL de base du service IDNot
|
|
- **Exemple**: `https://idnot.lecoffre.com`
|
|
- **Utilisation**: Authentification OAuth
|
|
|
|
#### `NEXT_PUBLIC_IDNOT_REDIRECT_URI`
|
|
- **Description**: URI de redirection après authentification
|
|
- **Exemple**: `https://app.lecoffre.com/callback`
|
|
- **Utilisation**: Flux d'authentification
|
|
|
|
### 4. Intégration Docaposte
|
|
|
|
#### `NEXT_PUBLIC_DOCAPOSTE_API_URL`
|
|
- **Description**: URL de l'API Docaposte
|
|
- **Exemple**: `https://api.docaposte.com`
|
|
- **Utilisation**: Services postaux
|
|
|
|
### 5. Intégration 4NK (Blockchain)
|
|
|
|
#### `NEXT_PUBLIC_4NK_URL`
|
|
- **Description**: URL de base des services 4NK
|
|
- **Exemple**: `https://dev4.4nkweb.com`
|
|
- **Utilisation**: Services blockchain et signature
|
|
|
|
#### `NEXT_PUBLIC_4NK_IFRAME_URL`
|
|
- **Description**: URL spécifique pour l'iframe 4NK
|
|
- **Exemple**: `https://dev4.4nkweb.com`
|
|
- **Utilisation**: Communication iframe
|
|
- **Note**: Peut être différente de `NEXT_PUBLIC_4NK_URL`
|
|
|
|
### 6. Analytics et Monitoring
|
|
|
|
#### `NEXT_PUBLIC_HOTJAR_SITE_ID`
|
|
- **Description**: Identifiant du site Hotjar
|
|
- **Exemple**: `123456`
|
|
- **Utilisation**: Analytics et heatmaps
|
|
|
|
#### `NEXT_PUBLIC_HOTJAR_VERSION`
|
|
- **Description**: Version de Hotjar
|
|
- **Exemple**: `6`
|
|
- **Utilisation**: Analytics et heatmaps
|
|
|
|
### 7. Configuration système
|
|
|
|
#### `NEXT_PUBLIC_API_URL`
|
|
- **Description**: URL générique de l'API
|
|
- **Exemple**: `https://api.lecoffre.com`
|
|
- **Utilisation**: Appels API génériques
|
|
|
|
#### `NEXT_PUBLIC_DEFAULT_VALIDATOR_ID`
|
|
- **Description**: Identifiant du validateur par défaut
|
|
- **Exemple**: `862406317a35064537ac959cb5d8bbdf4f849283b63db3ffa9904de2b3427c43:0`
|
|
- **Utilisation**: Validation des entités système
|
|
- **Valeur par défaut**: Définie dans `AppConstants.ts`
|
|
|
|
#### `NEXT_PUBLIC_DEFAULT_STORAGE_URLS`
|
|
- **Description**: URLs de stockage par défaut (séparées par des virgules)
|
|
- **Exemple**: `https://dev3.4nkweb.com/storage,https://backup.4nkweb.com/storage`
|
|
- **Utilisation**: Stockage des données
|
|
- **Valeur par défaut**: `https://dev3.4nkweb.com/storage`
|
|
|
|
### 8. Variables d'environnement système
|
|
|
|
#### `NEXTJS_APP_ENV_NAME`
|
|
- **Description**: Nom de l'environnement
|
|
- **Valeurs possibles**: `development`, `staging`, `preprod`, `production`
|
|
- **Utilisation**: Sélection de la configuration par environnement
|
|
- **Valeur par défaut**: `development`
|
|
|
|
#### `NODE_ENV`
|
|
- **Description**: Environnement Node.js
|
|
- **Valeurs possibles**: `development`, `production`
|
|
- **Utilisation**: Configuration Next.js
|
|
|
|
## Configuration par environnement
|
|
|
|
### Développement
|
|
```bash
|
|
NEXTJS_APP_ENV_NAME=development
|
|
NODE_ENV=development
|
|
NEXT_PUBLIC_BACK_API_PROTOCOL=http://
|
|
NEXT_PUBLIC_BACK_API_HOST=localhost
|
|
NEXT_PUBLIC_BACK_API_PORT=3001
|
|
NEXT_PUBLIC_4NK_URL=https://dev4.4nkweb.com
|
|
```
|
|
|
|
### Staging
|
|
```bash
|
|
NEXTJS_APP_ENV_NAME=staging
|
|
NODE_ENV=production
|
|
NEXT_PUBLIC_BACK_API_PROTOCOL=https://
|
|
NEXT_PUBLIC_BACK_API_HOST=stg-api.lecoffre.com
|
|
NEXT_PUBLIC_BACK_API_PORT=443
|
|
NEXT_PUBLIC_4NK_URL=https://dev4.4nkweb.com
|
|
```
|
|
|
|
### Production
|
|
```bash
|
|
NEXTJS_APP_ENV_NAME=production
|
|
NODE_ENV=production
|
|
NEXT_PUBLIC_BACK_API_PROTOCOL=https://
|
|
NEXT_PUBLIC_BACK_API_HOST=api.lecoffre.com
|
|
NEXT_PUBLIC_BACK_API_PORT=443
|
|
NEXT_PUBLIC_4NK_URL=https://4nk.lecoffre.com
|
|
```
|
|
|
|
## Utilisation dans le code
|
|
|
|
### Configuration Next.js
|
|
|
|
Les variables sont configurées dans `next.config.js`:
|
|
|
|
```javascript
|
|
const nextConfig = {
|
|
publicRuntimeConfig: {
|
|
NEXT_PUBLIC_BACK_API_PROTOCOL: process.env.NEXT_PUBLIC_BACK_API_PROTOCOL,
|
|
// ... autres variables
|
|
},
|
|
serverRuntimeConfig: {
|
|
// Même configuration pour le serveur
|
|
},
|
|
env: {
|
|
// Configuration pour le build
|
|
}
|
|
};
|
|
```
|
|
|
|
### Initialisation dans l'application
|
|
|
|
Les variables sont initialisées dans `_app.tsx`:
|
|
|
|
```typescript
|
|
const { publicRuntimeConfig } = getConfig();
|
|
|
|
MyApp.getInitialProps = async () => {
|
|
return {
|
|
backApiProtocol: publicRuntimeConfig.NEXT_PUBLIC_BACK_API_PROTOCOL,
|
|
// ... autres variables
|
|
};
|
|
};
|
|
```
|
|
|
|
### Utilisation dans les services
|
|
|
|
```typescript
|
|
// DatabaseService.ts
|
|
private static buildBaseUrl(): string {
|
|
return `${publicRuntimeConfig.NEXT_PUBLIC_BACK_API_PROTOCOL}${publicRuntimeConfig.NEXT_PUBLIC_BACK_API_HOST}:${publicRuntimeConfig.NEXT_PUBLIC_BACK_API_PORT}${publicRuntimeConfig.NEXT_PUBLIC_BACK_API_ROOT_URL}${publicRuntimeConfig.NEXT_PUBLIC_BACK_API_VERSION}`;
|
|
}
|
|
```
|
|
|
|
## Déploiement Docker
|
|
|
|
### Variables de build
|
|
|
|
```dockerfile
|
|
ARG NEXT_PUBLIC_BACK_API_PROTOCOL
|
|
ARG NEXT_PUBLIC_BACK_API_HOST
|
|
# ... autres variables
|
|
```
|
|
|
|
### Variables d'environnement runtime
|
|
|
|
```dockerfile
|
|
ENV NEXT_PUBLIC_BACK_API_PROTOCOL=${NEXT_PUBLIC_BACK_API_PROTOCOL} \
|
|
NEXT_PUBLIC_BACK_API_HOST=${NEXT_PUBLIC_BACK_API_HOST} \
|
|
# ... autres variables
|
|
```
|
|
|
|
### Exécution
|
|
|
|
```bash
|
|
docker run -e NEXT_PUBLIC_BACK_API_PROTOCOL=https:// \
|
|
-e NEXT_PUBLIC_BACK_API_HOST=api.example.com \
|
|
lecoffre/front:latest
|
|
```
|
|
|
|
## Déploiement Kubernetes
|
|
|
|
### Via Vault (recommandé)
|
|
|
|
```yaml
|
|
annotations:
|
|
vault.hashicorp.com/agent-inject: "true"
|
|
vault.hashicorp.com/agent-inject-secret-envs: secret/data/lecoffre-front-stg/config/envs
|
|
vault.hashicorp.com/agent-inject-template-envs: |
|
|
{{ with secret "secret/data/lecoffre-front-stg/config/envs" }}
|
|
{{ range $k, $v := .Data.data }}
|
|
export {{ $k }}="{{ $v }}"
|
|
{{ end }}
|
|
{{ end }}
|
|
```
|
|
|
|
### Via ConfigMap
|
|
|
|
```yaml
|
|
apiVersion: v1
|
|
kind: ConfigMap
|
|
metadata:
|
|
name: lecoffre-front-config
|
|
data:
|
|
NEXT_PUBLIC_BACK_API_PROTOCOL: "https://"
|
|
NEXT_PUBLIC_BACK_API_HOST: "api.example.com"
|
|
# ... autres variables
|
|
```
|
|
|
|
## Validation et tests
|
|
|
|
### Vérification des variables requises
|
|
|
|
```typescript
|
|
const requiredVars = [
|
|
'NEXT_PUBLIC_BACK_API_PROTOCOL',
|
|
'NEXT_PUBLIC_BACK_API_HOST',
|
|
'NEXT_PUBLIC_BACK_API_PORT',
|
|
'NEXT_PUBLIC_BACK_API_ROOT_URL',
|
|
'NEXT_PUBLIC_BACK_API_VERSION'
|
|
];
|
|
|
|
for (const varName of requiredVars) {
|
|
if (!publicRuntimeConfig[varName]) {
|
|
throw new Error(`${varName} is not defined in environment variables`);
|
|
}
|
|
}
|
|
```
|
|
|
|
### Tests d'environnement
|
|
|
|
```bash
|
|
# Vérifier les variables définies
|
|
env | grep NEXT_PUBLIC_
|
|
|
|
# Tester la construction d'URL
|
|
curl -I $(echo $NEXT_PUBLIC_BACK_API_PROTOCOL$NEXT_PUBLIC_BACK_API_HOST:$NEXT_PUBLIC_BACK_API_PORT$NEXT_PUBLIC_BACK_API_ROOT_URL$NEXT_PUBLIC_BACK_API_VERSION/health)
|
|
```
|
|
|
|
## Bonnes pratiques
|
|
|
|
1. **Sécurité**: Ne jamais exposer de secrets dans les variables `NEXT_PUBLIC_*`
|
|
2. **Validation**: Toujours valider la présence des variables requises
|
|
3. **Documentation**: Maintenir la documentation des variables
|
|
4. **Tests**: Tester avec différentes configurations d'environnement
|
|
5. **Fallbacks**: Prévoir des valeurs par défaut quand possible
|
|
|
|
## Dépannage
|
|
|
|
### Variables non définies
|
|
|
|
```bash
|
|
# Vérifier les variables d'environnement
|
|
docker exec -it <container> env | grep NEXT_PUBLIC_
|
|
|
|
# Vérifier la configuration Vault
|
|
vault kv get secret/data/lecoffre-front-stg/config/envs
|
|
```
|
|
|
|
### URLs malformées
|
|
|
|
```bash
|
|
# Tester la construction d'URL
|
|
node -e "
|
|
const config = {
|
|
protocol: process.env.NEXT_PUBLIC_BACK_API_PROTOCOL,
|
|
host: process.env.NEXT_PUBLIC_BACK_API_HOST,
|
|
port: process.env.NEXT_PUBLIC_BACK_API_PORT,
|
|
root: process.env.NEXT_PUBLIC_BACK_API_ROOT_URL,
|
|
version: process.env.NEXT_PUBLIC_BACK_API_VERSION
|
|
};
|
|
console.log(\`\${config.protocol}\${config.host}:\${config.port}\${config.root}\${config.version}\`);
|
|
"
|
|
```
|
|
|
|
---
|
|
|
|
*Documentation mise à jour le $(date) - Variables d'environnement lecoffre-front*
|