Espace numérique associatif

Introduction

Le SiMDE (Service informatique de la Maison Des Etudiants), commission du BDE, met à disposition des associations de la fédération un ensemble de services numériques. Cette présente documentation à pour objectif de les recenser et de guider les assos à travers leur utilisation.

Mail asso en .assos.utc.fr

Une adresses mail en [login_asso]@assos.utc.fr est attribué à chaque association de la fédération lors de la création de l'espace numérique.

Accès à la webmail des assos juste ici.

Portail des assos

Le portail des assos est le point d'accueil pour la vie associative. Il permet de consulter l'ensemble des associations présentes au sein de la fédération et de les rejoindre.

A la création de votre espace numérique, le SiMDE ajoute votre association au catalogue avec les informations fournies. Si celles-ci viennent à évoluer au fil du temps, alors l'association peut contacter le SiMDE pour mettre à jour ces infos.

Accès au portail des assos juste ici.

WeezPay

WeezPay est la plateforme de notre prestataire WeezEvent pour la gestion des flux financiers au sein de la fédération. Elle permet notamment aux associations de réaliser des ventes à destination des étudiants via cashless ou Payutc. Pour plus d'informations, voir la formation Tréso dispensée par le BDE, ou cette documentation concernant les ventes physiques.

Pour rappel, les accès à WeezPay sont à demander au SiMDE à chaque début de semestre par la présidence/tréso de l'asso.

Accès à la plateforme WeezPay juste ici.

Wooch

Wooch est une billetterie proposée par un prestataire pour permettre aux associations d'organiser des ventes accessibles aux étudiants et au public.

Les rôles pour accéder aux marché (=association) Wooch sont donnés automatiquement aux personnes qui ont rejoint l'association sur le portail des assos en tant que :

• Président.e, vice-président.e, trésorier/trésorière : droits admin sur le marché (y compris la création de ventes)
• Resp informatique : droits de gestion des commandes, gestion des scans, gestion des listes d'adhésion
• Resp communication : droit de gestion des ventes

Si une autre personne souhaite avoir des droits Wooch pour gérer le marché (ou une partie du marché) mais ne dispose pas de ces rôles sur le portail des assos, il est possible pour les admins du marché d'accorder des permissions temporaires dans les paramètres du marché > Accès temporaire.

Créer une vente

1. 
   Sur l'accueil de Wooch, se connecter à son compte en cliquant sur l'icône de la porte en haut à droite, puis choisir la connexion via le portail des associations et le CAS de l'UTC.
2. 
   Cliquer sur l'icône du profil > Mes marchés
3. 
   Choisir le marché (=association) pour lequel on souhaite faire la vente
4. 
   Cliquer sur Ventes à gauche
5. 
   Cliquer sur le bouton Créer une vente en haut à droite
6. Suivre les étapes de création puis confirmer la vente. Elle devra être ensuite validée par l'organisation (=le SiMDE) avant d'être mise en ligne. ⚠️ Pas besoin de nous envoyer un mail pour demander la validation, on en reçoit un automatiquement !

A noter : une vente reste modifiable après sa mise en ligne.

Astuce : au moment de créer les articles, il est possible de la restreindre à une liste particulières de personnes en cliquant sur Restrictions > Restrictions avancées > + > Ajouter une restriction > L'utilisateur est dans la liste > Choisir la liste. Il est possible de créer des listes en cliquant sur listes d'adhésion.

Accès à Wooch juste ici.

Cloud des assos

TODO : à rédiger

Serveur web

Vue d'ensemble de l'architecture

L'infrastructure proposée par le SiMDE est composée de plusieurs machines interconnectées qui permettent à chaque asso de profiter d'un espace informatique, notamment utilisé pour héberger des sites web, web app, serveurs (containerisés ou non).

Cette ressource a pris pour parti de se concentrer essentiellement sur les serveurs Laravel. Loin de supposer que Laravel est mieux que Rust, Node, Symfony... Mais c'est avant toute chose car

• Laravel est un serveur PHP et convient donc parfaitement pour être servi par le serveur Apache du SiMDE
• Laravel c'est facile à comprendre, ça permet une formation rapide pour reprendre en main les services proposés
• Laravel est utilisé dans la majorité des web app / serveurs des assos utcéennes (Intégration, Pic'Asso, SiMDE, Ski'UTC...), une personne qui se forme sur Laravel à l'UTC pourra donc s'y retrouver sur à peu près tous les projets informatiques.

Ce qu'il faut savoir sur l'architecture

