DOCUMENTATION.md

Documentation Détaillée - iDeploy Examples Repository

📋 Table des Matières

Vue d'ensemble
Structure du Repository
Configuration iDeploy
Applications Supportées
Guide par Framework
Docker et Containerization
Déploiement
Variables d'Environnement
Guide de Contribution

🎯 Vue d'Ensemble

ideploy-examples est un repository officiel d'iDeploy contenant une collection d'exemples et de templates pour déployer diverses applications et services en utilisant la plateforme iDeploy.

Objectif Principal

Fournir des exemples fonctionnels et prêts à déployer pour les développeurs souhaitant tester ou intégrer leurs applications avec iDeploy.

Technologie de Base

iDeploy : Plateforme open-source de déploiement et d'orchestration
Docker : Containerization des applications
Nixpacks : Alternative à Dockerfile pour le build
Docker Compose : Orchestration multi-conteneurs

📁 Structure du Repository

ideploy-examples/
├── ideploy.json                    # Configuration iDeploy racine
├── README.md                       # Readme principal
├── LICENSE                         # Licence du projet
│
├── 🔵 FRAMEWORKS NODEJS/JavaScript
│ ├── nodejs/                       # Application Node.js simple (Fastify)
│ ├── nestjs/                       # Framework NestJS (TypeScript)
│ ├── nextjs/                       # Framework Next.js avec 3 variantes
│ │  ├── prisma/
│ │  ├── spa/
│ │  ├── spa-standalone/
│ │  ├── spa-with-image-optimization/
│ │  └── ssr/
│ ├── remix/                        # Framework Remix
│ ├── nuxt/                         # Framework Nuxt (Vue.js)
│ ├── t3-app/                       # Create T3 App (TypeScript Stack)
│ ├── t3-nextauth/                  # T3 App avec NextAuth
│ ├── turbo-nextjs/                 # Monorepo avec Turbo & Next.js
│ ├── turbo-t3-nextauth/            # Monorepo avec T3 Stack
│ ├── vite/                         # Vite + React
│ ├── vue/                          # Vue.js
│ ├── astro/                        # Astro (Static/SSR)
│ │  ├── server/
│ │  └── static/
│ └── bun/                          # Runtime Bun (TypeScript)
│
├── 🟢 FRAMEWORKS PYTHON
│ ├── flask/                        # Flask (Python Web)
│ │  ├── app.py
│ │  ├── requirements.txt
│ │  ├── static/
│ │  └── templates/
│
├── 🔴 FRAMEWORKS BACKEND
│ ├── laravel/                      # Laravel (PHP)
│ ├── laravel-inertia/              # Laravel + Inertia.js
│ ├── laravel-pure/                 # Laravel pur
│ ├── symfony/                      # Symfony (PHP)
│ ├── elixir-phoenix/               # Phoenix Framework (Elixir)
│ ├── rails-example/                # Ruby on Rails
│ ├── shopware6/                    # Shopware 6 (E-commerce)
│
├── 🟠 AUTRES LANGAGES
│ ├── rust/                         # Application Rust
│ └── go/                           # Application Go
│      └── gin/                     # Gin framework (Go)
│
├── 🐳 DOCKER & ORCHESTRATION
│ ├── docker-compose/               # Exemples Docker Compose complets
│ │  ├── docker-compose.yaml        # Configuration de base
│ │  ├── docker-compose-deep-parse.yaml
│ │  ├── docker-compose-test.yaml
│ │  ├── Dockerfile                 # Image personnalisée
│ │  ├── index.ts                   # Application TypeScript
│ │  ├── scripts/                   # Scripts utilitaires
│ │  └── package.json
│ ├── docker-compose-caddy/         # Docker Compose avec Caddy
│ │  ├── Caddyfile
│ │  └── docker-compose.yaml
│ └── docker-compose-test/          # Configurations de test
│      ├── docker-compose-cifs.yaml
│      ├── docker-compose-local-volumes.yaml
│      ├── docker-compose-parser.yaml
│      ├── docker-compose-raw.yaml
│      ├── docker-compose-shared-volume.yaml
│      ├── docker-compose-simple.yaml
│      ├── docker-compose-test-new-parser.yaml
│      ├── docker-compose-variable-volume.yaml
│      ├── docker-compose-volume-change.yaml
│      ├── docker-compose-volumes.yaml
│      ├── docker-compose-weird.yaml
│      ├── db/
│      └── empty/
│
├── dockerfile/                     # Exemples avancés Docker
│ ├── ideploy.json
│ ├── Dockerfile
│ ├── apps/
│ └── packages/
│
├── static/                         # Contenu statique
└── strapi/                         # Strapi (CMS Headless)

