Wiki ISIG - Contributions [fr]

Packages R: développer un package

2026-07-20T07:30:20Z

Lvaudor : Page créée avec « = Développer un package R avec RStudio = Ce tutoriel présente une démarche simple pour créer un package R moderne, documenté et testé. Il s'appuie sur les packages '''devtools''', '''usethis''', '''roxygen2''' et '''testthat''', qui constituent aujourd'hui l'écosystème de référence pour le développement de packages. == Prérequis == Installer les principaux outils de développement : <code>install.packages(c( "devtools", "usethis", "roxygen2... »

= Développer un package R avec RStudio =
Ce tutoriel présente une démarche simple pour créer un package R moderne, documenté et testé. Il s'appuie sur les packages '''devtools''', '''usethis''', '''roxygen2''' et '''testthat''', qui constituent aujourd'hui l'écosystème de référence pour le développement de packages.

== Prérequis ==
Installer les principaux outils de développement :
<code>install.packages(c(
"devtools",
"usethis",
"roxygen2",
"testthat",
"pkgdown"
))</code>
Il est également recommandé d'utiliser une version récente de R et RStudio.

= 1. Créer le package =
Dans RStudio :

'''File > New Project > New Directory > R Package'''

Choisir :

* le nom du package (sans espaces ni caractères spéciaux)
* le dossier de création

RStudio crée automatiquement toute l'architecture du package.

On obtient notamment :
<code>monpackage/

├── DESCRIPTION
├── NAMESPACE
├── R/
├── man/
└── monpackage.Rproj</code>
Les rôles des principaux dossiers sont :
{| class="wikitable"
!Élément
!Rôle
|-
|R/
|Contient toutes les fonctions du package
|-
|man/
|Documentation générée automatiquement
|-
|DESCRIPTION
|Métadonnées et dépendances
|-
|NAMESPACE
|Fonctions exportées et imports (généré automatiquement)
|}
Les fichiers '''NAMESPACE''' et '''man/''' ne doivent généralement pas être modifiés à la main lorsqu'on utilise roxygen2.

= 2. Initialiser le package =
Plusieurs outils peuvent être ajoutés immédiatement grâce à '''usethis'''.

== Initialiser Git ==
<code>usethis::use_git()</code>
Éventuellement :
<code>usethis::use_github()</code>
pour créer directement un dépôt GitHub.

== Ajouter une licence ==
Par exemple :
<code>usethis::use_mit_license()</code>
ou
<code>usethis::use_gpl3_license()</code>

== Ajouter un README ==
<code>usethis::use_readme_rmd()</code>

= 3. Écrire des fonctions =
Toutes les fonctions doivent être placées dans le dossier
<code>R/</code>
Par exemple :
<code>R/calcul.R</code>
contenant
<code>addition <- function(x, y) {
x + y
}</code>
Le nom du fichier est libre.

En revanche, les fonctions doivent toujours être dans le dossier '''R/'''.

= 4. Documenter avec Roxygen =
Chaque fonction est précédée d'un bloc de commentaires.

Exemple :
<code>#' Addition de deux nombres
#'
#' Additionne deux valeurs numériques.
#'
#' @param x premier nombre
#' @param y second nombre
#'
#' @return Une valeur numérique.
#'
#' @export
addition <- function(x, y) {
x + y
}</code>
La documentation est ensuite générée automatiquement.

Dans RStudio :

'''Build > More > Document'''

ou
<code>devtools::document()</code>
Cette commande met à jour :

* le dossier <code>man/</code>
* le fichier <code>NAMESPACE</code>

Ces fichiers ne doivent normalement jamais être édités manuellement.

= 5. Gérer les dépendances =
Éviter de modifier directement le fichier DESCRIPTION.

Préférer :
<code>usethis::use_package("sf")</code>
qui ajoute automatiquement
<code>Imports:
sf</code>
Pour une dépendance utilisée uniquement pendant le développement :
<code>usethis::use_package("testthat", type = "Suggests")</code>
Les types de dépendances les plus fréquents sont :
{| class="wikitable"
!Type
!Utilisation
|-
|Imports
|Package nécessaire au fonctionnement
|-
|Suggests
|Package utilisé uniquement pour les tests ou des fonctionnalités optionnelles
|-
|Depends
|Rarement utilisé aujourd'hui
|}

= 6. Charger le package pendant le développement =
Pendant le développement, il n'est pas nécessaire de réinstaller le package après chaque modification.

Utiliser :
<code>devtools::load_all()</code>
Cette commande :

* charge toutes les fonctions ;
* recharge les données ;
* recharge les fichiers R modifiés ;
* permet de tester immédiatement les nouvelles fonctions.

C'est la commande utilisée en permanence pendant le développement.

= 7. Différence entre <code>load_all()</code> et le bouton Build =
Ces deux actions ont des objectifs très différents.

== <code>devtools::load_all()</code> ==
À utiliser pendant le développement.

Il simule un package installé mais sans construire réellement le package.

C'est très rapide.

Idéal pour :

* tester une fonction ;
* lancer une application Shiny ;
* faire du débogage.

== Build ==
Le bouton '''Build''' réalise une véritable construction du package.

Selon l'action choisie, RStudio peut :

* documenter le package ;
* construire le fichier <code>.tar.gz</code> ;
* installer le package ;
* vérifier (<code>R CMD check</code>) qu'il respecte les standards CRAN.

Cette étape est plus lente mais permet de détecter des erreurs qui ne sont pas visibles avec <code>load_all()</code>.

En pratique :

* <code>load_all()</code> est utilisé des dizaines de fois par jour ;
* Build est utilisé avant un commit important ou avant une diffusion.

= 8. Tester avec testthat =
Initialiser les tests :
<code>usethis::use_testthat()</code>
Créer un premier fichier de test :
<code>usethis::use_test("addition")</code>
On obtient :
<code>tests/testthat/test-addition.R</code>
Exemple :
<code>test_that("addition fonctionne", {

expect_equal(addition(2,3),5)

})</code>
Exécuter tous les tests :
<code>devtools::test()</code>
Les tests permettent de vérifier que les fonctions continuent à produire les résultats attendus après des modifications.

= 9. Vérifier le package =
Avant toute diffusion :
<code>devtools::check()</code>
Cette commande lance l'équivalent de :
<code>R CMD check</code>
Elle détecte notamment :

* erreurs ;
* avertissements ;
* notes ;
* documentation incomplète ;
* dépendances oubliées.

Un package destiné au partage devrait idéalement être exempt d'erreurs et d'avertissements.

= 10. Cas particulier : package contenant une application Shiny =
Un package peut également contenir une application Shiny.

L'organisation est généralement la suivante :
<code>R/
app.R
server.R
ui.R
modules/
utils.R</code>
La fonction principale est par exemple :
<code>run_app <- function() {

shiny::shinyApp(
ui = app_ui(),
server = app_server
)

}</code>
Pendant le développement :
<code>devtools::load_all()

run_app()</code>
L'application utilise alors directement les fonctions du package en cours de développement.

Cette approche présente plusieurs avantages :

* les fonctions sont réutilisables ;
* les tests peuvent porter sur la logique métier indépendamment de Shiny ;
* le code est mieux organisé ;
* il devient facile de documenter et partager les fonctions.

Le package '''golem''' automatise une grande partie de cette architecture et constitue aujourd'hui une référence pour le développement d'applications Shiny complexes.

= Bonnes pratiques =

* Une fonction = une responsabilité.
* Documenter chaque fonction.
* Écrire des tests dès que possible.
* Utiliser <code>usethis</code> plutôt que modifier les fichiers système à la main.
* Utiliser <code>load_all()</code> pendant le développement.
* Lancer régulièrement <code>devtools::check()</code>.
* Versionner le projet avec Git.

En suivant cette démarche, on obtient un package facile à maintenir, documenté, testable et partageable.

ShinyProxy

2026-04-21T12:33:49Z

Lvaudor : /* To do list mise en ligne d'une nouvelle appli */

'''<big>Attention : Page en cours de rédaction</big>'''

ISIG-Apps passe sous ShinyProxy pour améliorer la stabilité et l'isolation de vos applications pendant les montées en charge. Le fonctionnement est très différent par rapport à l'ancien Shiny-Server et nécessite quelques bases dans l'utilisation de Docker. L'objectif de cette page est de vous guider, rapidement et simplement, dans le nouveau workflow dev > prod en partant du principe que vous ne connaissez encore pas grand-chose à Docker.

== Principe de fonctionnement de ShinyProxy (et Docker) ==
ShinyProxy fonctionne comme un orchestrateur de conteneurs Docker. Chaque appli configurée doit avoir une image Docker associée présente sur le serveur qui exécute ShinyProxy. C'est ShinyProxy qui s'occupera ensuite de lancer et stopper un conteneur à chaque fois qu'un internaute se connectera ou se déconnectera de votre appli.
[[Fichier:Schéma Docker.png|centré|sans_cadre|1054x1054px]]

Afin que votre application puisse fonctionner sur ShinyProxy, il va donc falloir créer une '''image''' qui permettra au serveur ShinyProxy de lancer des '''containers''' de votre application.

Vous n'aurez généralement pas besoin de volume pour stocker des données pérennes dans le cas d'une application Shiny. Si votre application utilise une base de données, celle-ci devra être externalisée (hébergée sur le serveur de bases de données d'ISIG par exemple).

ShinyProxy fera en sorte qu'un certain nombre de containers (à définir dans la configuration décrite à la fin de ce tutoriel) soient toujours disponibles pour de nouveaux utilisateurs qui se connecteraient à votre application. Il s'occupera également de supprimer les containers quand vos utilisateurs se déconnectent.

== Conteneurisation de votre appli Shiny ==
La conteneurisation peut se faire directement sur votre machine personelle si vous y avez installé Docker (https://docs.docker.com/engine/install/), ou sur le serveur isig-apps de dev via [https://rstudio.evs.ens-lyon.fr Rstudio server] et son terminal intégré.

=== Fixer le port ===
Pour fonctionner en mode conteneurisé, votre application devra écouter toujours sur le même port (ce qui n'est pas le comportement par défaut d'une application Shiny).

Afin de s'en assurer, il faut :

* Dans le cas d'un appli Shiny classique, ajouter dans <code>options(..)</code>, avant l'appel de <code>shinyApp(..)</code>, les options suivantes : <code>"shiny.port"=3841</code> et <code>"shiny.host"="0.0.0.0"</code>. Par exemple :
<syntaxhighlight lang="r">
library(shiny)
library(glourbi)

# Dans cet exemple, l'application écoutera systématiquement sur le port 3838
options("shiny.port" = 3838, "shiny.host" = "0.0.0.0", "golem.app.prod" = TRUE)

shinyApp(ui=glourbapp:::app_ui,server=glourbapp:::app_server)
</syntaxhighlight>

* Dans le cas d'un document Rmarkdown, ........

=== Choisir l'image source ===
La construction d'une image Docker se fait sur la base... d'une autre. On choisi en général son image de base en fonction de ce qu'on va faire avec. Pour une application Shiny, nous aurons besoin d'une image Docker spécialisée en R.

Le [https://rocker-project.org/images/ projet Rocker] propose plusieurs images de base avec différentes quantités de packages pré-installés. Lorsque l'on choisi son image de base, il faut trouver le bon compromis entre une image légère et une image avec suffisamment de dépendances pré-installées pour qu'elle soit pratique.

L'image [https://eddelbuettel.github.io/r2u/ r2u] est une bonne base assez simple à utiliser, car elle va chercher des binaires précompilés des packages R que l'on souhaite installer et toutes leurs dépendances, librairies système incluses ! Pratiquement rien n'y est pré-installé, il faudra donc bien préciser toutes les dépendances dont vous avez besoin. En contrepartie, l'image sera plutôt légère, ce qui est une bonne chose ! L'inconvénient de cette fonctionnalité est (à ma connaissance) qu'elle ne fonctionne qu'avec la fonction <code>install.packages(...)</code>. Il n'est donc pas possible d'installer une version spécifique d'un package avec <code>remotes::install_version(...)</code> par exemple (la fonction reste utilisable de manière classique).

=== Écrire le Dockerfile ===

La création d'une image Docker repose sur l'écriture d'un fichier texte appelé '''Dockerfile''' (sans extension).

Voici un exemple de Dockerfile pour l'application GloUrb :<syntaxhighlight lang="dockerfile">
# On commence par définir l'image sur laquelle va se baser la notre
FROM rocker/r2u:jammy

# On précise quelques infos qui permettrons d'identifier l'image
LABEL org.opencontainers.image.authors="Lise Vaudor <lise.vaudor@ens-lyon.fr>, Samuel Dunesme <samuel.dunesme@ens-lyon.fr>"
LABEL org.opencontainers.image.source="https://github.com/glourb/glourbapp"
LABEL org.opencontainers.image.documentation="https://evs-gis.github.io/glourbdoc/"
LABEL org.opencontainers.image.version="0.0.0.9000"
LABEL org.opencontainers.image.description="An app for the GloUrb project"

# On peut éventuellement générer des locales supplémentaires si notre appli utilise d'autres langues que l'anglais
RUN locale-gen fr_FR.UTF-8

# On liste maintenant toutes les dépendances R à installer
RUN Rscript -e 'install.packages("tidyr")'
RUN Rscript -e 'install.packages("shiny")'
RUN Rscript -e 'install.packages("config")'
RUN Rscript -e 'install.packages("testthat")'
RUN Rscript -e 'install.packages("tibble")'
RUN Rscript -e 'install.packages("purrr")'
RUN Rscript -e 'install.packages("dplyr")'
RUN Rscript -e 'install.packages("ggplot2")'
RUN Rscript -e 'install.packages("forcats")'
RUN Rscript -e 'install.packages("magrittr")'
RUN Rscript -e 'install.packages("golem")'
RUN Rscript -e 'install.packages("sf")'
RUN Rscript -e 'install.packages("plotly")'
RUN Rscript -e 'install.packages("spelling")'
RUN Rscript -e 'install.packages("mclust")'
RUN Rscript -e 'install.packages("leaflet")'
RUN Rscript -e 'install.packages("cluster")'
RUN Rscript -e 'install.packages("cowplot")'
RUN Rscript -e 'install.packages("FactoMineR")'
RUN Rscript -e 'install.packages("glue")'
RUN Rscript -e 'install.packages("grDevices")'
RUN Rscript -e 'install.packages("RColorBrewer")'
RUN Rscript -e 'install.packages("remotes")'
RUN Rscript -e 'install.packages("cicerone")'
RUN Rscript -e 'install.packages("RPostgres")'
RUN Rscript -e 'install.packages("DBI")'
RUN Rscript -e 'install.packages("DT")'

RUN Rscript -e 'remotes::install_github("glourb/glourbi")'

# On copie l'arborescence de fichiers dans un dossier app à la racine de l'image. Ce sera le working directory des containers lancés avec notre image
RUN mkdir /app
ADD . /app
WORKDIR /app

# Si besoin, on peut installer notre package
RUN R -e 'remotes::install_local()'

# On détermine le port qui sera exposé (attention à bien fixer le port sur lequel votre appli écoute, cf. ci-dessus)
EXPOSE 3838

# Pour plus de sécurité, on fait en sorte que les containers ne se lancent pas avec l'utilisateur "root", mais avec un utilisateur "app" dédié
RUN groupadd -g 1010 app && useradd -c 'app' -u 1010 -g 1010 -m -d /home/app -s /sbin/nologin app
USER app

# Enfin, on précise la commande qui permet de lancer notre appli. C'est cette commande qui sera lancée par défaut par tout nouveau container lancé avec notre image
CMD ["R", "-f", "app.R"]
</syntaxhighlight>

=== Construire l'image Docker ===
Pour construire l'image docker à l'aide du Dockerfile, il faut lancer la commande <code>docker build</code>. C'est à ce moment que l'on va versionner l'image en la taguant avec l'argument <code>-t</code>. On peut mettre directement plusieurs tags à une image, ou les ajouter à posteriori en relançant la commande <code>docker build</code>. Si le Dockerfile n'a pas changé depuis le dernier build, <code>docker build</code> ne fera qu'ajouter les tags à l'image existante.

Pour que la CLI Docker trouve bien le Dockerfile, on lance le terminal dans le dossier ou ce Dockerfile est enregistré.

<code>docker build . -t ghcr.io/evs-gis/mapdoapp:latest -t ghcr.io/evs-gis/mapdoapp:2.0.1 -t ghcr.io/evs-gis/mapdoapp:$(git rev-parse --short HEAD)</code>

Remarquez que le tag doit contenir le chemin complet vers le registre où sera poussée l'image (étape suivante). Si vous ne précisez pas le chemin (par exemple <code>mapdoapp:latest</code>), le registre utilisé sera DockerHub.

Notez le tag <code>$(git rev-parse --short HEAD)</code> qui permet de taguer l'image avec le hash (la référence) du commit actuel (ne fonctionne que si vous êtes dans un dépôt git). Ce tag est bien pratique si vous n'incrémentez pas un numéro de version par ailleurs (<code>2.0.1</code> dans l'exemple ci-dessus).

Le tag <code>latest</code> est à mettre sur la dernière version de votre image. Il sera automatiquement retiré de toutes les autres versions de votre image.

La commande <code>docker images</code> permet ensuite de lister les tags disponibles localement. Si le build a réussi, vous devriez y voir votre image.<syntaxhighlight lang="bash">
~$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
ghcr.io/evs-gis/mapdoapp 2.0.1 b2b999e7d781 3 days ago 1.27GB
ghcr.io/evs-gis/mapdoapp 7ad814c b2b999e7d781 3 days ago 1.27GB
ghcr.io/evs-gis/mapdoapp latest b2b999e7d781 3 days ago 1.27GB
ghcr.io/glourb/glourbapp 642e23b 8a3daa97546e 4 days ago 1.38GB
ghcr.io/glourb/glourbapp latest 8a3daa97546e 4 days ago 1.38GB
ghcr.io/glourb/glourbapp 502564d 9a2050fc09d4 4 days ago 1.38GB
semaphoreui/semaphore v2.12.4 136bec584184 2 weeks ago 727MB
ghcr.io/mastergeonum/cartondes main a95ee654e34a 5 weeks ago 205MB
dockurr/windows latest c3419fd6e55a 2 months ago 384MB
docker.osgeo.org/geoserver 2.26.1 a91188b23092 3 months ago 608MB
rocker/verse 4.4.1 202c993befdc 3 months ago 3.77GB
ghcr.io/evs-gis/glourbee-ui 1.1.0 03e05bed5617 4 months ago 1.47GB

</syntaxhighlight>Remarquez que <code>ghcr.io/evs-gis/mapdoapp</code> est présente plusieurs fois avec des tags différents, mais le même IMAGE ID. Il s'agit bien de la même image et elle n'est pas dupliquée sur le disque.

Pour supprimer un tag, on utilisera la commande <code>docker image rm ghcr.io/evs-gis/mapdoapp:2.0.1</code>. Si plus aucun tag n'existe pour l'image, elle sera complètement supprimée du disque local.

=== Tester l'image ===
Pour tester son image, on peut utiliser la commande <code>docker run</code> :

<code>docker run --rm -p 3838:3838 ghcr.io/evs-gis/mapdoapp:latest</code>

* --rm : Supprimer le container lorsqu'il est arrêté.
* -p 3838:3838 : exposer le port 3838 local et le faire pointer vers le port 3838 dans le container.

Les logs de l'application s'affichent dans le terminal et l'application est accessible dans un navigateur à l'adresse http://localhost:3838. Pour stopper le container, '''Ctrl+C'''.

=== Faire du ménage localement ===
Il arrive que des vieilles images sans tag, de vieux volumes et de vieux containers plantés restent sur le disque au fil du temps. Tester la commande <code>docker ps --all</code> par exemple, pour lister tous les containers locaux (lancés ou stoppés). La commande <code>docker system prune</code> permet de faire le grand ménage.

=== Pousser l'image sur un registre ===
Pour que le serveur ShinyProxy (ainsi que le monde entier !) puisse accéder à votre image, il faut la pousser sur un registre. Si vous ne souhaitez pas que votre image soit publique, vous pouvez utiliser le registre ghcr.io/evs-gis (le serveur ShinyProxy y a accès même si les images sont privées).

Il faut d'abord se loguer sur le registre avec son login GitHub habituel, et un ''Personal Access Token'' en guise de mot de passe. Pour [https://github.com/settings/tokens/new obtenir un ''Personal Access Token''], rendez-vous [https://github.com/settings/tokens/new ici] et activez bien le droit <code>write:packages</code> pour votre token. <syntaxhighlight lang="sh"># La commande suivante est à lancer pour se loguer sur le registre. Il n'est pas nécessaire de la relancer à chaque fois.
docker login ghcr.io

# Pour pousser tous les tags de notre image sur le registre, on utilise ensuite la commande suivante.
docker push ghcr.io/evs-gis/mapdoapp -a

# Pour pousser seulement un tag spécifique, on préfèrera la commande suivante.
docker push ghcr.io/evs-gis/mapdoapp:latest</syntaxhighlight>

== Configuration de l'application sur le serveur ShinyProxy de production ==
La configuration initiale de l'application doit être faite par l'administrateur du serveur.

== Mise à jour d'une appli ==
La mise à jour d'une appli sur le serveur de prod ne nécessite généralement pas de modifier la configuration. Il suffit de '''pousser la nouvelle version de votre image sur votre registre''' (avec le tag latest), puis de '''lancer le job ''Mise à jour d'une application en production sous ShinyProxy'' sur Jenkins''' pour forcer le redémarrage des containers d'attente déjà lancés. Si l'intégration continue a été correctement configurée, le job Jenkins de mise à jour devrait se lancer automatiquement dès que la nouvelle version de l'image arrive sur le registre.

