Guía de usuario de AulaChat (Versión 0.1 Alpha)

Transcripción

1 Guía de usuario de AulaChat (Versión 0.1 Alpha) By James López Prieto. Índice de contenido Introducción...2 Instalación de AulaChat Requerimientos Nota previa Instalación Descargue o baje del SVN AulaChat (Web: ) Ejecute instalar.sh ( './instalar.sh' ) Base de datos MySQL Compilar el proyecto Configuración Resolución de problemas... 6 NOMENCLATURA General Nombre de ficheros Nombre de funciones / variables Conclusión... 8 ERRORES... 8

2 NOTA: Esta guía puede quedarse obsoleta sobre todo en versiones Alpha. No obstante, se procurará actualizarla debidamente en las versiones Beta del programa y siempre en las versiones finales. Introducción Esta guía es el conjunto de los documentos que hasta ahora han sido escritos para AulaChat. Más que una guía de usuario, es el conjunto de una documentación que puede ayudar al usuario y al desarrollador interesado en AulaChat a comprender mejor el programa. De hecho se centra en el programa en sí y no en el uso desde la web del mismo, esto es debido al hecho de que esta documentación es para la versión alpha, y el programa carece aún de la funcionalidad necesaria para escribir una guía de uso. Instalación de AulaChat 1 -- Requerimientos En cuanto al hardware lo necesario será siempre proporcional a la carga de datos y usuarios que se gestionen con AulaChat; en principio el programa está diseñado de modo que sea lo más eficiente posible, ya que incorpora todo el sistema de conexión con la BD, servicios, servidor web, etc.. en el mismo, y gestiona las peticiones web creando un proceso por cada una (esto puede ser discutido en cuanto a rendimiento ya que hay sistemas mejores, no obstante, no quita el hecho de que el rendimiento se ve enormemente disminuido debido a esta opción); por lo tanto cualquier sistema actual servirá de manera suficiente para incorporar un sistema dotado del servidor AulaChat. Por otra parte, el software requerido es un sistema UNIX que incorpore además las siguientes librerías: MySQL (es necesario el API de C (mysql.h y librerías) el servidor y el cliente), y las librerías estandar de C. Además deberemos tener un usuario con permiso suficiente para utilizar MySQL y poder crear BDs y tablas. También deberemos disponer los privilegios suficientes para poder ejecutar el servicio en un puerto de escucha, y para poder escribir/leer en el directorio donde se encontrase ubicado AulaChat.

3 2. -- Nota previa. Versiones de AulaChat Alpha o Beta: Estas versiones no solo carecen de alguna funcionalidad, si nó que se encuentran en un período de prueba, y sobre todo en las versiones Alpha, puede haber agujeros de seguridad importantes o puede que alguna funcionalidad se incorpore parcialmente. Por ello aconsejo no utilizar estas versiones en un servidor en producción, de cara al público en general, etc.. Ya que puede suponer un riesgo importante. Sí aconsejo su uso en privado, para hacer pruebas.. etc. Versiones de AulaChat finales: Estas versiones han sido testeadas lo suficiente como para poderse utilizar en cualquier ámbito. No obstante, se aconseja visitar la web con frecuencia para descargar posibles actualizaciones o obtener información acerca de algún posible bug descubierto. Ambas versiones: En futuras versiones posiblemente se proveerá un servicio de lista de correo para recibir la notificación de actualizaciones, etc. no obstante se aconseja visitar la web para informarse del estado del proyecto Instalación La instalación se ha facilitado enormemente poniendo a disposición del usuario un script (instalar.sh) que recauda los datos necesarios para instalar AulaChat en su sistema; además de un fichero de configuración en XML para modificar los valores esenciales antes de iniciar AulaChat en su sistema. Pasos a seguir: 1 - Descargue o baje del SVN AulaChat (Web: ) En el caso de descargar AulaChat comprimido desde la web deberá

