Creació d'un instal·lador automatitzat de l'aplicatiu, de la Demo amb docker i reorganització/creació de documentació a Github.

README.md

@@ -1,69 +1,128 @@
-django-aula
-===========
+# django-aula: Gestió Escolar - Software de Gestión de Centros Educatius
 
 Gestió de presència, incidències i més per a Instituts, Escoles i Acadèmies.
 
-School Attendance Software
+<p align="center">
+    <img src="http://i.imgur.com/YlCRTap.png" alt="Django-Aula responsive" width="70%">
+</p>
 
-![Imgur](http://i.imgur.com/YlCRTap.png)
+[![Tecnologia](https://img.shields.io/badge/Tecnologia-Django%205.1-092E20.svg?style=for-the-badge&logo=django)](https://www.djangoproject.com/)
+[![Database](https://img.shields.io/badge/Database-PostgreSQL-336791.svg?style=for-the-badge&logo=postgresql)](https://www.postgresql.org/)
 
-**[Llicència i Crèdits](LICENSE)** **EL PROGRAMA NO TÉ CAP GARANTIA, UTILITZEU-LO SOTA LA VOSTRA RESPONSABILITAT.**
+[![Servei](https://img.shields.io/badge/Served%20with-Docker%20Compose-2496ED.svg?style=for-the-badge&logo=docker)](https://docs.docker.com/compose/)
 
-Using Docker
-============
+[![Llicència](https://img.shields.io/badge/Llicència-MIT-2E8B57.svg?style=for-the-badge)](LICENSE)
 
-```
-cp env.example .env
-make build
-make start
+**[Llicència i Crèdits](LICENSE)** | **EL PROGRAMA NO TÉ CAP GARANTIA, UTILITZEU-LO SOTA LA VOSTRA RESPONSABILITAT.**
 
-# If you want to import demo data
-make load_demo_data
+---
 
-# If you want to clean the DB
-make down
-make start
-```
+# 📋 Índex de Continguts
+
+- [1. Introducció](#introduccio)
+- [2. Requisits del sistema operatiu per instal·lar Django-Aula](#requisits)
+- [3. Desplegament d'una Demostració de Django-Aula (Quick Demo) amb Docker 🐳 ](#quickdemo)
+- [4. Instal·lació i càrrega de dades de Django-Aula per ús real a un Centre Educatiu](#produccio)
+- [5. Equip Desenvolupador i Suport Tècnic](#dev-suport-tecnic)
+
+---
+
+<a name="introduccio"></a>
+## Introducció
+
+### Característiques Principals i Valor Afegit
+
+Django-Aula és un sistema integral dissenyat per alleugerir la càrrega de treball del personal docent d'un centre educatiu, millorant la gestió acadèmica i de convivència, al mateix temps que possibilita mantenir informades les famílies.
+
+El programa cobreix tots els aspectes clau de la gestió diària del centre educatiu: **Presència**, **Incidències**, **Actuacions**, **Sortides** i **Portal de Famílies**. Per a més detalls:
+
+➡️ **[Sobre les CARACTERÍSTIQUES generals](docs/USER_MANUAL/caracteristicas.md)**
+
+➡️ **[Sobre les FUNCIONALITATS concretes, amb captures de pantalla](docs/USER_MANUAL/funcionalidades.md)**
+
+Es pot consultar un índex complet amb tota la informació sobre Django-Aula:
+
+➡️ **[Índex complet sobre Django-Aula](docs/README.md)**
+
+
+<a name="requisits"></a>
+## Requisits del sistema operatiu per instal·lar Django-Aula
+
+Django-Aula s'instal·la en un servidor amb sistema operatiu Linux i està adaptat per Debian 13, Ubuntu Server 24.04 LTS o superior, o derivats de la mateixa base.
+
+Per qualsevol tipus d'instal·lació, ja sigui per un ús real o per l'entorn de demostració, és altament recomanable haver creat un usuari amb permisos de *SUDO*. [El procés està documentat.](docs/USER_MANUAL/ajuda-install/usuari_sudo.md)
+
+---
+
+<a name="quickdemo"></a>
+## Desplegament d'una Demostració de Django-Aula (Quick Demo) amb Docker 🐳 
+
+L'entorn de demostració, conegut com Demo, és una versió funcional del sistema i que es pot posar en funcionament en molt pocs minuts. Disposa de dades fictícies (usuaris, professors, alumnat i un horari mínim) que faciliten observar l'aspecte visual i interaccionar, des de diferents rols, amb les funcionalitats de l'aplicatiu real Django-Aula.
 
-Quick demo
-=========
+El desplegament de la Demo s'ha automatitzat amb l'execució de dues comandes i consta de dues passes consecutives:
 
-On Ubuntu Server 24.04 LTS:
+
+### 1a - Instal·lació automàtica de Docker i Docker Compose
+
+Des del directori de l'usuari instal·lador:
 
 ```bash
-sudo apt-get update
-sudo apt-get install python3 python3-venv python3-dev git
-sudo apt-get install python3-lxml python3-libxml2 libxml2-dev libxslt-dev lib32z1-dev
-sudo apt-get install libgl1 libglib2.0-0t64
-mkdir djau
-cd djau
-git clone --single-branch --branch master https://github.com/ctrl-alt-d/django-aula.git django-aula
-cd django-aula
-python3 -m venv venv
-source venv/bin/activate
-pip3 install -r requirements.txt
-./scripts/create_demo_data.sh
-python manage.py runserver
+wget -q -O install_docker.sh https://raw.githubusercontent.com/rafatecno1/django-aula/refs/heads/master/docker/install_docker.sh && \
+chmod +x install_docker.sh && \
+sudo ./install_docker.sh
+```
+
+### 2a - Instal·lació automàtica de la Demo de Django-Aula
+
+Es recomana crear un subdirectori dins el directori de l'usuari instal·lador per instal·lar la Demo, en aquest exemple `demo-djau-docker`:
 
+```bash
+mkdir demo-djau-docker && cd demo-djau-docker && \
+wget -q -O install_quick_demo_docker.sh https://raw.githubusercontent.com/rafatecno1/django-aula/refs/heads/master/docker/install_quick_demo_docker.sh && \
+chmod +x install_quick_demo_docker.sh && \
+bash ./install_quick_demo_docker.sh
 ```
 
-Open browser at http://127.0.0.1:8000 ( User M1, M2, ..., T1, T2, .. .All passwd 'dAju' )
+Tot i que el procés anterior és autònom i interactivament configurable, es recomana llegir la informació, molt més detallada del procés, segons el tipus de màquina (no virtualitzada, virtualitzada o servidor d'accés públic) on s'instal·larà la Demo. També hi haurà qui estarà interessat en dur a terme la instal·lació manual, tant de l'entorn de docker com de la Demo. Per tots aquests casos es recomana consultar els següents detallats documents:
 
-Deployment Docs
-=============
 
-[Documentació pas a pas per a fer el desplegament.](docs/Wiki/README.md)
+➡️ **[Instal·lació de l'entorn de Docker i Docker Compose](docs/USER_MANUAL/demo/install_entorn_docker.md)**.
 
-Vols col·laborar-hi com a #DEV?
-=============
+➡️ **[Instal·lació ràpida de la Demo amb Docker](docs/USER_MANUAL/demo/install_demo_docker.md)**.
 
-Aquestes són les [issues prioritàries](https://github.com/ctrl-alt-d/django-aula/issues?q=is%3Aissue%20state%3Aopen%20label%3APrioritari)
+➡️ **[Instal·lació manual de la Demo (sense Docker)](docs/USER_MANUAL/demo/install_demo_manual.md)**.
 
-Hi estàs interessat?
 
-[FAQs](https://github.com/ctrl-alt-d/django-aula/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3AFAQ+)
+<a name="produccio"></a>
+## 🚀 Instal·lació i càrrega de dades de Django-Aula per ús real a un Centre Educatiu (Entorn de Producció)
+
+### 1a part. Procés d'instal·lació.
+
+Si vol instal·lar Django-Aula per fer-lo servir a un centre educatiu cal un servidor de producció, ja sigui un servidor públic (VPS) o un servidor local (xarxa local), que pot ser una màquina real o una màquina virtual (VM). Per tots aquests casos hi ha dues opcions:
 
-Necessites ajuda?
-============
+* **Mètode Prioritari i recomanat: Desplegament completament automatitzat** amb scripts.  
+➡️ **[GUIA COMPLETA D'INSTAL·LACIÓ AUTOMATITZADA](docs/install_djau_automatic_scripts.md)**
 
+* Mètode Clàssic: Desplegament manual pas a pas.  
+➡️ **[Instruccions de Desplegament Manual](docs/install_djau_manual.md)**
+
+### 2a part. Procés de càrrega de dades
+
+Després de la instal·lació el sistema estarà preparat per rebre les dades reals del centre educatiu pel curs escolar (alumnat, docents, aules, horaris, etc).
+
+➡️ **[Instruccions per la càrrega de dades del centre educatiu](docs/README.md)**.
+
+---
+
+<a name="dev-suport-tecnic"></a>
+## 📚 Equip Desenvolupador i Suport Tècnic
+
+* **Vols col·laborar-hi com a #DEV?**  
+Aquestes són les [Issues prioritàries](https://github.com/ctrl-alt-d/django-aula/issues?q=is%3Aissue%20state%3Aopen%20label%3APrioritari)
+* **Pregüntes d'ús freqüent**.  
+[FAQs](https://github.com/ctrl-alt-d/django-aula/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3AFAQ+)
+* **Has trobat errors? Necessites ajuda?** Utilitza el Formulari per demanar ajuda o comunicar errors (*Issues*)  
 [Issues/Formularis d'ajuda](https://github.com/ctrl-alt-d/django-aula/issues/new/choose)
+
+---
+

aula/settings_dir/demo.py

@@ -2,7 +2,7 @@
 # Django settings for aula project.
 
 from .dev import *  # noqa: E402, F403, F401
-
+import os
 
 def location(x):
     return os.path.join(PROJECT_DIR, x)  # noqa: F405
@@ -21,6 +21,15 @@ def location(x):
 LOCALITAT = "L'Escala"
 URL_DJANGO_AULA = r"http://127.0.0.1:8000"
 
+# Possibilita la instal·lació de la Demo en qualsevol entorn
+# Llista base (sempre localhost)
+ALLOWED_HOSTS = ['127.0.0.1']
+# Si existeix la variable d'entorn amb altres hosts, la processa
+DEMO_HOSTS_STR = os.environ.get('DEMO_ALLOWED_HOSTS', '')
+if DEMO_HOSTS_STR:
+    # Afegeix els hosts llegits de la variable d'entorn (separats per coma)
+    ALLOWED_HOSTS += DEMO_HOSTS_STR.split(',')
+
 EMAIL_SUBJECT_PREFIX = "[DEMO AULA] "
 EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"
 

docker/Makefile.demo.automatica

@@ -0,0 +1,28 @@
+.PHONY: serve stop down logs
+
+# ----------- DEMO -----------
+
+serve:
+	${INFO} "Running demo services (detached)"
+	@ docker compose -f docker-compose.yml up -d
+
+stop:
+	${INFO} "Stopping demo services"
+	@ docker compose -f docker-compose.yml stop
+
+down:
+	${INFO} "Stopping demo services and deleting DB"
+	@ docker compose -f docker-compose.yml down -v
+
+logs:
+	${INFO} "Showing logs"
+	@ docker compose -f docker-compose.yml logs -f
+
+# ----------- Aesthetics -----------
+YELLOW := "\e[1;33m"
+NC := "\e[0m"
+
+INFO := @bash -c '\
+  printf $(YELLOW); \
+  echo "=> $$1"; \
+  printf $(NC)' SOME_VALUE

docker/README.md

@@ -0,0 +1,44 @@
+# Contingut del Directori Docker
+
+Aquest directori conté tots els fitxers creats per gestionar el desplegament de la Demo de Django-Aula i per la creació d'imatges de l'aplicació Django-Aula mitjançant contenidors Docker.
+
+El directori conté els fitxers de configuració pel desplegament ràpid de la Demo i els fitxers per construir-la, així com algun arxiu més que obre la porta per futurs desenvolupaments de l'aplicatiu sencer amb Docker.
+
+---
+
+## 1. Requisit previ. Instal·lació de Docker CE i docker-compose en el sistema operatiu
+
+Segons es descriu a les instruccions principals del repositori, hi ha dues maneres d'instal·lar Docker en el sistema operatiu, la manual i l'automatitzada.
+
+| Nom de l'Arxiu | Descripció | Ús Principal |
+| :--- | :--- | :--- |
+| `install_docker.sh` | **Script d'instal·lació automatitzada de Docker.** Descarrega i configura tot allò que cal per instal·lar l'entorn Docker i docker-compose en el sistema. | Instal·lar Docker en el sistema operatiu. |
+
+
+## 2. Arxius de Configuració de Desplegament Ràpid
+
+Aquests arxius s'utilitzen per a l'**Instal·lació de la Demo** amb Docker de forma automatitzada, tal com s'explica al document principal. Són la base per a un desplegament senzill i automatitzat típic amb Docker.
+
+| Nom de l'Arxiu | Descripció | Ús Principal |
+| :--- | :--- | :--- |
+| `install_quick_demo_docker.sh` | **Script d'instal·lació automatitzada.** Descarrega, col·loca els arxius de configuració a l'arrel del projecte, els reanomena i desplega els contenidors automàticament. | Desplegament actual de la Demo. |
+| `docker-compose.demo.automatica.yml` | Fitxer de configuració de serveis (Web + DB) utilitzat per la Demo. | Serà l'arxiu `docker-compose.yml` que desplegarà la Demo. |
+| `Makefile.demo.automatica` | Defineix les ordres de gestió simplificades (`serve`, `stop`, `logs` i `down`) per a la Demo. | Serà l'arxiu `Makefile` que facilitarà el desplegament de la Demo. |
+| `env.demo.automatica` | Arxiu de variables d'entorn per la base de dades de PostgreSQL que farà servir la Demo. | Serà l'arxiu `.env` que llegirà l'arxiu `docker-compose.yml`. |
+| `dades_demmo.sql` | És el fitxer SQL (`.sql`) amb les dades de demostració precarregades. | El contenidor de PostgreSQL llegeix aquest fitxer en iniciar-se i omple la base de dades de forma ràpida i automàtica. |
+
+---
+
+## 3. Fitxers de Construcció i Entorns de Desenvolupament
+
+Es troben ubicats al directori **build-dev** i són els que es fan servir per **crear noves imatges**, tant per la Demo com per qualsevol altre objectiu.
+
+| Nom de l'Arxiu | Descripció | Finalitat |
+| :--- | :--- | :--- |
+| `Dockerfile.demo.automatica` | Defineix com es va construir la imatge per a la Demo actualment desplegable de forma automatitzada . | Utilitzat per crear la imatge pujada al repositori d'imatges *Docker Hub*. |
+| `docker-compose.demo.manual.yml` | És el fitxer de partida a partir del qual es va construir el *docker-compose.demo.automatica.yml*. | Ús per a desenvolupadors locals que volen accedir a *shells*, *migrations*, etc. |
+| `docker-compose.dev.yml` | Configuració completa dels serveis per a **l'entorn de Desenvolupament** (DEV). (ara en desenvolupament) | Facilitar crear un entorn de desenvolupament de l'aplicació bassat en Docker i pensat per a desenvolupadors locals que volen accedir a *shells*, *migrations*, etc. |
+| `Makefile.demo.manual` | És el fitxer de partida a partir del qual es va construir el *Makefile.demo.automatica*. Interacciona amb el fitxer *docker-compose.demo.yml*.| És l'arxiu que facilitarà la creació i desplegament de les noves Demos que es vulguin crear. |
+| `Makefile.demo.complet` | Conté conjuntament les instruccions per treballar tant amb la versió manual com la versió *DEV*. | Serveix com a referència i com a base per a entorns de Producció/Desenvolupament. |
+| `env.example` | Arxiu de variables d'entorn *sense personalitzar* per la base de dades de PostgreSQL que farà servir la Demo. | Base per crear el fitxer `.env` per crear una imatge de Django-Aula amb Docker. |
+| `.dockerignore.demo` | Especifica els fitxers que s'han d'excloure del context de construcció de la imatge de la Demo. | Optimització i seguretat de la imatge Docker final. |