doc(all): update main doc

This commit is contained in:
Philippe Caseiro 2023-06-09 12:25:23 +02:00
parent 351f693775
commit d331ed66cd
9 changed files with 27 additions and 277 deletions

View File

@ -3,11 +3,8 @@
################################
IMAGE_REPO := reg.cadoles.com/cadoles
IMAGE_NAME := sp
IMAGE_FULL_NAME := $(IMAGE_REPO)/$(IMAGE_NAME)
IMAGE_VERSION := 0.1.0
DOCKERFILE ?=
DAY_SUFFIX_TAG ?= $(shell date +%Y%m%d)
include main.mk
include main.mk

View File

@ -1,13 +1,27 @@
# 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)
### Construire les images
```
make
```
### Publier les images
```
make release
```
### Ajouter une "nouvelle" image
* Créer un répertoire avec le nom de l'image dans "./files/images", si votre image s'appelle "flubber"
``` mkdir -p ./files/images/flubber ```
* Créer un répertoire avec la "variante" de votre image (le tag principal), si votre image et une base de travail "base"
``` mkdir -p ./files/images/flubber/base ```
* Ajouter votre Dockerfile dans ce nouveau répertoire.
* Vous pouvez maintenant construire votre image
``` make ```

View File

@ -1,12 +0,0 @@
# 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" \
.
```

View File

@ -1,19 +0,0 @@
# 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).

View File

@ -1,9 +0,0 @@
# 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)

View File

@ -1,102 +0,0 @@
# 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
```

View File

@ -1,3 +0,0 @@
# Utilisation avec Kubernetes
> `TODO`

View File

@ -1,115 +0,0 @@
# 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 ....
```

View File

@ -1,5 +1,4 @@
FROM reg.cadoles.com/proxy_cache/library/alpine:edge
#FROM reg.cadoles.com/proxy_cache/library/httpd:alpine3.18
# Adding testing repo
RUN echo "https://dl-cdn.alpinelinux.org/alpine/edge/testing" >> /etc/apk/repositories
@ -8,9 +7,9 @@ RUN apk update && apk add apache-mod-auth-openidc apache2-ssl
RUN mkdir -p /var/www/html
COPY files/alpine/sp-oidc/base/conf.d/mod-auth-openidc.conf /etc/apache2/conf.d/mod-auth-openidc.conf
COPY files/alpine/sp-oidc/base/conf.d/default-vhost.conf /etc/apache2/conf.d/default-vhost.conf
COPY files/alpine/sp-oidc/base/scripts/httpd-foreground /usr/local/bin/
COPY files/images/sp-oidc/base/conf.d/mod-auth-openidc.conf /etc/apache2/conf.d/mod-auth-openidc.conf
COPY files/images/sp-oidc/base/conf.d/default-vhost.conf /etc/apache2/conf.d/default-vhost.conf
COPY files/images/sp-oidc/base/scripts/httpd-foreground /usr/local/bin/
RUN chmod +x /usr/local/bin/httpd-foreground
RUN mkdir -p /var/www/html