== Debug des applis en prod ==

Pour accéder aux logs des applications sur le serveur de prod, se connecter en ssh aux archives:<syntaxhighlight lang="bash">
ssh archives.evs.ens-lyon.fr
</syntaxhighlight>Puis afficher le contenu des logs:<syntaxhighlight lang="bash">
tail -n 10 /data/echanges/ShinyProxyLogs/shinyapps-stdout.log
# récupérer les 10 (option -n) dernières lignes de stdout

tail -n 10 -f /data/echanges/ShinyProxyLogs/shinyapps-stderr.log
# voir stderr défiler en temps réel (option -f)

tail -n 10 /data/echanges/ShinyProxyLogs/shinyapps-std*.log
# voir les 10 dernières lignes de tous les logs (standard et erreur)

tail -n 100 ...
# pour les 100 dernières lignes, etc
</syntaxhighlight>Tous les logs (quelque soit l'appli) apparaissent. Pour chercher spécifiquement les lignes correspondant à une appli précise (par exemple mapdoapp):<syntaxhighlight lang="bash">
grep mapdoapp /data/echanges/ShinyProxyLogs/shinyapps-std*.log
# N'affiche que les lignes qui concernent mapdoapp
</syntaxhighlight>On peut aussi combiner défilement en live + grep<syntaxhighlight lang="bash">
tail -f /data/echanges/ShinyProxyLogs/shinyapps-std*.log | grep mapdoapp
</syntaxhighlight>

== To do list mise en ligne d'une nouvelle appli ==
1) récupérer dans le dossier d'une appli déjà mise en ligne sur ShinyProxy: run.R (si appli learnr), dockerfile, et le dossier .github qui contient un yaml qui permettra de build et push l'image docker sur le ShinyProxy.