Le SiMDE propose à chaque association un espace informatique sur la machine files.mde.etc. Pour modifier les fichiers sur son espace, chaque association possède un accès SFTP et SSH à la machine (accès bien évidemment restreint aux dossiers de l'association). Les fichiers sont ensuite récupérés par un Apache qui sert les fichiers statiques et les applications web.

⚠️ Attention : Apache est très adapté pour servir du HTML/CSS/JS/PHP mais n'est pas adapté au Node.js et Python. Si vous prévoyez d'utiliser un de ces deux langages, nous vous conseillons vivement de conteneuriser votre projet (cas particulier pour le node statique qui peut être exporté).

⚠️ Attention : Au cas par cas, le SiMDE peut également héberger des applications conteneurisées via Docker, mais cela nécessite une demande spécifique et la configuration du container ne revient pas au SIMDE, mais bien à l'association qui en fait la demande.

Accès à l'infrastructure

⚠️ Attention : Pour se connecter en SFTP, SSH ou même à la base de données fournie à l'association, il faut utiliser le VPN fourni par l'UTC (ou directement être connecté à utcetu).

Machine accessible aux associations

Seule la machine files.mde.etc est accessible aux associations pour déposer leurs fichiers et applications.

Accès SFTP avec Filezilla

Les associations peuvent accéder à leurs fichiers via SFTP (en utilisant Filezilla par exemple).

Configuration Filezilla :

• Protocole : SFTP
• Hôte : files.mde.etc
• Type d'authentification : Normale
• Identifiants : Fournis par le SiMDE

Bouton nouvelle connexion

Champs à configurer

Procédure de connexion SFTP

1. Ouvrir Filezilla
2. Saisir les identifiants fournis par le SiMDE
3. Se connecter au serveur files.mde.etc
4. Naviguer vers le dossier de votre association
5. Téléverser vos fichiers dans le dossier public_html

Accès SSH

L'accès SSH à la machine files.mde.utc est disponible mais avec des limitations importantes garantissant la sécurité et la confidentialité des assos malgré un hébergement mutualisé sur la même VM

Connexion SSH : ssh [votre-asso]@files.mde.etc

Limitations SSH

⚠️ Attention : Certaines commandes ne sont pas disponibles via SSH, notamment pour Laravel :

• composer install et autres commandes composer
• php artisan migrate et autres commandes php

Conséquences pour Laravel :

• Le dossier /vendor doit être téléversé via SFTP
  • Les dépendances doivent être installées localement avant le déploiement ou via d'autres méthodes
• La base de données doit être migrée à la main, ou alors avec des méthodes un peu moins conventionnelles...

Structure des URLs et déploiement

Format des URLs

Les applications sont servies selon un des deux formats suivants :

• https://assos.utc.fr/<loginasso>
• https://<loginasso>.assos.utc.fr

Si vous souhaitez posséder l'une des deux en particulier, n'hésitez pas à contacter le SiMDE.

Si vous développez un serveur, pensez donc bien à configurer son .env pour servir la bonne URL. Dans le cas contraire, vous risquez d'avoir quelques soucis de redirection...

Stratégies de déploiement

Sites web

Pour les sites web, c'est assez facile

1. Connectez-vous en SFTP
2. Envoyez tout le dossier dans public_html (en faisant en sorte que le fichier index soit accessible)

Tout de même

Si vous êtes motivé.e.s, vous pouvez mettre votre repo Git en public et créer un petit script shell pour cloner le repo et le déployer automatiquement (ça évite de se reconnecter en SFTP à chaque fois). Pour cela il suffit de

1. Créer un script en SSH ou en local et l'envoyer en SFTP
2. Lui donner les droits d'exécution : chmod 755 ./monScript.sh

Serveurs

Pour les serveurs, c'est un peu plus compliqué

1. Connectez-vous en SFTP
2. Envoyez tout votre serveur dans le dossier public_html
   • Cette étape peut être longue à cause du dossier de dépendances vendor/, on en reparle juste après
   • Pensez à bien modifier votre .env pour passer en mode APP_ENV=prod, APP_DEBUG=false et surtout APP_URL=<url_de_ton_asso>
3. En théorie, ça devrait déjà tourner (pas besoin de faire php artisan serve, Apache tourne déjà pleine balle)

Si vous êtes sur Laravel, pas besoin d'avoir index.php à la racine : il est dans le dossier public/ qui est accessible

Il peut arriver que certains problèmes surviennent lors du déploiement de votre serveur

• Votre URL théorique ne trouve pas le fichier index
• Le index est trouvé mais n'est pas servi. Cela peut être dû à de mauvaises config de .htaccess ou de mauvaise version d'interpréteur sur les machines. Dans ces deux cas (et probablement dans d'autres), vous ne pourrez pas faire grand-chose et vous allez devoir contacter le SiMDE.

Problématique des dépendances

Étant donné l'impossibilité d'utiliser composer directement sur le serveur, plusieurs stratégies sont recommandées :

Solution recommandée : GitHub Actions

La meilleure pratique consiste à automatiser le build et le déploiement via des Actions Git. Nous allons prendre ici GitHub comme exemple, mais le GitLab de l'UTC fait également une très bonne alternative.

Avantages :

• Installation automatique des dépendances
• Build de l'application
• Les PR sont refusées en cas d'erreur
• Création d'un artifact (zip du projet) prêt au déploiement
• Déploiement automatisé

Exemple d'implémentation : Consultez le repo Ocktopus de Pic'Asso

Cette implémentation se base sur 2 composantes :

• Une GitHub Action définie dans .github/actions/deploy.yml
  • Cette action observe chaque push ou merge sur une branche, récupérer le code, installer les deps, (build l'app) puis créer un artifact zip/tar.gz du projet.
• Une structure particulière dans /storage/app/deploy
  • Un fichier deploy.sh qui gère le déploiement (nécessite la création d'un PAT Github)
  • Un dossier tmp pour extraire l'artifact avant de synchroniser les changements avec la prod

Déploiement manuel

Si vous ne pouvez pas utiliser GitHub Actions :

1. Localement : composer install --no-dev --optimize-autoloader
2. Téléversement SFTP :
   • Téléverser tous les fichiers incluant le dossier /vendor

Exécution de code PHP sur le serveur

Méthode 1 : Routes d'administration

Créer des routes spécifiques dans votre application pour exécuter du code :

Exemple Laravel :

Méthode 2 : Scripts à la racine

1. Placer un fichier .php ou .sh à la racine de votre application
2. L'exécuter via URL : https://<url_de_ton_asso>/script.php

⚠️ Sécurité : Supprimer ces scripts directement après utilisation !

Configuration serveur et support

Modifications de configuration

Pour des besoins spécifiques (modification du php.ini, mise à jour de PHP, etc.), contacter le SiMDE.

Base de données

Le SIMDE fournit une base de données MySQL à chaque asso.

Accès phpMyAdmin :

• URL : ici
• Identifiants : Fournis par le SiMDE

OAuth 2.0

Le SIMDE propose un service d'authentification sur le modèle OAuth 2.0.

Ce service permet la connexion des utilisateur.ice.s par CAS ou par la création d'un compte (par email). L'option de connexion par mail est désactivable si votre service est exclusif aux UTCéen.ne.s. L'OAuth se chargera d'informer l'utilisateur.ice des données que vous souhaitez récupérer.

Interface admin

La première étape pour utiliser l'OAuth du SiMDE, est de déclarer votre application sur l'interface admin. Sur cette page, vous allez devoir

• Saisir l'URL (ou les URLs) de redirection autorisées par l'OAuth.
• La liste des informations (scopes) que vous voulez récupérer sur l'utilisateur.ice

⚠️ Attention : Les scopes déclarés côté admin et serveur doivent être strictement les mêmes et l'url côté serveur doit être strictement déclarée côté admin.

De manière optionnelle, il est possible de configurer la couleur et l'image qui seront affichées lors de la demande d'autorisation d'accès aux informations.

Retours de l'OAuth

Ci-dessous, voici la liste de ce que permet de récupérer chaque scope

Retour de users-infos

• uuid
• email
• firstName
• lastName
• type
  • Connexion CAS : "utc-etu"
  • Connexion mail : "exte"
• status
  • Connexion CAS : "students"/......
  • Connexion mail : "exte"
• active
• created_at
• updated_at
• deleted_at
• picture
• provider
  • Connexion CAS : "cas"
  • Connexion mail : "email"

Retour de read-assos

Ajoute un champ "read-assos", clé d'un array contenant toutes les associations auxquelles l'utilisateur.ice est accepté.e pour ce semestre.

Exemple :   "read-assos"=>["simde","skiutc"]

Retour de read-assos-history

Ce scope ne fonctionne pas pour l'instant

Retour de read-memberships

Ajoute un champ "read-memberships", clé d'un booléen informant si l'utilisateur.ice est cotisant.e

Exemple :   "read-memberships"=>true

Implémentation

Pour l'implémentation, je vous renvoie vers la documentation en ligne. Vous y retrouvez :

• Flow des requêtes
• Endpoints
• Implémentation PHP - Laravel

Exemples et références

Associations de référence

SiMDE :

Plein de projets sont disponibles avec différentes technologies et différentes implémentations, directement disponibles sur notre Gitlab.

Implémentation de l'OAuth dans app/Http/Controllers/AuthController.php pour du Laravel :

• Pour du Laravel + Blade : Shwet
• Pour du Laravel + React : Portail des assos

Ski'UTC :

• Organisation
• Serveur backend

Pic'Asso :

• Organisation
• BackOffice Laravel
• Exemple d'implémentation GitHub Actions

Bonnes pratiques

1. Utiliser des .env pour la configuration
2. Toujours tester localement avant le déploiement
3. Versionner votre code avec Git
4. Documenter les spécificités de votre déploiement
5. Pensez à la passation

Rédigé avec le <3 par Mathis Delmaere pour le SiMDE