4 descomprimirlo en el directorio que desee tener instalado el mismo, si utilizó SVN el directorio descargado será también el de instalación / ejecución. (descarga web) Ejemplo: Baje el archivo $wget Vaya a la ubicación donde desee tener instalado AulaChat $cd /home/pepe/ Descomprima el archivo $tar -xvzf aulachat-0.1alpha.tar.gz $cd AulaChat-0.1alpha 2 - Ejecute instalar.sh ( './instalar.sh' ) En caso de que instalar.sh no tenga permisos de ejecución deselos escribiendo 'chmod +x./instalar.sh'. Siga el proceso de instalación, recuerde, no obstante, que deberá tener instalado MySQL con las librerías correspondientes, ya que en el proceso de instalación 'instalar.sh' le preguntará por la ubicación de las mismas y además le pedirá un usuario en caso de que desee generar la base de datos de AulaChat. 3 - Base de datos MySQL AulaChat gestiona los datos que usa mediante una base de datos externa MySQL, por ello necesita comunicarse con la misma (API de C de MySQL, normalmente son las librerías 'dev' de mysqlclient, aunque depende de la distribución; si no da encontrado el paquete en cuestión escriba un mensaje en el foro con su distribución y versión de la misma) y además deberá tener instalado el servidor de MySQL con un usuario que tenga privilegios suficientes para generar la base de datos y las tablas (en el proceso de instalación) y para insertar, borrar o modificar datos (en la ejecución del programa). Puede configurar esto manualmente o desde el script de instalación, únicamente deberá ejecutar/importar las sentencias incluidas en el fichero 'aula.sql'. Esto podrá hacerlo desde la línea de comandos como hace el script de instalación (lo más rápido), o si lo prefiere desde un gestor tipo phpmyadmin o similares, manualmente.