2) modifier dans run.R (si appli learnr) le nom du Rmd à tricoter

3) modifier dans le yaml le nom de l'image docker (deux lignes à changer)

4) modifier le dockerfile: infos sur l'appli et noms des packages à installer

5) build l'image docker localement pour vérifier que tout est ok, par ex. <syntaxhighlight lang="bash">
docker build . -t ghcr.io/lvaudor/learnr_exos_shiny:latest
</syntaxhighlight>6) run un container pour vérifier que tout est ok, par ex.<syntaxhighlight lang="bash">
docker run --rm -p 3840:3840 ghcr.io/learnr_shiny_exos:latest
</syntaxhighlight>7) Aller sur le repo github et changer paramètres: Settings => Actions => General => Workflow permissions => Cocher Read and write permissions

8) Faire un commit et push des dernières modifs sur main => Une image docker doit être créée dans les github Actions

9) Prévenir Samuel pour qu'il ajoute la nouvelle appli au registre

== To do list mise à jour d'une appli ==
1) build l'image docker localement pour vérifier que tout est ok, par ex.<syntaxhighlight lang="bash">
docker build . -t ghcr.io/lvaudor/learnr_exos_shiny:latest
</syntaxhighlight>2) run un container pour vérifier que tout est ok, par ex.<syntaxhighlight lang="bash">
docker run --rm -p 3840:3840 ghcr.io/learnr_shiny_exos:latest
</syntaxhighlight>3) Faire le docker push pour mettre à jour le registre<syntaxhighlight lang="bash">
docker push ghcr.io/lvaudor/learnr_shiny_exos:latest

</syntaxhighlight>
[[Catégorie:Tutoriel]]

ShinyProxy

2026-04-10T09:01:38Z

Lvaudor : /* To do list mise en ligne d'une nouvelle appli */

'''<big>Attention : Page en cours de rédaction</big>'''

ISIG-Apps passe sous ShinyProxy pour améliorer la stabilité et l'isolation de vos applications pendant les montées en charge. Le fonctionnement est très différent par rapport à l'ancien Shiny-Server et nécessite quelques bases dans l'utilisation de Docker. L'objectif de cette page est de vous guider, rapidement et simplement, dans le nouveau workflow dev > prod en partant du principe que vous ne connaissez encore pas grand-chose à Docker.

== Principe de fonctionnement de ShinyProxy (et Docker) ==
ShinyProxy fonctionne comme un orchestrateur de conteneurs Docker. Chaque appli configurée doit avoir une image Docker associée présente sur le serveur qui exécute ShinyProxy. C'est ShinyProxy qui s'occupera ensuite de lancer et stopper un conteneur à chaque fois qu'un internaute se connectera ou se déconnectera de votre appli.
[[Fichier:Schéma Docker.png|centré|sans_cadre|1054x1054px]]

Afin que votre application puisse fonctionner sur ShinyProxy, il va donc falloir créer une '''image''' qui permettra au serveur ShinyProxy de lancer des '''containers''' de votre application.

