Voir la source de Espace numérique associatif

[[Category:Services informatiques]]

= 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 d'un espace numérique associatif|création de l'espace numérique]].

Accès à la webmail des assos juste [https://assos.utc.fr/webmail 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 d'un espace numérique associatif|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 [mailto:simde@assos.utc.fr contacter le SiMDE] pour mettre à jour ces infos.

Accès au portail des assos juste [https://assos.utc.fr 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 [[Solutions de paiement|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 [https://admin.weezevent.com/pay/#!/80405 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


TODO : à rédiger

Accès à Wooch juste [https://utc.wooch.fr 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
[[Fichier:Filezilla-1.png|gauche|vignette|540x540px|Bouton nouvelle connexion]]
[[Fichier:Filezilla-2.png|centré|vignette|511x511px|Champs à configurer]]

==== Procédure de connexion SFTP ====

# Ouvrir Filezilla
# Saisir les identifiants fournis par le SiMDE
# Se connecter au serveur '''files.mde.etc'''
# Naviguer vers le dossier de votre association
# Téléverser vos fichiers dans le dossier <code>public_html</code>

=== 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 :''' <code>ssh [votre-asso]@files.mde.etc</code>

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

* <code>composer install</code> et autres commandes composer
* <code>php artisan migrate</code> et autres commandes php

'''Conséquences pour Laravel :'''

* Le dossier <code>/vendor</code> doit être téléversé via SFTP
** Les dépendances doivent être installées localement avant le déploiement ou via [[Espace numérique associatif#probl%C3%A9matique-des-d%C3%A9pendances|d'autres méthodes]]
* La base de données doit être migrée à la main, ou alors avec des méthodes [[Espace numérique associatif#ex%C3%A9cution-de-code-php-sur-le-serveur|un peu moins conventionnelles]]...

== Structure des URLs et déploiement ==

=== Format des URLs ===
Les applications sont servies selon un des deux formats suivants :

*<code><nowiki>https://assos.utc.fr/</nowiki><loginasso></code>
*<code>https://<loginasso>.assos.utc.fr</code>

Si vous souhaitez posséder l'une des deux en particulier, n'hésitez pas à [mailto:simde@assos.utc.fr 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

# Connectez-vous en SFTP
# 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

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

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

# Connectez-vous en SFTP
# 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=<code><url_de_ton_asso></code>
# 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 [mailto:simde@assos.utc.fr contacter le SiMDE].

=== Problématique des dépendances ===
Étant donné l'impossibilité d'utiliser <code>composer</code> 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 [[/github.com/picasso-utc/ocktopus|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 [[/github.com/settings/personal-access-tokens|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 :

# '''Localement :''' <code>composer install --no-dev --optimize-autoloader</code>
# '''Téléversement SFTP :'''
#* Téléverser tous les fichiers incluant le dossier <code>/vendor</code>

=== 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 :'''
[[Fichier:Commande par URL.png|gauche|vignette|373x373px]]




==== Méthode 2 : Scripts à la racine ====

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

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

== Configuration serveur et support ==

=== Modifications de configuration ===
Pour des besoins spécifiques (modification du <code>php.ini</code>, mise à jour de PHP, etc.), [mailto:simde@assos.utc.fr contacter le SiMDE].

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

'''Accès phpMyAdmin :'''

* URL : [https://phpmyadmin.assos.utc.fr 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 [https://auth.assos.utc.fr/admin 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 :  '' <code>"read-assos"=>["simde","skiutc"]</code>

==== 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 :  '' <code>"read-memberships"=>true</code>

=== Implémentation ===
Pour l'implémentation, je vous renvoie vers la [https://auth.assos.utc.fr/admin/implement 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 [https://gitlab.utc.fr/simde notre Gitlab].

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

* Pour du Laravel + Blade : [https://gitlab.utc.fr/simde/shwet Shwet]
* Pour du Laravel + React : [https://gitlab.utc.fr/simde/portail-des-assos Portail des assos]

'''Ski'UTC :'''
* [https://github.com/ski-utc Organisation]
* [https://github.com/ski-utc/server-SkiUt-P25 Serveur backend]

'''Pic'Asso :'''

* [https://github.com/picasso-utc Organisation]
* [https://github.com/picasso-utc/ocktopus BackOffice Laravel]
* Exemple d'implémentation GitHub Actions

== Bonnes pratiques ==

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

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