⚙️ Configuration iDeploy

Fichier `ideploy.json` - Structure Complète

{
  "version": "1.0",
  "name": "test-app",
  "build": {
    "type": "nixpacks",
    "install_command": "npm install",
    "build_command": "npm run build",
    "start_command": "npm start"
  },
  "domains": {
    "ports_exposes": "3000"
  },
  "environment_variables": {
    "production": [
      {"key": "DB_PASSWORD", "value": "SERVICE_PASSWORD_64"},
      {"key": "APP_SECRET", "value": "SERVICE_BASE64_32"}
    ]
  }
}

Paramètres Clés

Paramètre	Type	Description
`version`	string	Version du format ideploy.json
`name`	string	Nom de l'application
`build.type`	string	Type de build : `nixpacks` ou `dockerfile`
`build.install_command`	string	Commande pour installer les dépendances
`build.build_command`	string	Commande pour compiler/builder l'app
`build.start_command`	string	Commande de démarrage
`domains.ports_exposes`	string	Port(s) exposé(s)
`environment_variables`	object	Variables d'environnement par env

Types de Build Supportés

1. Nixpacks

Détection automatique du langage et framework
Pas besoin de Dockerfile
Léger et rapide

"build": {
  "type": "nixpacks",
  "install_command": "npm install",
  "build_command": "npm run build",
  "start_command": "npm start"
}

2. Dockerfile

Contrôle total sur le processus de build
Plus de flexibilité
Plus verbeux

"build": {
  "type": "dockerfile"
}

📦 Applications Supportées

Applications Node.js / TypeScript

1. Node.js Simple

Chemin : nodejs/
Framework : Fastify
Description : Application simple avec Fastify et CORS
Port : 3000

2. NestJS

Chemin : nestjs/
Type : Backend TypeScript robuste
Description : Framework full-featured pour API REST
Scripts :
- npm run build : Compilation
- npm run start : Production
- npm run start:dev : Développement
- npm run test : Tests Jest

3. Next.js

Chemin : nextjs/
Variantes :
- prisma/ : Avec ORM Prisma
- spa/ : Single Page App
- spa-standalone/ : SPA autonome
- spa-with-image-optimization/ : SPA avec optimisation images
- ssr/ : Server-Side Rendering
Description : Framework React complet

4. Remix

Chemin : remix/
Type : Framework React moderne
Description : Full-stack React framework

5. Nuxt

Chemin : nuxt/
Type : Framework Vue.js
Description : Vue.js SSR/SSG framework

6. Vite

Chemin : vite/
Type : Frontend tool
Description : Build tool moderne pour React/Vue

7. Vue.js

Chemin : vue/
Type : Framework frontend
Description : Application Vue.js

8. Astro

Chemin : astro/
Variantes :
- server/ : Astro avec rendu serveur
- static/ : Astro SSG
Description : Static site generator moderne

9. Create T3 App

Chemin : t3-app/ et t3-nextauth/
Stack : TypeScript + Next.js + Tailwind + Prisma + NextAuth
Description : Full-stack opinioné TypeScript

10. Turborepo

Chemin : turbo-nextjs/ et turbo-t3-nextauth/
Type : Monorepo management
Description : Monorepo avec Turborepo

11. Bun

Chemin : bun/
Type : Runtime JavaScript alternatif
Description : Application utilisant le runtime Bun
Features :
- TypeScript natif
- Bundler intégré
- Test runner intégré

Applications Python

Flask

Chemin : flask/
Description : Framework web minimaliste
Structure :
- app.py : Application principale
- requirements.txt : Dépendances Python
- templates/ : Templates HTML
- static/ : Fichiers statiques

Applications PHP

Laravel

Chemin : laravel/, laravel-inertia/, laravel-pure/
Variantes :
- laravel/ : Laravel classique
- laravel-inertia/ : Avec Inertia.js
- laravel-pure/ : Laravel pur
Features : ORM Eloquent, Migrations, Artisan CLI

Symfony

Chemin : symfony/
Description : Framework PHP complet et modulaire

Autres Frameworks

Elixir - Phoenix

Chemin : elixir-phoenix/
Type : Backend Elixir
Description : Framework web Elixir moderne

Ruby on Rails

Chemin : rails-example/
Type : Backend Ruby
Description : Monolithic framework complet