Vous n'aurez généralement pas besoin de volume pour stocker des données pérennes dans le cas d'une application Shiny. Si votre application utilise une base de données, celle-ci devra être externalisée (hébergée sur le serveur de bases de données d'ISIG par exemple).

ShinyProxy fera en sorte qu'un certain nombre de containers (à définir dans la configuration décrite à la fin de ce tutoriel) soient toujours disponibles pour de nouveaux utilisateurs qui se connecteraient à votre application. Il s'occupera également de supprimer les containers quand vos utilisateurs se déconnectent.

== Conteneurisation de votre appli Shiny ==
La conteneurisation peut se faire directement sur votre machine personelle si vous y avez installé Docker (https://docs.docker.com/engine/install/), ou sur le serveur isig-apps de dev via [https://rstudio.evs.ens-lyon.fr Rstudio server] et son terminal intégré.

=== Fixer le port ===
Pour fonctionner en mode conteneurisé, votre application devra écouter toujours sur le même port (ce qui n'est pas le comportement par défaut d'une application Shiny).

Afin de s'en assurer, il faut :

* Dans le cas d'un appli Shiny classique, ajouter dans <code>options(..)</code>, avant l'appel de <code>shinyApp(..)</code>, les options suivantes : <code>"shiny.port"=3841</code> et <code>"shiny.host"="0.0.0.0"</code>. Par exemple :
<syntaxhighlight lang="r">
library(shiny)
library(glourbi)

# Dans cet exemple, l'application écoutera systématiquement sur le port 3838
options("shiny.port" = 3838, "shiny.host" = "0.0.0.0", "golem.app.prod" = TRUE)

shinyApp(ui=glourbapp:::app_ui,server=glourbapp:::app_server)
</syntaxhighlight>

* Dans le cas d'un document Rmarkdown, ........

=== Choisir l'image source ===
La construction d'une image Docker se fait sur la base... d'une autre. On choisi en général son image de base en fonction de ce qu'on va faire avec. Pour une application Shiny, nous aurons besoin d'une image Docker spécialisée en R.

Le [https://rocker-project.org/images/ projet Rocker] propose plusieurs images de base avec différentes quantités de packages pré-installés. Lorsque l'on choisi son image de base, il faut trouver le bon compromis entre une image légère et une image avec suffisamment de dépendances pré-installées pour qu'elle soit pratique.

L'image [https://eddelbuettel.github.io/r2u/ r2u] est une bonne base assez simple à utiliser, car elle va chercher des binaires précompilés des packages R que l'on souhaite installer et toutes leurs dépendances, librairies système incluses ! Pratiquement rien n'y est pré-installé, il faudra donc bien préciser toutes les dépendances dont vous avez besoin. En contrepartie, l'image sera plutôt légère, ce qui est une bonne chose ! L'inconvénient de cette fonctionnalité est (à ma connaissance) qu'elle ne fonctionne qu'avec la fonction <code>install.packages(...)</code>. Il n'est donc pas possible d'installer une version spécifique d'un package avec <code>remotes::install_version(...)</code> par exemple (la fonction reste utilisable de manière classique).

=== Écrire le Dockerfile ===

La création d'une image Docker repose sur l'écriture d'un fichier texte appelé '''Dockerfile''' (sans extension).

Voici un exemple de Dockerfile pour l'application GloUrb :<syntaxhighlight lang="dockerfile">
# On commence par définir l'image sur laquelle va se baser la notre
FROM rocker/r2u:jammy

# On précise quelques infos qui permettrons d'identifier l'image
LABEL org.opencontainers.image.authors="Lise Vaudor <lise.vaudor@ens-lyon.fr>, Samuel Dunesme <samuel.dunesme@ens-lyon.fr>"
LABEL org.opencontainers.image.source="https://github.com/glourb/glourbapp"
LABEL org.opencontainers.image.documentation="https://evs-gis.github.io/glourbdoc/"
LABEL org.opencontainers.image.version="0.0.0.9000"
LABEL org.opencontainers.image.description="An app for the GloUrb project"

# On peut éventuellement générer des locales supplémentaires si notre appli utilise d'autres langues que l'anglais
RUN locale-gen fr_FR.UTF-8

# On liste maintenant toutes les dépendances R à installer
RUN Rscript -e 'install.packages("tidyr")'
RUN Rscript -e 'install.packages("shiny")'
RUN Rscript -e 'install.packages("config")'
RUN Rscript -e 'install.packages("testthat")'
RUN Rscript -e 'install.packages("tibble")'
RUN Rscript -e 'install.packages("purrr")'
RUN Rscript -e 'install.packages("dplyr")'
RUN Rscript -e 'install.packages("ggplot2")'
RUN Rscript -e 'install.packages("forcats")'
RUN Rscript -e 'install.packages("magrittr")'
RUN Rscript -e 'install.packages("golem")'
RUN Rscript -e 'install.packages("sf")'
RUN Rscript -e 'install.packages("plotly")'
RUN Rscript -e 'install.packages("spelling")'
RUN Rscript -e 'install.packages("mclust")'
RUN Rscript -e 'install.packages("leaflet")'
RUN Rscript -e 'install.packages("cluster")'
RUN Rscript -e 'install.packages("cowplot")'
RUN Rscript -e 'install.packages("FactoMineR")'
RUN Rscript -e 'install.packages("glue")'
RUN Rscript -e 'install.packages("grDevices")'
RUN Rscript -e 'install.packages("RColorBrewer")'
RUN Rscript -e 'install.packages("remotes")'
RUN Rscript -e 'install.packages("cicerone")'
RUN Rscript -e 'install.packages("RPostgres")'
RUN Rscript -e 'install.packages("DBI")'
RUN Rscript -e 'install.packages("DT")'

RUN Rscript -e 'remotes::install_github("glourb/glourbi")'

# On copie l'arborescence de fichiers dans un dossier app à la racine de l'image. Ce sera le working directory des containers lancés avec notre image
RUN mkdir /app
ADD . /app
WORKDIR /app

# Si besoin, on peut installer notre package
RUN R -e 'remotes::install_local()'

# On détermine le port qui sera exposé (attention à bien fixer le port sur lequel votre appli écoute, cf. ci-dessus)
EXPOSE 3838

# Pour plus de sécurité, on fait en sorte que les containers ne se lancent pas avec l'utilisateur "root", mais avec un utilisateur "app" dédié
RUN groupadd -g 1010 app && useradd -c 'app' -u 1010 -g 1010 -m -d /home/app -s /sbin/nologin app
USER app

# Enfin, on précise la commande qui permet de lancer notre appli. C'est cette commande qui sera lancée par défaut par tout nouveau container lancé avec notre image
CMD ["R", "-f", "app.R"]
</syntaxhighlight>

=== Construire l'image Docker ===
Pour construire l'image docker à l'aide du Dockerfile, il faut lancer la commande <code>docker build</code>. C'est à ce moment que l'on va versionner l'image en la taguant avec l'argument <code>-t</code>. On peut mettre directement plusieurs tags à une image, ou les ajouter à posteriori en relançant la commande <code>docker build</code>. Si le Dockerfile n'a pas changé depuis le dernier build, <code>docker build</code> ne fera qu'ajouter les tags à l'image existante.

Pour que la CLI Docker trouve bien le Dockerfile, on lance le terminal dans le dossier ou ce Dockerfile est enregistré.

<code>docker build . -t ghcr.io/evs-gis/mapdoapp:latest -t ghcr.io/evs-gis/mapdoapp:2.0.1 -t ghcr.io/evs-gis/mapdoapp:$(git rev-parse --short HEAD)</code>

Remarquez que le tag doit contenir le chemin complet vers le registre où sera poussée l'image (étape suivante). Si vous ne précisez pas le chemin (par exemple <code>mapdoapp:latest</code>), le registre utilisé sera DockerHub.

Notez le tag <code>$(git rev-parse --short HEAD)</code> qui permet de taguer l'image avec le hash (la référence) du commit actuel (ne fonctionne que si vous êtes dans un dépôt git). Ce tag est bien pratique si vous n'incrémentez pas un numéro de version par ailleurs (<code>2.0.1</code> dans l'exemple ci-dessus).

Le tag <code>latest</code> est à mettre sur la dernière version de votre image. Il sera automatiquement retiré de toutes les autres versions de votre image.

La commande <code>docker images</code> permet ensuite de lister les tags disponibles localement. Si le build a réussi, vous devriez y voir votre image.<syntaxhighlight lang="bash">
~$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
ghcr.io/evs-gis/mapdoapp 2.0.1 b2b999e7d781 3 days ago 1.27GB
ghcr.io/evs-gis/mapdoapp 7ad814c b2b999e7d781 3 days ago 1.27GB
ghcr.io/evs-gis/mapdoapp latest b2b999e7d781 3 days ago 1.27GB
ghcr.io/glourb/glourbapp 642e23b 8a3daa97546e 4 days ago 1.38GB
ghcr.io/glourb/glourbapp latest 8a3daa97546e 4 days ago 1.38GB
ghcr.io/glourb/glourbapp 502564d 9a2050fc09d4 4 days ago 1.38GB
semaphoreui/semaphore v2.12.4 136bec584184 2 weeks ago 727MB
ghcr.io/mastergeonum/cartondes main a95ee654e34a 5 weeks ago 205MB
dockurr/windows latest c3419fd6e55a 2 months ago 384MB
docker.osgeo.org/geoserver 2.26.1 a91188b23092 3 months ago 608MB
rocker/verse 4.4.1 202c993befdc 3 months ago 3.77GB
ghcr.io/evs-gis/glourbee-ui 1.1.0 03e05bed5617 4 months ago 1.47GB

</syntaxhighlight>Remarquez que <code>ghcr.io/evs-gis/mapdoapp</code> est présente plusieurs fois avec des tags différents, mais le même IMAGE ID. Il s'agit bien de la même image et elle n'est pas dupliquée sur le disque.

Pour supprimer un tag, on utilisera la commande <code>docker image rm ghcr.io/evs-gis/mapdoapp:2.0.1</code>. Si plus aucun tag n'existe pour l'image, elle sera complètement supprimée du disque local.

=== Tester l'image ===
Pour tester son image, on peut utiliser la commande <code>docker run</code> :

<code>docker run --rm -p 3838:3838 ghcr.io/evs-gis/mapdoapp:latest</code>

* --rm : Supprimer le container lorsqu'il est arrêté.
* -p 3838:3838 : exposer le port 3838 local et le faire pointer vers le port 3838 dans le container.

Les logs de l'application s'affichent dans le terminal et l'application est accessible dans un navigateur à l'adresse http://localhost:3838. Pour stopper le container, '''Ctrl+C'''.

=== Faire du ménage localement ===
Il arrive que des vieilles images sans tag, de vieux volumes et de vieux containers plantés restent sur le disque au fil du temps. Tester la commande <code>docker ps --all</code> par exemple, pour lister tous les containers locaux (lancés ou stoppés). La commande <code>docker system prune</code> permet de faire le grand ménage.

=== Pousser l'image sur un registre ===
Pour que le serveur ShinyProxy (ainsi que le monde entier !) puisse accéder à votre image, il faut la pousser sur un registre. Si vous ne souhaitez pas que votre image soit publique, vous pouvez utiliser le registre ghcr.io/evs-gis (le serveur ShinyProxy y a accès même si les images sont privées).

Il faut d'abord se loguer sur le registre avec son login GitHub habituel, et un ''Personal Access Token'' en guise de mot de passe. Pour [https://github.com/settings/tokens/new obtenir un ''Personal Access Token''], rendez-vous [https://github.com/settings/tokens/new ici] et activez bien le droit <code>write:packages</code> pour votre token. <syntaxhighlight lang="sh">
# La commande suivante est à lancer pour se loguer sur le registre. Il n'est pas nécessaire de la relancer à chaque fois.
docker login ghcr.io

# Pour pousser tous les tags de notre image sur le registre, on utilise ensuite la commande suivante.
docker push ghcr.io/evs-gis/mapdoapp -a

# Pour pousser seulement un tag spécifique, on préfèrera la commande suivante.
docker push ghcr.io/evs-gis/mapdoapp:latest
</syntaxhighlight>

== Configuration de l'application sur le serveur ShinyProxy de production ==
La configuration initiale de l'application doit être faite par l'administrateur du serveur.

== Mise à jour d'une appli ==
La mise à jour d'une appli sur le serveur de prod ne nécessite généralement pas de modifier la configuration. Il suffit de '''pousser la nouvelle version de votre image sur votre registre''' (avec le tag latest), puis de '''lancer le job ''Mise à jour d'une application en production sous ShinyProxy'' sur Jenkins''' pour forcer le redémarrage des containers d'attente déjà lancés. Si l'intégration continue a été correctement configurée, le job Jenkins de mise à jour devrait se lancer automatiquement dès que la nouvelle version de l'image arrive sur le registre.

== Debug des applis en prod ==

Pour accéder aux logs des applications sur le serveur de prod, se connecter en ssh aux archives:<syntaxhighlight lang="bash">
ssh archives.evs.ens-lyon.fr
</syntaxhighlight>Puis afficher le contenu des logs:<syntaxhighlight lang="bash">
tail -n 10 /data/echanges/ShinyProxyLogs/shinyapps-stdout.log
# récupérer les 10 (option -n) dernières lignes de stdout

tail -n 10 -f /data/echanges/ShinyProxyLogs/shinyapps-stderr.log
# voir stderr défiler en temps réel (option -f)

tail -n 10 /data/echanges/ShinyProxyLogs/shinyapps-std*.log
# voir les 10 dernières lignes de tous les logs (standard et erreur)

tail -n 100 ...
# pour les 100 dernières lignes, etc
</syntaxhighlight>Tous les logs (quelque soit l'appli) apparaissent. Pour chercher spécifiquement les lignes correspondant à une appli précise (par exemple mapdoapp):<syntaxhighlight lang="bash">
grep mapdoapp /data/echanges/ShinyProxyLogs/shinyapps-std*.log
# N'affiche que les lignes qui concernent mapdoapp
</syntaxhighlight>On peut aussi combiner défilement en live + grep<syntaxhighlight lang="bash">
tail -f /data/echanges/ShinyProxyLogs/shinyapps-std*.log | grep mapdoapp
</syntaxhighlight>

== To do list mise en ligne d'une nouvelle appli ==
1) récupérer dans le dossier d'une appli déjà mise en ligne sur ShinyProxy: run.R (si appli learnr), dockerfile, et le dossier .github qui contient un yaml qui permettra de build et push l'image docker sur le ShinyProxy.

2) modifier dans run.R (si appli learnr) le nom du Rmd à tricoter

3) modifier dans le yaml le nom de l'image docker (deux lignes à changer)

4) modifier le dockerfile: infos sur l'appli et noms des packages à installer