5 NOTA: Es posible que si necesita reinstalar quiera mantener o borrar las tablas, esto último solo lo podría hacer desde la línea de comandos con la orden correspondiente o desde el programa gestor externo. 4 - Compilar el proyecto Esto se hace ejecutando un simple 'make' en el directorio de AulaChat. Si todo está correcto debería compilar y finalmente tendremos el ejecutable 'aulachat' (puede ser necesario darle permisos de ejecución con 'chmod +x aulachat'. 5 - Configuración Deberá configurar AulaChat para iniciar el programa correctamente. Esto se hace copiando primero el fichero aulachat.xml.default a aulachat.xml $cp./aulachat.xml.default./aulachat.xml y seguidamente editando este último fichero. En este fichero nos encontramos diversas opciones a modificar, alguna puede que no funcione todavía. Lo más importante es modificar lo siguiente: port: Escriba el número de puerto de escucha para peticiones web que mejor le convenga. Al programa se accede desde un navegador, por lo tanto si es puerto elegido es el 80 podrá acceder a el poniendo: Si es el puerto XXX accederá poniendo: mysql: En este apartado deberá modificarlos los datos de conexión a la base de datos MySQL. El puerto normalmente es el 3306; deberá proveer un usuario y una contraseña para acceder al servidor y el host del mismo. NOTA: Es importante que el acceso a este fichero esté restringido o la carpeta de AulaChat, ya que puede suponer un riesgo al poder visualizar estas contraseñas con un simple 'cat'. Además AulaChat o la BD no encripta las contraseñas (de momento), por lo tanto, tenga especial cuidado con los permisos de acceso.

6 El resto de las opciones preferiblemente déjelas como están. Recuerde no poner un espacio en blanco entre los datos que escriba Ej: <dato> </dato> <- estaría mal!. -- Finalmente ya estaría todo listo para ejecutar aulachat ( './aulachat' ) Resolución de problemas Debido a que al menos cuando escribo esto las únicas versiones disponibles de AulaChat son Alpha, es posible que tenga dificultades con la instalación del mismo; por ello, ruego deje un mensaje en el foro para poder solventar el fallo, la duda, o lo que haga falta!. Acceda al foro desde la opción en El foro, al menos en las primeras versiones, es el mejor método para la resolución de incidentes, dudas, etc. mientras no se creen listas de correo o se busquen otros métodos para facilitar el envío de fallos. En este documento se agregará toda la información que crea necesaria para un mejor entendimiento de las fuentes del programa; específicamente esta sección está creada para entender la nomenclatura a utilizar en nombres de ficheros, nombres de funciones, variables, etc... Con ello pretendo facilitar la "lectura" de código, y además ayudarme a mi (el programador inicial del proyecto) a organizar todo lo relativo al 'bautizo' (que bueno..) de funciones, entre otras cosas. NOMENCLATURA

7 1. General El 'bautizo' de estos nombres principalmente será en dos idiomas, castellano e inglés. Lógicamente sería más razonable efectuar dicho bautizo en uno solo, pero la manía personal puede a la lógica en algunas ocasiones, y es que cambiar una costumbre que tengo muy arraigada por razones personales al programas es muy dificil. Básicamente muchas de los nombres en asignaciones quedan más cortos en inglés, por lo que seguramente use más ese idioma, no obstante, y como ejemplo, el nombre de una lista de funciones con estructura algo enrevesada podría optar por ponerlo en español ya que sería más intuitivo. 2. Nombre de ficheros El nombre de los ficheros del programa será en mayusculas si el fichero es un documento, o en minúsculas si el fichero es codigo fuente u otro. Además los nombres intentarán ser lo más cortos y descriptibles posibles con su contenido. El nombre de directorios será igualmente en minuscula siendo también lo más descriptibles posibles en cuanto a su contenido; además loa estructura de los mismos será tal que deberá ser lo suficiente intuitiva como para saber la localización de lo que se busque. 3. Nombre de funciones / variables El nombre de funciones o variables será en minúscula principalmente, siendo en mayúscula las variables definidas como constantes (#defines) y quizá alguna struct o función que sea neceasario una mayor énfasis de la misma, en tal caso solo se haría mayuscula la primera letra de la función/struct/... Lógicamente estos nombres serán descriptivos en la medida de lo posible, ya que algunas variables por ejemplo incrementales llevarán los clásicos nombres de "i, j...". Finalmente se podrá hacer agrupaciones de variables/funciones del estilo: "mysql_escribe(), mysql_lee()", también podría implementar esto con los

8 ficheros si fuese conveniente. 4. Conclusión En principio esto es básicamente la nomenclatura a utilizar, no me he basado en nada escrito, es decir, estas "reglas" no las he buscado o recojido de ningún sitio, simplemente las expuse basándome siempre en la lógica y poniendo toda la 'hostilidad' necesaria para que un futuro programador que quiera hacer algo con el programa o simplemente alguien que curiosee el código sea lo más intuitivo posible. ERRORES En otros programas las salidas de error se hacen directamente en la pantalla de salida indicando el error encontrado y quizás un código que normalmente no se recoge en la documentación principal del programa. En este caso y por comodidad y querer hacer una buena estructuración de donde se generan estos errores AulaChat printea un código de error que puede ser interpretado en este documento. Este código normalmente se compone de dos cifras, siendo la de la izquierda la más significativa (CIFRA IZ - CiFRA DER), de este modo se estructura el error primero según el módulo general (normalmente) donde se encuentra (cifra IZ), y después según en donde es localizado en concreto el error, es decir, en qué parte del módulo ha ocurrido el mismo. A continuación se listan los códigos de error jerarquizados según el módulo y además se dice el lugar del error. Trivialmente sabiendo esto no hace falta concretar mucho más para saber a qué se debe el error, debido a que dentro de cada módulo del programa al fallar y dar lugar un error en una parte del módulo, la misma está totalmente definida.

9 NOTA: Algunos errores, la mayoría no asociados a un código de error, saldrán por pantalla únicamente si la variable global DEBUG está activada. - #0-* - Módulo principal (Inicio del programa). (aulachat.*) - #0 - Error en la inicialización del programa. - #1..4-* - Módulo web (web.*) - #1 - Error al escuchar en el puerto. (Servidor). - #2-* - Módulo del bucle principal de escucha (superloop). - #2 - Error en el bucle principal. - #2-1 - Error al recibir datos - #2-2 - Petición no válida (se puede omitir/no debería suceder). - # Memoria insuficiente. - #2-3 - Error al leer el fichero pedido. - #2-4 - Error en el envío. - #3 - Error al crear socket cliente. - #4* - Gestión de envíos a usuarios (datos web) - #4-1 - No existe un administrador global - #5* - Módulo de gestión de usuarios. (user.*) - #5-1 - Error en la asignación de la memoria compartida Más información: WEB: FORO: Código fuente: 8/4/2007 James López Prieto bluegod (at) bluegod.net