Shopware 6

Chemin : shopware6/
Type : E-commerce
Description : Plateforme e-commerce Shopware

Strapi

Chemin : strapi/
Type : CMS Headless
Description : Headless CMS flexible basé sur Node.js

Applications Compilées

Rust

Chemin : rust/
Description : Application compilée Rust

Go

Chemin : go/
Sous-dossiers :
- gin/ : Framework Gin pour Go
Description : Application compilée Go

📚 Guide par Framework

Node.js + Fastify (nodejs/)

nodejs/
├── index.js              # Point d'entrée
├── package.json          # Dépendances
├── README.md
└── ideploy.json         # Configuration iDeploy

Configuration :

{
  "build": {
    "type": "nixpacks",
    "install_command": "npm install",
    "start_command": "node index.js"
  },
  "domains": {
    "ports_exposes": "3000"
  }
}

NestJS (nestjs/)

nestjs/
├── src/                  # Code source
├── test/                 # Tests
├── package.json
├── tsconfig.json
├── nest-cli.json         # Configuration NestJS CLI
└── README.md

Scripts Importants :

npm run build : Compilation TypeScript
npm run start:dev : Mode développement avec reload
npm run start:prod : Production optimisée
npm run test : Jest tests

Next.js (nextjs/)

Variantes disponibles :

SSR (Server-Side Rendering)

ssr/
├── pages/
├── public/
├── package.json
└── next.config.js

SPA (Single Page App)

spa/
├── pages/
├── public/
└── package.json

Avec Prisma

prisma/
├── pages/
├── prisma/
│  └── schema.prisma
└── package.json

Laravel (laravel/)

laravel/
├── app/                  # Code applicatif
├── config/               # Configuration
├── database/             # Migrations & seeders
├── routes/               # Routes
├── resources/            # Views & assets
├── storage/              # Fichiers générés
├── bootstrap/            # Bootstrap app
├── composer.json         # Dépendances PHP
├── artisan              # CLI Laravel
└── phpunit.xml          # Configuration tests

Commandes Clés :

php artisan migrate       # Exécuter migrations
php artisan serve        # Démarrer le serveur dev
php artisan tinker       # Shell interactif
composer install         # Installer dépendances

Flask (flask/)

flask/
├── app.py               # Application Flask
├── requirements.txt     # Dépendances Python
├── templates/           # Templates Jinja2
├── static/              # Fichiers statiques (CSS, JS)
└── README.md

Dépendances :

flask

Elixir + Phoenix (elixir-phoenix/)

elixir-phoenix/
├── lib/                 # Code applicatif
├── test/                # Tests
├── priv/                # Ressources
├── assets/              # Frontend assets
├── config/              # Configuration
├── mix.exs              # Dépendances Mix
└── README.md

🐳 Docker et Containerization

Docker Compose - Structure

docker-compose/

Contient des configurations Docker Compose complètes :

docker-compose/
├── docker-compose.yaml         # Configuration de base
├── docker-compose-test.yaml    # Configuration de test
├── docker-compose-deep-parse.yaml
├── Dockerfile                  # Image personnalisée
├── index.ts                    # App TypeScript
├── package.json
├── tsconfig.json
└── scripts/                    # Scripts utilitaires

Exemple : docker-compose.yaml

version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    volumes:
      - ./src:/app/src

Docker Compose Test - Configurations Spécialisées

docker-compose-test/

Contient 11 variantes de configuration :

Fichier	Objectif
`docker-compose-simple.yaml`	Configuration minimale
`docker-compose-volumes.yaml`	Gestion des volumes
`docker-compose-local-volumes.yaml`	Volumes locaux
`docker-compose-shared-volume.yaml`	Volumes partagés
`docker-compose-cifs.yaml`	Volumes CIFS/SMB
`docker-compose-variable-volume.yaml`	Volumes avec variables
`docker-compose-volume-change.yaml`	Changements de volumes
`docker-compose-parser.yaml`	Parsing configuration
`docker-compose-raw.yaml`	Configuration brute
`docker-compose-test-new-parser.yaml`	Nouveau parser
`docker-compose-weird.yaml`	Cas limites & edge cases

Docker Compose avec Caddy

docker-compose-caddy/

Intègre Caddy comme reverse proxy :

docker-compose-caddy/
├── docker-compose.yaml
├── Caddyfile           # Configuration Caddy
└── ...

Caddyfile : Configuration du reverse proxy Caddy

example.com {
  reverse_proxy localhost:3000
}

Dockerfile Avancé

