Vitepress

logo vitepress

Introduction à Vitepress

VitePress est un générateur de site statique rapide, minimaliste et optimisé pour la création de documentations techniques et de sites légers.
Basé sur Vite, un framework JavaScript pour construire des interfaces utilisateur et Vue.js,un outil de développement front-end, souvent utilisé pour des projets qui utilisent Vue.js

Déployer VitePress avec Docker et Nginx

Dans ce guide, nous expliquons comment déployer VitePress dans un conteneur Docker et le configurer pour qu’il soit accessible via un reverse proxy Nginx.

Installer npm

sudo apt update
sudo apt install npm

Créez un projet VitePress

mkdir vitepress-demo
cd vitepress-demo
npx vitepress init

Nous pouvons faire la première configuration de notre site :

vitepress init

  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  Vitepress DEMO
│
◇  Site description:
│  Demo
│
◇  Theme:
│  Default Theme
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◆  Add VitePress npm scripts to package.json?
│  ● Yes / ○ No
|
└  Done! Now run npm run docs:dev and start writing.

Cela va nous créer des fichiers dans vitepress-demo:

├── vitepress-demo
│   ├── docs
│   │   ├── api-examples.md
│   │   ├── index.md
│   │   └── markdown-examples.md
│   └── package.json

Modification du fichier `package.json`

Rajouter --host

   "docs:dev": "vitepress dev docs --host",

Par défaut, le serveur est souvent limité à localhost, ce qui signifie qu’il n’est accessible que depuis la machine où il s’exécute. L’option --host permet de lever cette restriction.

Configurer Docker pour VitePress sans nginx

Nous allons créer un fichier docker-compose.yml

docker-compose.yml


services:
  vitepress:
    image: node:23
    container_name: vitepress-demo
    working_dir: /app
    volumes:
      - ./:/app
      - /app/node_modules
    command: >
      sh -c "npm install && npm run docs:dev -- --host 0.0.0.0"
    environment:
      - NODE_ENV=development
    restart: unless-stopped
    ports:
      - "4500:5173"

Notre conteneur est maintenant prêt ! docker compose up -d
screen vitepress

Ajout d’un proxy nginx

Nous allons ajouter un second conteneur dans notre docker-compose.yml et modifier le conteneur vitepress afin que seul notre proxy puisse y accéder:

docker-compose.yml

services:
  vitepress:
    image: node:23
    container_name: vitepress-demo
    working_dir: /app
    volumes:
      - ./:/app
      - /app/node_modules
    command: >
      sh -c "npm install && npm run docs:dev -- --host 0.0.0.0"
    environment:
      - NODE_ENV=development
    restart: unless-stopped
    networks:
      - backend  # Réseau privé interne Docker
    expose:
      - "5173"  # Le port 5173 est exposé uniquement aux autres services du même réseau (Nginx)

  nginx:
    image: nginx:1.27
    container_name: proxy-vitepress-demo
    depends_on:
      - vitepress
    ports:
      - "8080:80"  # Le proxy écoute sur le port 80 pour les connexions externes
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./error.html:/usr/share/nginx/html/error.html:ro
    restart: unless-stopped
    networks:
      - backend  # Nginx est aussi dans le même réseau privé

networks:
  backend:
    driver: bridge  # Réseau privé Docker, accessible uniquement par les conteneurs du même réseau

Configuration nginx

Dans le conteneur nginx, 2 volumes sont montés comprenant le fichier de configuration de nginx et la page html d’erreur.

    volumes:   
      - ./nginx.conf:/etc/nginx/nginx.conf:ro   
      - ./error.html:/usr/share/nginx/html/error.html:ro

Nous allons donc créer ces deux fichiers:

nginx.conf:

nginx.conf

events {}

http {
    server {
        listen 80;
        server_name localhost;

        # Redirection vers VitePress
        location / {
            proxy_pass http://vitepress:5173;  # Redirige vers le conteneur VitePress
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection 'upgrade';
            proxy_set_header Host $host;
            proxy_cache_bypass $http_upgrade;
        }

        # Page d'erreur personnalisée
        error_page 502 503 504 /error.html;

        location = /error.html {
            root /usr/share/nginx/html;  # Assurez-vous que error.html est à cet endroit
            internal;
        }
    }
}

Cette configuration Nginx permet de rediriger toutes les requêtes venant de l’URL racine (/) vers le service VitePress . Elle configure également la gestion de WebSockets et d’autres comportements spécifiques du protocole HTTP.

error.html :

Note

page généré par IA mais sans css pour alléger le tutoriel

error.html

<!DOCTYPE html>
<html lang="fr">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Site Indisponible</title>
</head>
<body>
    <div class="content">
        <div class="emoji">🤷‍♂️🤦‍♂️</div>
        <h1>Flûte !</h1>
        <p>Le site n'est pas disponible pour le moment.</p>
        <footer>
            <p>Revenez plus tard...</p>
        </footer>
    </div>
</body>
</html>

Cette page error.htmlpermet de gérer les erreurs côté serveur, telles que des erreurs 500 (erreur interne du serveur).

Notre arborescence ressemble désormais à ça:

.
├── docker-compose.yml
├── docs
│   ├── api-examples.md
│   ├── index.md
│   └── markdown-examples.md
├── error.html
├── nginx.conf
├── node_modules
├── package.json
└── package-lock.json

Tout est prêt ! docker compose up -d Voyons ce que ça donne: screen vitepress
Notre site est maintenant accessible via le port 8080 et non plus par le port 4500, nous utilison le proxy,

Arrêtons le conteneur vitepress: docker stop vitepress-demo

screen vitepress

Notre page error.htmls’affiche bien

Conclusion

Dans ce tutoriel, nous avons vu comment mettre en place VitePress dans un environnement conteneurisé avec Docker et Nginx. Vous êtes désormais prêt à créer votre site statique de documentation.