> ## Documentation Index
> Fetch the complete documentation index at: https://infra-docs.kaeyros.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Dockerfile gabarit pour les frontends (Next.js et Vite)

> Deux gabarits Docker pour les frontends Kaeyros : Next.js SSR avec runtime Node.js, et SPA statique servie par nginx avec fallback vers index.html.

Les applications frontend chez Kaeyros Analytics utilisent principalement Next.js (avec SSR) ou Vite (SPA statique). Chaque technologie requiert un pattern Docker distinct : Next.js nécessite un runtime Node.js tandis qu'une SPA Vite peut être servie directement par nginx après export statique.

## Variante 1 : Next.js avec SSR

Pour les applications Next.js utilisant le rendu côté serveur, l'API routes ou le middleware, un runtime Node.js est obligatoire.

```dockerfile Dockerfile.nextjs theme={null}
# syntax=docker/dockerfile:1

# ============================================
# Stage 1 : Build
# ============================================
FROM node:20-alpine AS build
WORKDIR /app

# Variables d'environnement publiques injectées au build
ARG NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}

COPY package.json package-lock.json ./
RUN npm ci --ignore-scripts

COPY . .
RUN npm run build

# ============================================
# Stage 2 : Production runtime
# ============================================
FROM node:20-alpine AS production
WORKDIR /app

ENV NODE_ENV=production
ENV PORT=3000

# Utilisateur non-root
RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 nextjs

# Copie des artefacts nécessaires au runtime Next.js
COPY --from=build --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=build --chown=nextjs:nodejs /app/.next/static ./.next/static
COPY --from=build --chown=nextjs:nodejs /app/public ./public

USER nextjs

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD node -e "require('http').get('http://localhost:3000/api/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"

CMD ["node", "server.js"]
```

### Configuration requise pour Next.js

Dans votre `next.config.js` :

```javascript next.config.js theme={null}
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
  // Les variables NEXT_PUBLIC_* sont inlined au build
  env: {
    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
  },
}

module.exports = nextConfig
```

> [!WARNING]
>
> Les variables `NEXT_PUBLIC_*` sont **inlinées au moment du build**. Elles ne peuvent pas être changées au runtime. Assurez-vous de les passer en `ARG`/`ENV` dans le stage build du Dockerfile.

## Variante 2 : SPA Vite avec nginx

Pour les applications Vite (React, Vue, Svelte) exportées en statique, nginx est le serveur optimal : léger, rapide et éprouvé en production.

```dockerfile Dockerfile.vite theme={null}
# syntax=docker/dockerfile:1

# ============================================
# Stage 1 : Build
# ============================================
FROM node:20-alpine AS build
WORKDIR /app

# Variables publiques injectées au build
ARG VITE_API_URL
ENV VITE_API_URL=${VITE_API_URL}

COPY package.json package-lock.json ./
RUN npm ci --ignore-scripts

COPY . .
RUN npm run build

# ============================================
# Stage 2 : Serveur nginx
# ============================================
FROM nginx:1.27-alpine AS production

# Configuration nginx pour SPA
COPY nginx.conf /etc/nginx/conf.d/default.conf

# Copie des fichiers statiques
COPY --from=build /app/dist /usr/share/nginx/html

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]
```

### Configuration nginx pour SPA

```nginx nginx.conf theme={null}
server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;

    # Gzip compression
    gzip on;
    gzip_types text/plain text/css application/javascript application/json image/svg+xml;

    # Cache agressif pour les assets hashés
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Fallback SPA : toute route non trouvée renvoie index.html
    location / {
        try_files $uri $uri/ /index.html;
    }

    # Healthcheck simple
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }
}
```

## Comparaison des deux approches

| Critère | Next.js SSR | SPA Vite + nginx |
| - | - | - |
| Runtime requis | Node.js | Non (nginx uniquement) |
| Taille d'image | \~200 Mo | \~25 Mo |
| SSR / API routes | Oui | Non |
| ISR | Supporté | Non applicable |
| Temps de démarrage | Quelques secondes | Instantané |
| Fallback routing | Géré par Next.js | `try_files` nginx |

## Variables d'environnement publiques

**Next.js**

Toute variable préfixée par `NEXT_PUBLIC_` est exposée au navigateur. Exemples :

* `NEXT_PUBLIC_API_URL`
* `NEXT_PUBLIC_APP_NAME`
* `NEXT_PUBLIC_SENTRY_DSN`

**Vite**

Toute variable préfixée par `VITE_` est exposée au navigateur. Exemples :

* `VITE_API_URL`
* `VITE_APP_TITLE`
* `VITE_MAPBOX_TOKEN`

> [!NOTE]
>
> Les variables sensibles (clés API backend, tokens de service) ne doivent **jamais** utiliser le préfixe public. Elles sont injectées côté serveur ou stockées dans Vault.

## Checklist de validation

**1. Vérifier le build local**

Exécutez `npm run build` en local avant de containeriser. Résolvez toutes les erreurs de compilation.

**2. Tester l'image Docker**

```bash theme={null}
docker build -t mon-frontend:test .
docker run -p 3000:3000 mon-frontend:test  # Next.js
# ou
docker run -p 8080:80 mon-frontend:test    # Vite
```

**3. Valider le routing**

Pour les SPA, accédez directement à une sous-route (ex: `/dashboard`) et vérifiez que la page se charge sans erreur 404.

**4. Vérifier les variables publiques**

Inspectez le source dans le navigateur et confirmez que les valeurs `NEXT_PUBLIC_*` ou `VITE_*` sont correctement substituées.

> [!TIP]
>
> Pour les frontends Next.js utilisant uniquement des pages statiques (pas de SSR, pas d'API routes), vous pouvez opter pour `output: 'export'` et servir avec nginx comme une SPA Vite. Cela réduit considérablement la complexité et la taille de l'image.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.