dockerfile/

Exemples avancés de Dockerfiles :

dockerfile/
├── Dockerfile          # Dockerfile principal
├── ideploy.json       # Configuration iDeploy
├── apps/              # Applications multi-conteneurs
└── packages/          # Packages/modules

🚀 Déploiement

Processus de Déploiement Général

1. Code Push (Git)
    ↓
2. iDeploy détecte changement
    ↓
3. Build (Nixpacks ou Dockerfile)
    ↓
4. Tests (optionnel)
    ↓
5. Image Docker création
    ↓
6. Container déploiement
    ↓
7. Health check
    ↓
8. Application accessible

Configuration Minimale pour Déployer

Étape 1 : ideploy.json

{
  "version": "1.0",
  "name": "mon-app",
  "build": {
    "type": "nixpacks"
  },
  "domains": {
    "ports_exposes": "3000"
  }
}

Étape 2 : Package.json (Node.js)

{
  "scripts": {
    "start": "node index.js",
    "build": "echo 'Build complete'"
  }
}

Ports et Domaines

"domains": {
  "ports_exposes": "3000"       // Single port
  // ou
  "ports_exposes": "3000,8080"  // Multiple ports
}

Health Checks

iDeploy effectue des vérifications de santé :

HTTP requests sur les ports exposés
Vérification de la réponse 200 OK
Timeout configurable

🔐 Variables d'Environnement

Configuration dans ideploy.json

{
  "environment_variables": {
    "production": [
      {
        "key": "DATABASE_URL",
        "value": "SERVICE_DATABASE_URL"
      },
      {
        "key": "APP_SECRET",
        "value": "SERVICE_BASE64_32"
      }
    ],
    "development": [
      {
        "key": "DEBUG",
        "value": "true"
      }
    ]
  }
}

Variables Spéciales d'iDeploy

Variable	Type	Description
`SERVICE_PASSWORD_64`	string	Mot de passe encodé en base64
`SERVICE_BASE64_32`	string	String aléatoire base64 (32 chars)
`SERVICE_DATABASE_URL`	string	URL de base de données générée
`SERVICE_*`	string	Services liés

Accès aux Variables dans l'Application

Node.js

const dbUrl = process.env.DATABASE_URL;
const secret = process.env.APP_SECRET;

Python

import os
db_url = os.getenv('DATABASE_URL')
secret = os.getenv('APP_SECRET')

PHP / Laravel

$dbUrl = env('DATABASE_URL');
$secret = env('APP_SECRET');

📋 Cas d'Usage Typiques

1. Déployer un API Node.js

Copier nodejs/ comme base
Modifier index.js avec votre logique
Ajouter dépendances à package.json
Configurer ideploy.json
Push vers Git
iDeploy détecte et déploie

2. Déployer un Full-Stack Next.js

Utiliser nextjs/ssr/ comme template
Créer pages dans pages/
Ajouter Prisma si base de données
Configurer variables d'environnement
Déployer via iDeploy

3. Déployer une API Laravel

Utiliser laravel/ comme base
Créer controllers et models
Configurer base de données dans .env
Exécuter migrations : php artisan migrate
Déployer

4. Déployer Docker Compose Multi-Services

Utiliser docker-compose/ comme base
Configurer services dans docker-compose.yaml
Définir volumes et networks
iDeploy exécute docker-compose up
Services accessible via domaines

🔧 Installation et Utilisation Locale

Prérequis

Git
Docker & Docker Compose
Node.js 18+ (pour Node.js apps)
Python 3.8+ (pour Flask)
PHP 8.1+ (pour Laravel)
Docker (pour tous)

Utilisation Générale

# Cloner le repository
git clone https://github.com/coollabs/ideploy-examples.git
cd ideploy-examples

# Entrer dans le dossier de l'app
cd nodejs

# Installer dépendances
npm install

# Démarrer localement
npm start

Utilisation avec Docker

cd docker-compose

# Afficher les services
docker-compose config

# Démarrer les services
docker-compose up

# Voir les logs
docker-compose logs -f

# Arrêter les services
docker-compose down

🌍 Exemples de Production

Configuration Production - Node.js

{
  "version": "1.0",
  "name": "api-production",
  "build": {
    "type": "nixpacks",
    "install_command": "npm install --production",
    "build_command": "npm run build",
    "start_command": "npm run start:prod"
  },
  "domains": {
    "ports_exposes": "3000"
  },
  "environment_variables": {
    "production": [
      {
        "key": "NODE_ENV",
        "value": "production"
      },
      {
        "key": "LOG_LEVEL",
        "value": "error"
      },
      {
        "key": "DATABASE_URL",
        "value": "SERVICE_DATABASE_URL"
      }
    ]
  }
}

