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.

Si les liens semblent invalides, merci de se référer aux services sur le portail des assos, ou de contacter le SiMDE.

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.

Cloud des assos

Chaque association dispose d'un espace de 20Go pour stocker des fichiers sur le serveur Nextcloud du SiMDE.

L'accès se fait avec le login/mdp principal juste ici.

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

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 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

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

Pour aller plus loin (CI/CD)

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 : chmod 755 ./monScript.sh

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=<url_de_ton_asso>
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 :

Localement : composer install --no-dev --optimize-autoloader
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

Placer un fichier .php ou .sh à la racine de votre application
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.

Site WordPress

WordPress est un système de gestion de contenu (CMS) gratuit, libre, souvent utilisé pour mettre en place un site web rapidement et simplement sans avoir à implémenter beaucoup de code (low-code/no-code). WP est ecrit en PHP, votre site utilisant ce CMS peut donc être hébergé sur notre infrastructure.

Il faudra simplement faire attention à quelques petits points :

en raison de la configuration réseau du serveur, il n'est pas possible de télécharger des thèmes et plugins depuis l'application déployée. Il faut donc les télécharger en local puis les déposer avec le site dans le dossier public_html de l'asso. Penser à bien vérifier les droits sur les dossiers du public_html en cas d'erreur.
Ajouter le snippet suivant au début du fichier wp-config.php :

1define('FORCE_SSL_ADMIN', true);                                                                                                                                         
2define('FORCE_SSL_LOGIN', true);                                                                                                                                         
3// in some setups HTTP_X_FORWARDED_PROTO might contain                                                                                                                   
4// a comma-separated list e.g. http,https                                                                                                                                
5// so check for https existence                                                                                                                                          
6if (strpos($_SERVER['HTTP_X_FORWARDED_PROTO'], 'https') !== false)                                                                                                       
7        $_SERVER['HTTPS']='on';

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 :

Pic'Asso :

Organisation
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