5) build l'image docker localement pour vérifier que tout est ok, par ex. <syntaxhighlight lang="bash">
docker build . -t ghcr.io/lvaudor/learnr_exos_shiny:latest
</syntaxhighlight>6) run un container pour vérifier que tout est ok, par ex.<syntaxhighlight lang="bash">
docker run --rm -p 3840:3840 ghcr.io/learnr_shiny_exos:latest
</syntaxhighlight>7) Aller sur le repo github et changer paramètres: Settings => Actions => General => Workflow permissions => Cocher Read and write permissions

8) Faire un commit et push des dernières modifs sur main => Une image docker doit être créée dans les github Actions

9) Prévenir Samuel pour qu'il ajoute la nouvelle appli au registre
[[Catégorie:Tutoriel]]

ShinyProxy

2026-04-10T09:01:06Z

Lvaudor : TODO ajout d'une nouvelle appli

'''<big>Attention : Page en cours de rédaction</big>'''

ISIG-Apps passe sous ShinyProxy pour améliorer la stabilité et l'isolation de vos applications pendant les montées en charge. Le fonctionnement est très différent par rapport à l'ancien Shiny-Server et nécessite quelques bases dans l'utilisation de Docker. L'objectif de cette page est de vous guider, rapidement et simplement, dans le nouveau workflow dev > prod en partant du principe que vous ne connaissez encore pas grand-chose à Docker.

== Principe de fonctionnement de ShinyProxy (et Docker) ==
ShinyProxy fonctionne comme un orchestrateur de conteneurs Docker. Chaque appli configurée doit avoir une image Docker associée présente sur le serveur qui exécute ShinyProxy. C'est ShinyProxy qui s'occupera ensuite de lancer et stopper un conteneur à chaque fois qu'un internaute se connectera ou se déconnectera de votre appli.
[[Fichier:Schéma Docker.png|centré|sans_cadre|1054x1054px]]

Afin que votre application puisse fonctionner sur ShinyProxy, il va donc falloir créer une '''image''' qui permettra au serveur ShinyProxy de lancer des '''containers''' de votre application.

