feat(init): first commit

2023-06-05 15:24:42 +02:00
parent 1ee84e57a5
commit b13a5e892f
37 changed files with 926 additions and 2 deletions
--- a/docs/README.md
+++ b/docs/README.md
@ -0,0 +1,13 @@
+# Documentation
+
+## Tutoriels
+
+- [Créer une image pour votre projet Symfony](./docker-usage.md)
+- [Utilisation avec Kubernetes](./kubernetes-usage.md)
+- [Créer une application avec docker-compose](./starting-with-docker-compose.md)
+
+## Comment faire pour ... ?
+
+- [Installer des paquets supplémentaires](./additional-packages.md)
+- [Contextualiser la configuration](./configuration-contextualization.md)
+- [Utiliser une version spécifique de NodeJS](./customize_nodejs_version.md)
--- a/docs/additional-packages.md
+++ b/docs/additional-packages.md
@ -0,0 +1,12 @@
+# Installer des paquets supplémentaires
+
+Vous pouvez spécifier des paquets supplémentaires (par exemple des dépendances PHP) en ajoutant l'argument de construction `ADDITIONAL_PACKAGES`.
+
+**Exemple**
+
+```
+docker build \
+    -t my-symfony-app:latest \
+    --build-arg "ADDITIONAL_PACKAGES=vim=9.0.0999-r0 curl=7.87.0-r0" \
+    .
+```
--- a/docs/configuration-contextualization.md
+++ b/docs/configuration-contextualization.md
@ -0,0 +1,19 @@
+# Contextualisation la configuration
+
+Les images intègrent l'utilitaire [`gomplate`](https://docs.gomplate.ca/) par défaut.
+
+Ce dernier est utilisé au démarrage du conteneur afin de compléter les fichiers prévus à cet effet avec les données de contexte. Cette opération est réalisée par le script [`files/common/scripts/run.sh`](../files/common/scripts/run.sh).
+
+Le principe général est le suivant:
+
+1. Au démarrage du conteneur:
+    1. Trouver tous les fichiers de l'arborescence correspondant dont le nom termine par `<CHEMIN>/<NOM_FICHIER>.<EXT>.gotmpl`
+    2. Générer le fichier `<CHEMIN>/<NOM_FICHIER>.<EXT>` via `gomplate`
+
+> Par exemple, le fichier `/etc/nginx/nginx.conf.gotmpl` sera automatiquement transformé en `/etc/nginx/nginx.conf` au démarrage du conteneur.
+
+Cette opération s'appliquent également aux fichiers ajoutés par les images étendant les images de base, ainsi que dans les volumes.
+
+Une grande partie des fichiers de configuration par défaut des images sont prévus pour être compatibles avec ce mécanisme. Vous pouvez donc personnaliser une partie de leurs attributs via des variables d'environnement. 
+
+> [Voir par exemple le fichier `files/common/nginx/nginx.conf.gotmpl`](../files/common/nginx/nginx.conf.gotmpl).
--- a/docs/customize-nodejs-version.md
+++ b/docs/customize-nodejs-version.md
@ -0,0 +1,9 @@
+# Utiliser une version spécifique de NodeJS
+
+Les images intègrent l'outil [nvm](https://github.com/nvm-sh/nvm) par défaut. Cet outil permet d'installer une version spécifique de NodeJS.
+
+Pour personnaliser la version de NodeJS installée dans l'image de votre conteneur, créez un fichier `.nvmrc` à la racine de votre projet Symfony contenant la version de NodeJS souhaitée (par exemple: `lts/hydrogen` ou `v18.13.0`). 
+
+La liste des versions disponibles est visible via la commande `nvm ls-remote`.
+
+(Plus d'informations sur le site du projet NVM](https://github.com/nvm-sh/nvm#nvmrc)
--- a/docs/docker-usage.md
+++ b/docs/docker-usage.md
@ -0,0 +1,102 @@
+# Créer une image Docker pour votre projet Symfony
+
+> ⚠ La procédure suivante s'applique dans le cadre d'un déploiement sur Docker.
+>
+> Pour créer une image à destination d'un environnement Kubernetes, préférer
+> la procédure ["Usage dans Kubernetes"](./kubernetes-usage.md)
+
+## Création d'une image
+
+1. Dans le répertoire de votre projet, créer le fichier `Dockerfile` suivant:
+
+    ```Dockerfile
+    ARG ADDITIONAL_PACKAGES="<packages_list>"
+
+    FROM reg.cadoles.com/cadoles/symfony:alpine-php-8.1-standalone
+    ```
+
+    > La variable d'environnement `ADDITIONAL_PACKAGES` permet de définir une liste de paquets supplémentaires à installer avant d'exécuter les "triggers" de base embaqrués par l'image. Voir ["Installer des paquets supplémentaires"](./additional-packages.md) pour plus d'information.
+
+2. Créer le fichier `.dockerignore` avec les données suivantes:
+
+    ```text
+    /vendor
+    /var
+    ```
+
+3. Construire l'image de votre application
+
+    ```sh
+    docker build \
+        -t my-symfony-app:latest \
+        .
+    ```
+
+4. Exécuter l'image de votre application
+
+    ```sh
+    docker run \
+        -it \
+        --rm \
+        -p 8080:8080 \
+        my-symfony-app:latest
+    ```
+
+5. Ouvrir l'URL http://localhost:8080. Votre application devrait s'afficher.
+
+## Utilisation de votre image en développement
+
+1. **Avec docker**:
+
+    ```sh
+    docker run \
+        -it --rm \
+        -p 8080:8080 \
+        -v "${PWD}/src:/app/src:delegated" \
+        -v "${PWD}/templates:/app/templates:delegated" \
+        -v "${PWD}/translations:/app/translations:delegated" \
+        -v "${PWD}/tests:/app/tests:delegated" \
+        -v "${PWD}/config:/app/config:delegated" \
+        -v "${PWD}/.env:/app/.env:delegated" \
+        test-symfony-app
+    ```
+
+2. **Avec docker-compose**:
+   1. Créer un fichier `Dockerfile.standalone` à la racine de votre projet:
+
+        ```dockerfile
+        ARG ADDITIONAL_PACKAGES=""
+
+        FROM reg.cadoles.com/cadoles/symfony:alpine-php-8.1-standalone
+        ```
+
+   2. Créer un fichier `docker-compose.yml`:
+
+        ```yaml
+        version: '3'
+        services:
+
+            app:
+                build:
+                    context: .
+                    dockerfile: Dockerfile.standalone
+                ports:
+                    - ${APP_HTTP_PORT:-8080}:8080
+                volumes:
+                    - ./src:/app/src:delegated
+                    - ./templates:/app/templates:delegated
+                    - ./translations:/app/translations:delegated
+                    - ./tests:/app/tests:delegated
+                    - ./config:/app/config:delegated
+                    - ./.env:/app/.env:delegated
+                environment:
+                    PHP_FPM_MEMORY_LIMIT: 128m
+                    APP_ENV: dev
+                    ## truncated for brevity
+        ```
+
+   3. Démarrer l'environnement
+
+        ```sh
+        docker-compose up
+        ```
--- a/docs/kubernetes-usage.md
+++ b/docs/kubernetes-usage.md
@ -0,0 +1,3 @@
+# Utilisation avec Kubernetes
+
+> `TODO`
--- a/docs/starting-with-docker-compose.md
+++ b/docs/starting-with-docker-compose.md
@ -0,0 +1,115 @@
+# Créer un projet en utilisant docker-compose
+
+> ⚠ La procédure suivante s'applique dans le cadre du développement d'une application
+> en utilisant l'image ["standalone"](./docker-usage.md).
+
+## Création du projet symfony
+
+1. **Création du projet**
+
+```shell
+symfony new app --webapp [other options...]
+# voir https://symfony.com/download pour l'installation de symfony CLI
+```
+
+2. **Création du ficher Dockerfile**  
+A la racine du projet, créer le fichier `Dockerfile` et placer ce contenu:
+```dockerfile
+ARG ADDITIONAL_PACKAGES="php81-pdo=8.1.14-r0 php81-pdo_pgsql=8.1.14-r0"
+
+FROM reg.cadoles.com/cadoles/symfony:alpine-php-8.1-standalone
+```
+**Notes**: adapter la liste des paquets additionnels à votre besoin.
+
+3. **Création du fichier docker-compose**  
+A la racine du projet, créer le fichier (ou remplacer celui existant)`docker-compose.yml`, supprimer le fichier `docker-compose.override.yml` et placer ce contenu:
+```yaml
+version: '3'
+services:
+
+    app:
+        build:
+            context: .
+            dockerfile: Dockerfile
+        volumes:
+            - ./:/app:delegated
+        environment:
+            PHP_FPM_MEMORY_LIMIT: 128m
+            APP_ENV: dev
+            DATABASE_URL: postgresql://${POSTGRES_PASSWORD:-app}:${POSTGRES_PASSWORD:-app}@db:5432/${POSTGRES_DB:-app}?serverVersion=15&chartset=utf8
+        ports:
+            - ${APP_HTTP_PORT:-8080}:8080
+    
+    db:
+        image: postgres:${POSTGRES_VERSION:-15}-alpine
+        restart: unless-stopped
+        environment:
+            POSTGRES_DB: ${POSTGRES_DB:-app}
+            POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-app}
+            POSTGRES_USER: ${POSTGRES_USER:-app}
+        volumes:
+            - app-db-data:/var/lib/postgresql/data:rw
+
+volumes:
+  app-db-data:
+```
+4. Création du fichier `Makefile`  
+A la racine du projet, créer le fichier `Makefile` et placer ce contenu:
+```make
+dc := docker-compose
+de := $(dc) exec
+dr := $(dc) run --rm
+app := $(dr) --no-deps app
+
+.DEFAULT_GOAL := help
+.PHONY: help
+help: ## Affiche cette aide
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: dev
+dev: vendor/autoload.php ## Lance le serveur de développement
+	$(dc) up
+
+# -----------------------------------
+# Utilitaires
+# -----------------------------------
+.PHONY: php
+app: ## Se connecte au conteneur PHP
+	$(app) /bin/sh
+
+# -----------------------------------
+# Builds
+# -----------------------------------
+.PHONY: build
+build: ## build application image
+	docker build \
+    -t app-standalone:latest \
+    .
+
+# -----------------------------------
+# Dependencies
+# -----------------------------------
+vendor/autoload.php: composer.lock
+	$(app) composer install
+	touch vendor/autoload.php
+
+```
+
+## Démarrer l'environnement
+
+```shell
+cd app/
+make
+# doit afficher la liste des commandes disponible
+make dev
+# doit démarrer l'environnement docker défini dans votre docker-compose.yml
+# l'application doit être disponible à l'adresse http://localhost:8080
+```
+
+## Installer des dépendances `composer`
+
+```shell
+make app
+# dans le conteneur
+composer require ....
+```