Configuration Production - Laravel

{
  "version": "1.0",
  "name": "laravel-production",
  "build": {
    "type": "nixpacks",
    "install_command": "composer install --no-dev",
    "build_command": "php artisan optimize",
    "start_command": "php artisan serve"
  },
  "domains": {
    "ports_exposes": "8000"
  },
  "environment_variables": {
    "production": [
      {
        "key": "APP_ENV",
        "value": "production"
      },
      {
        "key": "APP_DEBUG",
        "value": "false"
      },
      {
        "key": "APP_KEY",
        "value": "SERVICE_BASE64_32"
      }
    ]
  }
}

📖 Lexique et Concepts

Terme	Explication
iDeploy	Plateforme de déploiement open-source
Nixpacks	Build system qui détecte framework automatiquement
Docker	Containerization technology
Docker Compose	Orchestration multi-conteneurs
Framework	Structure de développement
SSR	Server-Side Rendering
SPA	Single Page Application
ORM	Object-Relational Mapping
Headless CMS	CMS sans frontend intégré
Monorepo	Repository avec plusieurs projets
Health Check	Vérification que l'app fonctionne
Reverse Proxy	Proxy qui redirige requêtes

📚 Ressources Supplémentaires

Documentation Officielle

Frameworks

Outils

🤝 Guide de Contribution

Ajouter un Nouvel Exemple

Créer un dossier : mkdir my-framework
Ajouter ideploy.json :

{
  "version": "1.0",
  "name": "my-app",
  "build": {
    "type": "nixpacks"
  }
}

Ajouter README.md avec instructions
Tester localement avec iDeploy
Créer Pull Request

Standards

✅ Chaque exemple doit fonctionner indépendamment
✅ Inclure un README.md explicatif
✅ Inclure ideploy.json valide
✅ Exclure node_modules, vendor, etc. (.gitignore)
✅ Utiliser les meilleures pratiques du framework
✅ Tester sur une instance iDeploy

📝 License

Voir le fichier LICENSE dans le repository.

Dernière mise à jour : Janvier 2026
Version : 1.0
Repository : ideploy-examples

FilesExpand file tree

DOCUMENTATION.md

Latest commit

History

DOCUMENTATION.md

File metadata and controls

Documentation Détaillée - iDeploy Examples Repository

📋 Table des Matières

🎯 Vue d'Ensemble

Objectif Principal

Technologie de Base

📁 Structure du Repository

⚙️ Configuration iDeploy

Fichier ideploy.json - Structure Complète

Paramètres Clés

Types de Build Supportés

1. Nixpacks

2. Dockerfile

📦 Applications Supportées

Applications Node.js / TypeScript

1. Node.js Simple

2. NestJS

3. Next.js

4. Remix

5. Nuxt

6. Vite

7. Vue.js

8. Astro

9. Create T3 App

10. Turborepo

11. Bun

Applications Python

Flask

Applications PHP

Laravel

Symfony

Autres Frameworks

Elixir - Phoenix

Ruby on Rails

Shopware 6

Strapi

Applications Compilées

Rust

Go

📚 Guide par Framework

Node.js + Fastify (nodejs/)

NestJS (nestjs/)

Next.js (nextjs/)

Laravel (laravel/)

Flask (flask/)

Elixir + Phoenix (elixir-phoenix/)

🐳 Docker et Containerization

Docker Compose - Structure

docker-compose/

Exemple : docker-compose.yaml

Docker Compose Test - Configurations Spécialisées

docker-compose-test/

Docker Compose avec Caddy

docker-compose-caddy/

Dockerfile Avancé

dockerfile/

🚀 Déploiement

Processus de Déploiement Général

Configuration Minimale pour Déployer

Étape 1 : ideploy.json

Étape 2 : Package.json (Node.js)

Ports et Domaines

Health Checks

🔐 Variables d'Environnement

Configuration dans ideploy.json

Variables Spéciales d'iDeploy

Accès aux Variables dans l'Application

Node.js

Python

PHP / Laravel

📋 Cas d'Usage Typiques

1. Déployer un API Node.js

2. Déployer un Full-Stack Next.js

3. Déployer une API Laravel

4. Déployer Docker Compose Multi-Services

Fichier `ideploy.json` - Structure Complète