Vous n'aurez généralement pas besoin de volume pour stocker des données pérennes dans le cas d'une application Shiny. Si votre application utilise une base de données, celle-ci devra être externalisée (hébergée sur le serveur de bases de données d'ISIG par exemple).

ShinyProxy fera en sorte qu'un certain nombre de containers (à définir dans la configuration décrite à la fin de ce tutoriel) soient toujours disponibles pour de nouveaux utilisateurs qui se connecteraient à votre application. Il s'occupera également de supprimer les containers quand vos utilisateurs se déconnectent.

== Conteneurisation de votre appli Shiny ==
La conteneurisation peut se faire directement sur votre machine personelle si vous y avez installé Docker (https://docs.docker.com/engine/install/), ou sur le serveur isig-apps de dev via [https://rstudio.evs.ens-lyon.fr Rstudio server] et son terminal intégré.

=== Fixer le port ===
Pour fonctionner en mode conteneurisé, votre application devra écouter toujours sur le même port (ce qui n'est pas le comportement par défaut d'une application Shiny).

Afin de s'en assurer, il faut :

* Dans le cas d'un appli Shiny classique, ajouter dans <code>options(..)</code>, avant l'appel de <code>shinyApp(..)</code>, les options suivantes : <code>"shiny.port"=3841</code> et <code>"shiny.host"="0.0.0.0"</code>. Par exemple :
<syntaxhighlight lang="r">
library(shiny)
library(glourbi)

# Dans cet exemple, l'application écoutera systématiquement sur le port 3838
options("shiny.port" = 3838, "shiny.host" = "0.0.0.0", "golem.app.prod" = TRUE)

shinyApp(ui=glourbapp:::app_ui,server=glourbapp:::app_server)
</syntaxhighlight>

* Dans le cas d'un document Rmarkdown, ........

=== Choisir l'image source ===
La construction d'une image Docker se fait sur la base... d'une autre. On choisi en général son image de base en fonction de ce qu'on va faire avec. Pour une application Shiny, nous aurons besoin d'une image Docker spécialisée en R.

Le [https://rocker-project.org/images/ projet Rocker] propose plusieurs images de base avec différentes quantités de packages pré-installés. Lorsque l'on choisi son image de base, il faut trouver le bon compromis entre une image légère et une image avec suffisamment de dépendances pré-installées pour qu'elle soit pratique.

L'image [https://eddelbuettel.github.io/r2u/ r2u] est une bonne base assez simple à utiliser, car elle va chercher des binaires précompilés des packages R que l'on souhaite installer et toutes leurs dépendances, librairies système incluses ! Pratiquement rien n'y est pré-installé, il faudra donc bien préciser toutes les dépendances dont vous avez besoin. En contrepartie, l'image sera plutôt légère, ce qui est une bonne chose ! L'inconvénient de cette fonctionnalité est (à ma connaissance) qu'elle ne fonctionne qu'avec la fonction <code>install.packages(...)</code>. Il n'est donc pas possible d'installer une version spécifique d'un package avec <code>remotes::install_version(...)</code> par exemple (la fonction reste utilisable de manière classique).

=== Écrire le Dockerfile ===

La création d'une image Docker repose sur l'écriture d'un fichier texte appelé '''Dockerfile''' (sans extension).

Voici un exemple de Dockerfile pour l'application GloUrb :<syntaxhighlight lang="dockerfile">
# On commence par définir l'image sur laquelle va se baser la notre
FROM rocker/r2u:jammy

# On précise quelques infos qui permettrons d'identifier l'image
LABEL org.opencontainers.image.authors="Lise Vaudor <lise.vaudor@ens-lyon.fr>, Samuel Dunesme <samuel.dunesme@ens-lyon.fr>"
LABEL org.opencontainers.image.source="https://github.com/glourb/glourbapp"
LABEL org.opencontainers.image.documentation="https://evs-gis.github.io/glourbdoc/"
LABEL org.opencontainers.image.version="0.0.0.9000"
LABEL org.opencontainers.image.description="An app for the GloUrb project"

# On peut éventuellement générer des locales supplémentaires si notre appli utilise d'autres langues que l'anglais
RUN locale-gen fr_FR.UTF-8

# On liste maintenant toutes les dépendances R à installer
RUN Rscript -e 'install.packages("tidyr")'
RUN Rscript -e 'install.packages("shiny")'
RUN Rscript -e 'install.packages("config")'
RUN Rscript -e 'install.packages("testthat")'
RUN Rscript -e 'install.packages("tibble")'
RUN Rscript -e 'install.packages("purrr")'
RUN Rscript -e 'install.packages("dplyr")'
RUN Rscript -e 'install.packages("ggplot2")'
RUN Rscript -e 'install.packages("forcats")'
RUN Rscript -e 'install.packages("magrittr")'
RUN Rscript -e 'install.packages("golem")'
RUN Rscript -e 'install.packages("sf")'
RUN Rscript -e 'install.packages("plotly")'
RUN Rscript -e 'install.packages("spelling")'
RUN Rscript -e 'install.packages("mclust")'
RUN Rscript -e 'install.packages("leaflet")'
RUN Rscript -e 'install.packages("cluster")'
RUN Rscript -e 'install.packages("cowplot")'
RUN Rscript -e 'install.packages("FactoMineR")'
RUN Rscript -e 'install.packages("glue")'
RUN Rscript -e 'install.packages("grDevices")'
RUN Rscript -e 'install.packages("RColorBrewer")'
RUN Rscript -e 'install.packages("remotes")'
RUN Rscript -e 'install.packages("cicerone")'
RUN Rscript -e 'install.packages("RPostgres")'
RUN Rscript -e 'install.packages("DBI")'
RUN Rscript -e 'install.packages("DT")'

RUN Rscript -e 'remotes::install_github("glourb/glourbi")'

# On copie l'arborescence de fichiers dans un dossier app à la racine de l'image. Ce sera le working directory des containers lancés avec notre image
RUN mkdir /app
ADD . /app
WORKDIR /app

# Si besoin, on peut installer notre package
RUN R -e 'remotes::install_local()'

# On détermine le port qui sera exposé (attention à bien fixer le port sur lequel votre appli écoute, cf. ci-dessus)
EXPOSE 3838

# Pour plus de sécurité, on fait en sorte que les containers ne se lancent pas avec l'utilisateur "root", mais avec un utilisateur "app" dédié
RUN groupadd -g 1010 app && useradd -c 'app' -u 1010 -g 1010 -m -d /home/app -s /sbin/nologin app
USER app

# Enfin, on précise la commande qui permet de lancer notre appli. C'est cette commande qui sera lancée par défaut par tout nouveau container lancé avec notre image
CMD ["R", "-f", "app.R"]
</syntaxhighlight>

=== Construire l'image Docker ===
Pour construire l'image docker à l'aide du Dockerfile, il faut lancer la commande <code>docker build</code>. C'est à ce moment que l'on va versionner l'image en la taguant avec l'argument <code>-t</code>. On peut mettre directement plusieurs tags à une image, ou les ajouter à posteriori en relançant la commande <code>docker build</code>. Si le Dockerfile n'a pas changé depuis le dernier build, <code>docker build</code> ne fera qu'ajouter les tags à l'image existante.

Pour que la CLI Docker trouve bien le Dockerfile, on lance le terminal dans le dossier ou ce Dockerfile est enregistré.

<code>docker build . -t ghcr.io/evs-gis/mapdoapp:latest -t ghcr.io/evs-gis/mapdoapp:2.0.1 -t ghcr.io/evs-gis/mapdoapp:$(git rev-parse --short HEAD)</code>

Remarquez que le tag doit contenir le chemin complet vers le registre où sera poussée l'image (étape suivante). Si vous ne précisez pas le chemin (par exemple <code>mapdoapp:latest</code>), le registre utilisé sera DockerHub.

Notez le tag <code>$(git rev-parse --short HEAD)</code> qui permet de taguer l'image avec le hash (la référence) du commit actuel (ne fonctionne que si vous êtes dans un dépôt git). Ce tag est bien pratique si vous n'incrémentez pas un numéro de version par ailleurs (<code>2.0.1</code> dans l'exemple ci-dessus).

Le tag <code>latest</code> est à mettre sur la dernière version de votre image. Il sera automatiquement retiré de toutes les autres versions de votre image.

La commande <code>docker images</code> permet ensuite de lister les tags disponibles localement. Si le build a réussi, vous devriez y voir votre image.<syntaxhighlight lang="bash">
~$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
ghcr.io/evs-gis/mapdoapp 2.0.1 b2b999e7d781 3 days ago 1.27GB
ghcr.io/evs-gis/mapdoapp 7ad814c b2b999e7d781 3 days ago 1.27GB
ghcr.io/evs-gis/mapdoapp latest b2b999e7d781 3 days ago 1.27GB
ghcr.io/glourb/glourbapp 642e23b 8a3daa97546e 4 days ago 1.38GB
ghcr.io/glourb/glourbapp latest 8a3daa97546e 4 days ago 1.38GB
ghcr.io/glourb/glourbapp 502564d 9a2050fc09d4 4 days ago 1.38GB
semaphoreui/semaphore v2.12.4 136bec584184 2 weeks ago 727MB
ghcr.io/mastergeonum/cartondes main a95ee654e34a 5 weeks ago 205MB
dockurr/windows latest c3419fd6e55a 2 months ago 384MB
docker.osgeo.org/geoserver 2.26.1 a91188b23092 3 months ago 608MB
rocker/verse 4.4.1 202c993befdc 3 months ago 3.77GB
ghcr.io/evs-gis/glourbee-ui 1.1.0 03e05bed5617 4 months ago 1.47GB

</syntaxhighlight>Remarquez que <code>ghcr.io/evs-gis/mapdoapp</code> est présente plusieurs fois avec des tags différents, mais le même IMAGE ID. Il s'agit bien de la même image et elle n'est pas dupliquée sur le disque.

Pour supprimer un tag, on utilisera la commande <code>docker image rm ghcr.io/evs-gis/mapdoapp:2.0.1</code>. Si plus aucun tag n'existe pour l'image, elle sera complètement supprimée du disque local.

=== Tester l'image ===
Pour tester son image, on peut utiliser la commande <code>docker run</code> :

<code>docker run --rm -p 3838:3838 ghcr.io/evs-gis/mapdoapp:latest</code>

* --rm : Supprimer le container lorsqu'il est arrêté.
* -p 3838:3838 : exposer le port 3838 local et le faire pointer vers le port 3838 dans le container.

Les logs de l'application s'affichent dans le terminal et l'application est accessible dans un navigateur à l'adresse http://localhost:3838. Pour stopper le container, '''Ctrl+C'''.

=== Faire du ménage localement ===
Il arrive que des vieilles images sans tag, de vieux volumes et de vieux containers plantés restent sur le disque au fil du temps. Tester la commande <code>docker ps --all</code> par exemple, pour lister tous les containers locaux (lancés ou stoppés). La commande <code>docker system prune</code> permet de faire le grand ménage.

=== Pousser l'image sur un registre ===
Pour que le serveur ShinyProxy (ainsi que le monde entier !) puisse accéder à votre image, il faut la pousser sur un registre. Si vous ne souhaitez pas que votre image soit publique, vous pouvez utiliser le registre ghcr.io/evs-gis (le serveur ShinyProxy y a accès même si les images sont privées).

Il faut d'abord se loguer sur le registre avec son login GitHub habituel, et un ''Personal Access Token'' en guise de mot de passe. Pour [https://github.com/settings/tokens/new obtenir un ''Personal Access Token''], rendez-vous [https://github.com/settings/tokens/new ici] et activez bien le droit <code>write:packages</code> pour votre token. <syntaxhighlight lang="sh">
# La commande suivante est à lancer pour se loguer sur le registre. Il n'est pas nécessaire de la relancer à chaque fois.
docker login ghcr.io

# Pour pousser tous les tags de notre image sur le registre, on utilise ensuite la commande suivante.
docker push ghcr.io/evs-gis/mapdoapp -a

# Pour pousser seulement un tag spécifique, on préfèrera la commande suivante.
docker push ghcr.io/evs-gis/mapdoapp:latest
</syntaxhighlight>

== Configuration de l'application sur le serveur ShinyProxy de production ==
La configuration initiale de l'application doit être faite par l'administrateur du serveur.

== Mise à jour d'une appli ==
La mise à jour d'une appli sur le serveur de prod ne nécessite généralement pas de modifier la configuration. Il suffit de '''pousser la nouvelle version de votre image sur votre registre''' (avec le tag latest), puis de '''lancer le job ''Mise à jour d'une application en production sous ShinyProxy'' sur Jenkins''' pour forcer le redémarrage des containers d'attente déjà lancés. Si l'intégration continue a été correctement configurée, le job Jenkins de mise à jour devrait se lancer automatiquement dès que la nouvelle version de l'image arrive sur le registre.

== Debug des applis en prod ==

Pour accéder aux logs des applications sur le serveur de prod, se connecter en ssh aux archives:<syntaxhighlight lang="bash">
ssh archives.evs.ens-lyon.fr
</syntaxhighlight>Puis afficher le contenu des logs:<syntaxhighlight lang="bash">
tail -n 10 /data/echanges/ShinyProxyLogs/shinyapps-stdout.log
# récupérer les 10 (option -n) dernières lignes de stdout

tail -n 10 -f /data/echanges/ShinyProxyLogs/shinyapps-stderr.log
# voir stderr défiler en temps réel (option -f)

tail -n 10 /data/echanges/ShinyProxyLogs/shinyapps-std*.log
# voir les 10 dernières lignes de tous les logs (standard et erreur)

tail -n 100 ...
# pour les 100 dernières lignes, etc
</syntaxhighlight>Tous les logs (quelque soit l'appli) apparaissent. Pour chercher spécifiquement les lignes correspondant à une appli précise (par exemple mapdoapp):<syntaxhighlight lang="bash">
grep mapdoapp /data/echanges/ShinyProxyLogs/shinyapps-std*.log
# N'affiche que les lignes qui concernent mapdoapp
</syntaxhighlight>On peut aussi combiner défilement en live + grep<syntaxhighlight lang="bash">
tail -f /data/echanges/ShinyProxyLogs/shinyapps-std*.log | grep mapdoapp
</syntaxhighlight>

== To do list mise en ligne d'une nouvelle appli ==
1) récupérer dans le dossier d'une appli déjà mise en ligne sur ShinyProxy: run.R (si appli learnr), dockerfile, et le dossier .github qui contient un yaml qui permettra de build et push l'image docker sur le ShinyProxy.

2) modifier dans run.R (si appli learnr) le nom du Rmd à tricoter

3) modifier dans le yaml le nom de l'image docker

4) modifier le dockerfile: infos sur l'appli et noms des packages à installer

