diff --git a/.github/workflows/manual.yaml b/.github/workflows/manual.yaml new file mode 100644 index 0000000..99ee5ff --- /dev/null +++ b/.github/workflows/manual.yaml @@ -0,0 +1,44 @@ +on: + # Creating a release requires a tag + push: + tags: + "*" + paths: + - 'docs/manuel/**' + - '.github/workflows/manual.yaml' + +jobs: + build-manual: + runs-on: ubuntu-22.04 + container: + image: rust:latest + options: --user 1001 # So we avoid ownership issues + env: + book-dir: ./docs/manuel + steps: + - uses: actions/checkout@v4 + + - name: Declare some variables + shell: bash + run: | + echo "sha_short=$(git rev-parse --short "$GITHUB_SHA")" >> "$GITHUB_ENV" + echo "branch=$(echo $GITHUB_REF | sed 's/refs\/\(tags\|heads\)\///;s/\//_/g')" >> "$GITHUB_ENV" + + # Install mdbook + - name: Install `mdbook` + run: cargo install mdbook + + # Build the book + - name: Build the book + run: | + mdbook build + mv book manuel-langate-${{ env.sha_short }} + tar zcvf manuel.tar.gz manuel-langate-${{ env.sha_short }} + working-directory: ${{ env.book-dir }} + + # Create a release + - name: Create a release + uses: softprops/action-gh-release@v1 + with: + files: ${{ env.book-dir }}/manuel.tar.gz + diff --git a/README.md b/README.md index e7a845e..ecf3aab 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,13 @@ This repository is here to hold the langate infrastructure. It is composed of the frontend, the backend, and the nginx server. +## Documentation + +Technical documentation is available [here](docs/manuel/src/SUMMARY.md) (in french). + ## Contributing -Please read carefully[the CONTRIBUTING.md file](CONTRIBUTING.md) before any +Please read carefully [the CONTRIBUTING.md file](CONTRIBUTING.md) before any contribution. ## Netcontrol @@ -65,4 +69,4 @@ Docker can take a lot of disk space with all the images. You have a few options to clean it up: - `make clean-all` will remove all the containers and images -- `make clean-custom` will remove all the custom images (the ones we build and not the ones we pull from docker hub) +- `make clean-custom` will remove all the custom images (the ones we build and not the ones we pull from docker hub) \ No newline at end of file diff --git a/docs/manuel/.gitignore b/docs/manuel/.gitignore new file mode 100644 index 0000000..e9c0728 --- /dev/null +++ b/docs/manuel/.gitignore @@ -0,0 +1 @@ +book \ No newline at end of file diff --git a/docs/manuel/book.toml b/docs/manuel/book.toml new file mode 100644 index 0000000..609c154 --- /dev/null +++ b/docs/manuel/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["Hector \"pixup1\" Vernet"] +language = "fr" +multilingual = false +src = "src" +title = "Manuel de la Langate3000" \ No newline at end of file diff --git a/docs/manuel/src/00-backend/README.md b/docs/manuel/src/00-backend/README.md new file mode 100644 index 0000000..6d99ba6 --- /dev/null +++ b/docs/manuel/src/00-backend/README.md @@ -0,0 +1,3 @@ +# Backend + +Le backend de la langate est écrit en Python et utilise [DRF](django-rest-framework.org). \ No newline at end of file diff --git a/docs/manuel/src/00-backend/modeles.md b/docs/manuel/src/00-backend/modeles.md new file mode 100644 index 0000000..97ad510 --- /dev/null +++ b/docs/manuel/src/00-backend/modeles.md @@ -0,0 +1 @@ +# Modèles \ No newline at end of file diff --git a/docs/manuel/src/00-backend/netcontrol.md b/docs/manuel/src/00-backend/netcontrol.md new file mode 100644 index 0000000..0f4b401 --- /dev/null +++ b/docs/manuel/src/00-backend/netcontrol.md @@ -0,0 +1,7 @@ +# Netcontrol + +Netcontrol est le composant de la langate qui interface le backend avec la tête de réseau. + +Il permet à la langate de pouvoir effectuer des opérations de plus bas niveau grace à un niveau de privilège plus élevé sur la tête. + +Il communique via sockets UNIX. Les informations sont précédées d'une annonce de leur taille, sous la forme d'un int de 4 octets. Les informations en elles-mêmes sont toujours des dictionnaires Python encodés en [pickle](https://docs.python.org/3/library/pickle.html). \ No newline at end of file diff --git a/docs/manuel/src/00-backend/urls.md b/docs/manuel/src/00-backend/urls.md new file mode 100644 index 0000000..2b8a14e --- /dev/null +++ b/docs/manuel/src/00-backend/urls.md @@ -0,0 +1 @@ +# URLs \ No newline at end of file diff --git a/docs/manuel/src/00-backend/vues.md b/docs/manuel/src/00-backend/vues.md new file mode 100644 index 0000000..3691e78 --- /dev/null +++ b/docs/manuel/src/00-backend/vues.md @@ -0,0 +1 @@ +# Vues \ No newline at end of file diff --git a/docs/manuel/src/01-frontend/README.md b/docs/manuel/src/01-frontend/README.md new file mode 100644 index 0000000..f0a87c9 --- /dev/null +++ b/docs/manuel/src/01-frontend/README.md @@ -0,0 +1,3 @@ +# Frontend + +Le frontend est écrit en [Vue](https://fr.vuejs.org). \ No newline at end of file diff --git a/docs/manuel/src/01-frontend/gestion.md b/docs/manuel/src/01-frontend/gestion.md new file mode 100644 index 0000000..d95d935 --- /dev/null +++ b/docs/manuel/src/01-frontend/gestion.md @@ -0,0 +1,9 @@ +# Page de gestion + +C'est cette page qui permet aux administrateurs de gérer les joueurs et les appareils connectés au réseau. Elle permet de : + +- Ajouter / supprimer des utilisateurs +- Whitelist des appareils +- Kick / Ban des joueurs ou des appareils + +Django dispose d'une page de management native assez capable, mais nous avons choisi d'en faire une custom. \ No newline at end of file diff --git a/docs/manuel/src/01-frontend/style.md b/docs/manuel/src/01-frontend/style.md new file mode 100644 index 0000000..665ef27 --- /dev/null +++ b/docs/manuel/src/01-frontend/style.md @@ -0,0 +1,3 @@ +# Style + +Le thème de la langate est réalisé en Tailwind. diff --git a/docs/manuel/src/01-frontend/vues.md b/docs/manuel/src/01-frontend/vues.md new file mode 100644 index 0000000..30ef74c --- /dev/null +++ b/docs/manuel/src/01-frontend/vues.md @@ -0,0 +1,11 @@ +# Vues + +Le front est composé des vues suivantes : + +- Page de connexion +- Page d'accueil +- Page d'erreur +- Page de la FAQ +- [Page de gestion](gestion.md) +- Page de création de ticket +- Page de gestion des tickets \ No newline at end of file diff --git a/docs/manuel/src/README.md b/docs/manuel/src/README.md new file mode 100644 index 0000000..dcfb152 --- /dev/null +++ b/docs/manuel/src/README.md @@ -0,0 +1,49 @@ +# Introduction + +Ce manuel a pour but de documenter le fonctionnement de la [langate 3000](https://github.com/InsaLan/langate3000) (réécrite en 2024). La langate étant bâtie sur beaucoup des mêmes technologies que le site web, une documentation plus extensive sur ces technologies est disponible dans le [manuel de prise en main du backend](https://docs.insalan.fr/backend/). + +Le manuel de la langate est présenté, comme celui du site, sous une license [Creative Commons BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/). + +## Langate ? + +La langate est le portail captif de l'InsaLan, utilisé en Mini et à la LAN. Elle fournit les fonctionnalités suivantes : +- Gestion d'utilisateurs (statut de paiement, gestion des privilèges) +- Synchronisation des comptes utilisateurs avec le site web +- Gestion d'appareils (whitelist) +- Panneau de gestion custom +- Tickets +- Annonces + +## Historique + +Au commencement, il n'y avait rien. Puis il y eut l'InsaLan. La première date d'utilisation d'un portail captif n'est pas connue, peut-être que les archives sont incomplètes, cependant on en trouve plusieurs mentions sur l'ancien wiki. + +La [langate 2000](https://github.com/InsaLan/langate2000) fut mise en service en 2019 pour l'InsaLan XIV. Elle était codée avec des technologies similaires à la langate actuelle (surtout le back, qui était déjà en Django), mais sans documentation. + +Il a donc été décidé de créer cette version de la langate. Elle nous permettra d'avoir une documentation et une compréhension complète de son fonctionnement, et elle sera ainsi plus facile à maintenir et améliorer. + +## Technologies + +Cette langate, comme le site web, utilise [Nginx](nginx.com) et [DRF](django-rest-framework.org) (outil permettant de développer des API web en **Python**) pour le back et [Vue](https://fr.vuejs.org) pour le front. + +On la déploie avec [Docker](docker.com). + +## L'équipe + +La langate 3000 est le fruit d'une coopération historique entre les équipes SysRez-Dev et SysRez-Infra, et plus spécifiquement : + +- Gabriel "**KwikKill**" Blaisot [il], responsable SysRez-Dev de l'InsaLan XIX +- Paul "**TheBloodMan**" Gasnier [il], responsable SysRez-Infra de l'InsaLan XVIII +- Amance "**Ecnama**" Graindorge [il], responsable SysRez-Infra de l'InsaLan XIX +- Hector "**pixup1**" Vernet [il], responsable SysRez-Infra de l'InsaLan XIX + +Elle repose bien évidemment sur le travail des légendes à l'origine de la langate 2000 : + +- **Mahal** / ShiroUsagi-san +- **Red** / red4game +- **Flo** / darkgallium +- **Lin HD** / cloudyhug +- **Kuro** / antonincms +- **Trinity** / trinity-1686a +- **Lux** / Lymkwi +- **ElPainAuChocolat** / NathanPERIER \ No newline at end of file diff --git a/docs/manuel/src/SUMMARY.md b/docs/manuel/src/SUMMARY.md new file mode 100644 index 0000000..da05ee5 --- /dev/null +++ b/docs/manuel/src/SUMMARY.md @@ -0,0 +1,14 @@ +# Sommaire + +[Introduction](README.md) + +- [Backend](00-backend/README.md) + - [URLs](00-backend/urls.md) + - [Modèles](00-backend/modeles.md) + - [Vues](00-backend/vues.md) + - [Netcontrol](00-backend/netcontrol.md) + +- [Frontend](01-frontend/README.md) + - [Vues](01-frontend/vues.md) + - [Page de gestion](01-frontend/gestion.md) + - [Style](01-frontend/style.md) \ No newline at end of file