5) build l'image docker localement pour vérifier que tout est ok, par ex. <syntaxhighlight lang="bash">
docker build . -t ghcr.io/lvaudor/learnr_exos_shiny:latest
</syntaxhighlight>6) run un container pour vérifier que tout est ok, par ex.<syntaxhighlight lang="bash">
docker run --rm -p 3840:3840 ghcr.io/learnr_shiny_exos:latest
</syntaxhighlight>7) Aller sur le repo github et changer paramètres: Settings => Actions => General => Workflow permissions => Cocher Read and write permissions

8) Faire un commit et push des dernières modifs sur main => Une image docker doit être créée dans les github Actions

9) Prévenir Samuel pour qu'il ajoute la nouvelle appli au registre
[[Catégorie:Tutoriel]]

ShinyProxy

2026-03-04T13:21:04Z

Lvaudor :

'''<big>Attention : Page en cours de rédaction</big>'''

ISIG-Apps passe sous ShinyProxy pour améliorer la stabilité et l'isolation de vos applications pendant les montées en charge. Le fonctionnement est très différent par rapport à l'ancien Shiny-Server et nécessite quelques bases dans l'utilisation de Docker. L'objectif de cette page est de vous guider, rapidement et simplement, dans le nouveau workflow dev > prod en partant du principe que vous ne connaissez encore pas grand-chose à Docker.

== Principe de fonctionnement de ShinyProxy (et Docker) ==
ShinyProxy fonctionne comme un orchestrateur de conteneurs Docker. Chaque appli configurée doit avoir une image Docker associée présente sur le serveur qui exécute ShinyProxy. C'est ShinyProxy qui s'occupera ensuite de lancer et stopper un conteneur à chaque fois qu'un internaute se connectera ou se déconnectera de votre appli.
[[Fichier:Schéma Docker.png|centré|sans_cadre|1054x1054px]]

Afin que votre application puisse fonctionner sur ShinyProxy, il va donc falloir créer une '''image''' qui permettra au serveur ShinyProxy de lancer des '''containers''' de votre application.

Vous n'aurez généralement pas besoin de volume pour stocker des données pérennes dans le cas d'une application Shiny. Si votre application utilise une base de données, celle-ci devra être externalisée (hébergée sur le serveur de bases de données d'ISIG par exemple).

ShinyProxy fera en sorte qu'un certain nombre de containers (à définir dans la configuration décrite à la fin de ce tutoriel) soient toujours disponibles pour de nouveaux utilisateurs qui se connecteraient à votre application. Il s'occupera également de supprimer les containers quand vos utilisateurs se déconnectent.

== Conteneurisation de votre appli Shiny ==
La conteneurisation peut se faire directement sur votre machine personelle si vous y avez installé Docker (https://docs.docker.com/engine/install/), ou sur le serveur isig-apps de dev via [https://rstudio.evs.ens-lyon.fr Rstudio server] et son terminal intégré.

=== Fixer le port ===
Pour fonctionner en mode conteneurisé, votre application devra écouter toujours sur le même port (ce qui n'est pas le comportement par défaut d'une application Shiny).

Afin de s'en assurer, il faut :

* Dans le cas d'un appli Shiny classique, ajouter dans <code>options(..)</code>, avant l'appel de <code>shinyApp(..)</code>, les options suivantes : <code>"shiny.port"=3841</code> et <code>"shiny.host"="0.0.0.0"</code>. Par exemple :
<syntaxhighlight lang="r">
library(shiny)
library(glourbi)

# Dans cet exemple, l'application écoutera systématiquement sur le port 3838
options("shiny.port" = 3838, "shiny.host" = "0.0.0.0", "golem.app.prod" = TRUE)

shinyApp(ui=glourbapp:::app_ui,server=glourbapp:::app_server)
</syntaxhighlight>

* Dans le cas d'un document Rmarkdown, ........

=== Choisir l'image source ===
La construction d'une image Docker se fait sur la base... d'une autre. On choisi en général son image de base en fonction de ce qu'on va faire avec. Pour une application Shiny, nous aurons besoin d'une image Docker spécialisée en R.

Le [https://rocker-project.org/images/ projet Rocker] propose plusieurs images de base avec différentes quantités de packages pré-installés. Lorsque l'on choisi son image de base, il faut trouver le bon compromis entre une image légère et une image avec suffisamment de dépendances pré-installées pour qu'elle soit pratique.

L'image [https://eddelbuettel.github.io/r2u/ r2u] est une bonne base assez simple à utiliser, car elle va chercher des binaires précompilés des packages R que l'on souhaite installer et toutes leurs dépendances, librairies système incluses ! Pratiquement rien n'y est pré-installé, il faudra donc bien préciser toutes les dépendances dont vous avez besoin. En contrepartie, l'image sera plutôt légère, ce qui est une bonne chose ! L'inconvénient de cette fonctionnalité est (à ma connaissance) qu'elle ne fonctionne qu'avec la fonction <code>install.packages(...)</code>. Il n'est donc pas possible d'installer une version spécifique d'un package avec <code>remotes::install_version(...)</code> par exemple (la fonction reste utilisable de manière classique).

=== Écrire le Dockerfile ===

La création d'une image Docker repose sur l'écriture d'un fichier texte appelé '''Dockerfile''' (sans extension).

Voici un exemple de Dockerfile pour l'application GloUrb :<syntaxhighlight lang="dockerfile">
# On commence par définir l'image sur laquelle va se baser la notre
FROM rocker/r2u:jammy

# On précise quelques infos qui permettrons d'identifier l'image
LABEL org.opencontainers.image.authors="Lise Vaudor <lise.vaudor@ens-lyon.fr>, Samuel Dunesme <samuel.dunesme@ens-lyon.fr>"
LABEL org.opencontainers.image.source="https://github.com/glourb/glourbapp"
LABEL org.opencontainers.image.documentation="https://evs-gis.github.io/glourbdoc/"
LABEL org.opencontainers.image.version="0.0.0.9000"
LABEL org.opencontainers.image.description="An app for the GloUrb project"

# On peut éventuellement générer des locales supplémentaires si notre appli utilise d'autres langues que l'anglais
RUN locale-gen fr_FR.UTF-8

# On liste maintenant toutes les dépendances R à installer
RUN Rscript -e 'install.packages("tidyr")'
RUN Rscript -e 'install.packages("shiny")'
RUN Rscript -e 'install.packages("config")'
RUN Rscript -e 'install.packages("testthat")'
RUN Rscript -e 'install.packages("tibble")'
RUN Rscript -e 'install.packages("purrr")'
RUN Rscript -e 'install.packages("dplyr")'
RUN Rscript -e 'install.packages("ggplot2")'
RUN Rscript -e 'install.packages("forcats")'
RUN Rscript -e 'install.packages("magrittr")'
RUN Rscript -e 'install.packages("golem")'
RUN Rscript -e 'install.packages("sf")'
RUN Rscript -e 'install.packages("plotly")'
RUN Rscript -e 'install.packages("spelling")'
RUN Rscript -e 'install.packages("mclust")'
RUN Rscript -e 'install.packages("leaflet")'
RUN Rscript -e 'install.packages("cluster")'
RUN Rscript -e 'install.packages("cowplot")'
RUN Rscript -e 'install.packages("FactoMineR")'
RUN Rscript -e 'install.packages("glue")'
RUN Rscript -e 'install.packages("grDevices")'
RUN Rscript -e 'install.packages("RColorBrewer")'
RUN Rscript -e 'install.packages("remotes")'
RUN Rscript -e 'install.packages("cicerone")'
RUN Rscript -e 'install.packages("RPostgres")'
RUN Rscript -e 'install.packages("DBI")'
RUN Rscript -e 'install.packages("DT")'

RUN Rscript -e 'remotes::install_github("glourb/glourbi")'

# On copie l'arborescence de fichiers dans un dossier app à la racine de l'image. Ce sera le working directory des containers lancés avec notre image
RUN mkdir /app
ADD . /app
WORKDIR /app

# Si besoin, on peut installer notre package
RUN R -e 'remotes::install_local()'

# On détermine le port qui sera exposé (attention à bien fixer le port sur lequel votre appli écoute, cf. ci-dessus)
EXPOSE 3838

# Pour plus de sécurité, on fait en sorte que les containers ne se lancent pas avec l'utilisateur "root", mais avec un utilisateur "app" dédié
RUN groupadd -g 1010 app && useradd -c 'app' -u 1010 -g 1010 -m -d /home/app -s /sbin/nologin app
USER app

# Enfin, on précise la commande qui permet de lancer notre appli. C'est cette commande qui sera lancée par défaut par tout nouveau container lancé avec notre image
CMD ["R", "-f", "app.R"]
</syntaxhighlight>

=== Construire l'image Docker ===
Pour construire l'image docker à l'aide du Dockerfile, il faut lancer la commande <code>docker build</code>. C'est à ce moment que l'on va versionner l'image en la taguant avec l'argument <code>-t</code>. On peut mettre directement plusieurs tags à une image, ou les ajouter à posteriori en relançant la commande <code>docker build</code>. Si le Dockerfile n'a pas changé depuis le dernier build, <code>docker build</code> ne fera qu'ajouter les tags à l'image existante.

Pour que la CLI Docker trouve bien le Dockerfile, on lance le terminal dans le dossier ou ce Dockerfile est enregistré.

<code>docker build . -t ghcr.io/evs-gis/mapdoapp:latest -t ghcr.io/evs-gis/mapdoapp:2.0.1 -t ghcr.io/evs-gis/mapdoapp:$(git rev-parse --short HEAD)</code>

Remarquez que le tag doit contenir le chemin complet vers le registre où sera poussée l'image (étape suivante). Si vous ne précisez pas le chemin (par exemple <code>mapdoapp:latest</code>), le registre utilisé sera DockerHub.

Notez le tag <code>$(git rev-parse --short HEAD)</code> qui permet de taguer l'image avec le hash (la référence) du commit actuel (ne fonctionne que si vous êtes dans un dépôt git). Ce tag est bien pratique si vous n'incrémentez pas un numéro de version par ailleurs (<code>2.0.1</code> dans l'exemple ci-dessus).

Le tag <code>latest</code> est à mettre sur la dernière version de votre image. Il sera automatiquement retiré de toutes les autres versions de votre image.

La commande <code>docker images</code> permet ensuite de lister les tags disponibles localement. Si le build a réussi, vous devriez y voir votre image.<syntaxhighlight lang="bash">
~$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
ghcr.io/evs-gis/mapdoapp 2.0.1 b2b999e7d781 3 days ago 1.27GB
ghcr.io/evs-gis/mapdoapp 7ad814c b2b999e7d781 3 days ago 1.27GB
ghcr.io/evs-gis/mapdoapp latest b2b999e7d781 3 days ago 1.27GB
ghcr.io/glourb/glourbapp 642e23b 8a3daa97546e 4 days ago 1.38GB
ghcr.io/glourb/glourbapp latest 8a3daa97546e 4 days ago 1.38GB
ghcr.io/glourb/glourbapp 502564d 9a2050fc09d4 4 days ago 1.38GB
semaphoreui/semaphore v2.12.4 136bec584184 2 weeks ago 727MB
ghcr.io/mastergeonum/cartondes main a95ee654e34a 5 weeks ago 205MB
dockurr/windows latest c3419fd6e55a 2 months ago 384MB
docker.osgeo.org/geoserver 2.26.1 a91188b23092 3 months ago 608MB
rocker/verse 4.4.1 202c993befdc 3 months ago 3.77GB
ghcr.io/evs-gis/glourbee-ui 1.1.0 03e05bed5617 4 months ago 1.47GB

</syntaxhighlight>Remarquez que <code>ghcr.io/evs-gis/mapdoapp</code> est présente plusieurs fois avec des tags différents, mais le même IMAGE ID. Il s'agit bien de la même image et elle n'est pas dupliquée sur le disque.

Pour supprimer un tag, on utilisera la commande <code>docker image rm ghcr.io/evs-gis/mapdoapp:2.0.1</code>. Si plus aucun tag n'existe pour l'image, elle sera complètement supprimée du disque local.

=== Tester l'image ===
Pour tester son image, on peut utiliser la commande <code>docker run</code> :

<code>docker run --rm -p 3838:3838 ghcr.io/evs-gis/mapdoapp:latest</code>

* --rm : Supprimer le container lorsqu'il est arrêté.
* -p 3838:3838 : exposer le port 3838 local et le faire pointer vers le port 3838 dans le container.

Les logs de l'application s'affichent dans le terminal et l'application est accessible dans un navigateur à l'adresse http://localhost:3838. Pour stopper le container, '''Ctrl+C'''.

=== Faire du ménage localement ===
Il arrive que des vieilles images sans tag, de vieux volumes et de vieux containers plantés restent sur le disque au fil du temps. Tester la commande <code>docker ps --all</code> par exemple, pour lister tous les containers locaux (lancés ou stoppés). La commande <code>docker system prune</code> permet de faire le grand ménage.

=== Pousser l'image sur un registre ===
Pour que le serveur ShinyProxy (ainsi que le monde entier !) puisse accéder à votre image, il faut la pousser sur un registre. Si vous ne souhaitez pas que votre image soit publique, vous pouvez utiliser le registre ghcr.io/evs-gis (le serveur ShinyProxy y a accès même si les images sont privées).

Il faut d'abord se loguer sur le registre avec son login GitHub habituel, et un ''Personal Access Token'' en guise de mot de passe. Pour [https://github.com/settings/tokens/new obtenir un ''Personal Access Token''], rendez-vous [https://github.com/settings/tokens/new ici] et activez bien le droit <code>write:packages</code> pour votre token. <syntaxhighlight lang="sh">
# La commande suivante est à lancer pour se loguer sur le registre. Il n'est pas nécessaire de la relancer à chaque fois.
docker login ghcr.io

# Pour pousser tous les tags de notre image sur le registre, on utilise ensuite la commande suivante.
docker push ghcr.io/evs-gis/mapdoapp -a

# Pour pousser seulement un tag spécifique, on préfèrera la commande suivante.
docker push ghcr.io/evs-gis/mapdoapp:latest
</syntaxhighlight>

== Configuration de l'application sur le serveur ShinyProxy de production ==
La configuration initiale de l'application doit être faite par l'administrateur du serveur.

== Mise à jour d'une appli ==
La mise à jour d'une appli sur le serveur de prod ne nécessite généralement pas de modifier la configuration. Il suffit de '''pousser la nouvelle version de votre image sur votre registre''' (avec le tag latest), puis de '''lancer le job ''Mise à jour d'une application en production sous ShinyProxy'' sur Jenkins''' pour forcer le redémarrage des containers d'attente déjà lancés. Si l'intégration continue a été correctement configurée, le job Jenkins de mise à jour devrait se lancer automatiquement dès que la nouvelle version de l'image arrive sur le registre.

== Debug des applis en prod ==

Pour accéder aux logs des applications sur le serveur de prod, se connecter en ssh aux archives:<syntaxhighlight lang="bash">
ssh archives.evs.ens-lyon.fr
</syntaxhighlight>Puis afficher le contenu des logs:<syntaxhighlight lang="bash">
tail -n 10 /data/echanges/ShinyProxyLogs/shinyapps-stdout.log
# récupérer les 10 (option -n) dernières lignes de stdout

tail -n 10 -f /data/echanges/ShinyProxyLogs/shinyapps-stderr.log
# voir stderr défiler en temps réel (option -f)

tail -n 10 /data/echanges/ShinyProxyLogs/shinyapps-std*.log
# voir les 10 dernières lignes de tous les logs (standard et erreur)

tail -n 100 ...
# pour les 100 dernières lignes, etc
</syntaxhighlight>Tous les logs (quelque soit l'appli) apparaissent. Pour chercher spécifiquement les lignes correspondant à une appli précise (par exemple mapdoapp):<syntaxhighlight lang="bash">
grep mapdoapp /data/echanges/ShinyProxyLogs/shinyapps-std*.log
# N'affiche que les lignes qui concernent mapdoapp
</syntaxhighlight>On peut aussi combiner défilement en live + grep<syntaxhighlight lang="bash">
tail -f /data/echanges/ShinyProxyLogs/shinyapps-std*.log | grep mapdoapp
</syntaxhighlight>
[[Catégorie:Tutoriel]]

Fichier:Woody.png

2025-01-31T08:52:46Z

Lvaudor :

Fichier:WaveleT.png

2025-01-31T08:52:35Z

Lvaudor :

Fichier:Riviewlet.png

2025-01-31T08:52:23Z

Lvaudor :

Fichier:Riverbed.png

2025-01-31T08:52:10Z

Lvaudor :

Fichier:MapdO.png

2025-01-31T08:51:55Z

Lvaudor :

Fichier:GloUrb.png

2025-01-31T08:51:45Z

Lvaudor :

Fichier:Glitter.png

2025-01-31T08:51:22Z

Lvaudor :