Manual Técnico de Instalación BiblioTEK Edición Open Source El objetivo del presente manual consiste en lograr una instalación del software opensource BiblioTEK en un servidor web administrado de manera privada. HT México Servicios y Consultoría no asume ninguna responsabilidad por fallas en la configuración, defectos del propio software o falta de experiencia en la administración de servidores. Se les pide abstenerse de contactar directamente a HT México a través de llamadas telefónicas o a los consultores de esa empresa; pero podrá dirigir un email a soporte@htmex.mx con sus preguntas, mismas que serán respondidas en la medida de las posibilidades de tiempo y agenda; HT México tampoco se asume ningún compromiso al respecto. Requisitos previos de software - Servidor Web apache funcionando. - Firebird SQL Server para gestionar base de datos. - PHP versión 5.4 - Extensión de Firebird para PHP. Requisitos previos Operativos - Identifique su IP pública. - Planificar cual es la forma en que estará disponible la aplicación: o A través de un subdominio de la institución educativo o biblioteca. p.e. biblioteca-digital.cities.org o A través de un dominio exclusivo donde operará la aplicación. p.e. www.bibliocolegiomorelos.edu.mx - Con base en la decisión anterior determinar los cambios necesarios a nivel DNS, adquisición de dominio, configuración de los paneles de control del servidor, etc. - BiblioTEK es una aplicación que facilita un sistema de comunicación a través de mensajes de correo electrónico, que requiere una cuenta de salida a través de SMTP. o o Es responsabilidad de Usted determinar si ya posee alguna cuenta que pueda ser usada al respecto y que ofrece una garantía de entrega sin el riesgo de que los mensajes sean calificados como spam. Se recomienda abrir una cuenta con el servicio mandrillapp.com que le asegura la entrega de cada mensaje, con una confiabilidad cercana al 100%. Este servicio le ofrece la entrega de los primeros 12,000 mensajes sin costo, que para la mayoría de los casos es suficiente. HT México Servicios y Consultoría SA de CV Página [1]
PROCESO DE INSTALACIÓN Este manual está pensado para un servidor Linux y fue documentado desde una distribución Ubuntu (Debian). Para el proceso de instalación utilizaremos comandos simples a través de una ventana de terminal directamente en el servidor o a través de una aplicación SSH, cuando el servidor es remoto. En cualquiera de los casos anteriores se deberá tener acceso como root. INSTALANDO EL SERVIDOR APACHE Opción 1: Instalando en un servidor completamente nuevo: 1) Instale Apache WEB server. sudo apt-get install apache2 2) Instale PHP. sudo apt-get install php5 3) Configure Apache para ejecutar aplicaciones php. sudo apt-get install libapache2-mod-php5 4) Reinicie apache para verificar los cambios. service apache2 restart 5) Abra su navegador favorito e ingrese con su IP pública (http://www.xxx.yyy.zzz) y verifique que Apache Web Server ya esté funcionando, en este momento podremos ver una página web default que nos indica que el servidor ya responde y está funcional pero aún debemos configurar muchas cosas: HT México Servicios y Consultoría SA de CV Página [2]
Opción 2: Instalando en un servidor con panel de control administrativo como CPanel o Plesk. 1) Usualmente ya estará instalado Apache y también PHP. 2) Verifique que la versión de apache sea 2.4 o superior y la versión de PHP sea 5.4 o superior. 3) Cree el subdominio o el dominio donde responderá BiblioTEK. Tome nota del directorio o carpeta donde quedará instalado. Es posible que en este momento se haya creado un usuario administrador de dominio (o subdominio). 4) Probablemente estas herramientas le permitan buscar e instalar el software Firebird SQL Server. Busque la versión 2.5 o superior. Si no fuera posible continúe al procedimiento Instalando Firebird como soporte de datos y hágalo manualmente. INSTALANDO FIREBIRD como soporte de base de datos Para esta parte del proceso Usted deberá acceder a su servidor como root. 1) Si aún no tiene instalado Firebird SQL Server 2.5. Ejecute las siguientes líneas para instalarlo manualmente. sudo add-apt-repository ppa:mapopa sudo apt-get update sudo apt-get install firebird2.5-superclassic Nota: Se le pedirá una contraseña para que el usuario SYSDBA indique su contraseña libremente y tome nota de ella para utilizarla más tarde. sudo apt-get install firebird2.5-examples firebird2.5-dev sudo apt-get install php5-interbase php5enmod interbase Reinicie apache para concluir esta fase de la instalación: service apache2 restart ** Recuerde que al concluir este proceso Usted deberá tener anotada con la contraseña del usuario SYSBA y en el documento nos referiremos a ella como supasswordsysdba. 2) El archivo firebird.conf controla la configuración de firebird, asegúrese de eliminar o comentar la línea RemoteBindAddress = localhost para poder realizar conexiones a la base de datos desde ubicaciones externas al servidor. Por default la línea estará activa y solo permite conexiones de datos desde el propio servidor pero frecuentemente necesitaremos realizar conexiones remotas o externas. Para comentar la línea basta colocar un signo de número # al inicio de la línea, p.e. # Asi la necesitamos # RemoteBindAddress = localhost HT México Servicios y Consultoría SA de CV Página [3]
3) Elija una ruta donde instalará el archivo de base de datos, por ejemplo: Nosotros recomendamos elegir un directorio con facilidad de acceso como /opt y crear un subdirectorio especial para la base de datos de BiblioTEK llamado datos. P.e. /opt/datos (ingrese al directorio /opt de su servidor y cree el subdirectorio datos usando el comando mkdir datos ) 4) Descargue una base de datos limpia. 4.1. Ingrese al directorio anteriormente creado y descargue el archivo metadata de base de datos con esta instrucción: wget http://www.htmex.mx/descargas/bibliotek_bd.bak 4.2. El archivo que será descargado es metadata transportable pero no es una base de datos, para crear la base de datos ejecute la siguiente instrucción: gbak R bibliotek_bd.bak biblio.fdb USER SYSDBA PASSWORD supasswordsysdba 5) Para tener un mejor nivel de seguridad no utilizaremos referencias directas a la ubicación de la base de datos, en su lugar utilizaremos un ALIAS. En el archivo de aliases configure la base de datos biblio.fdb como en este ejemplo se muestra: Ejecute un editor como vi o nano: vi /etc/firebird/2.5/aliases.conf Al final del archive agregue la siguiente línea: # # Live Databases: # biblio = /opt/datos/biblio.fdb Guarde sus cambios de acuerdo al editor que esté utilizando. Reinicie el servicio Firebird Database Server. Con la instrucción service firebird2.5-superclassic restart o también puede reiniciar el servidor). 6) El archivo de bases de datos que hemos creado con las anteriores líneas, deberá ser asignado al grupo y usuario firebird como sigue: chown firebird.firebird /opt/datos/biblio.fdb HT México Servicios y Consultoría SA de CV Página [4]
CREAR USUARIO ADMINISTRADOR DE DOMINIO Crear el directorio y usuario administrador de dominio Decida el directorio donde será instalado BiblioTEK. En este ejemplo supondremos que será el directorio /www-bibliotek/ ubicado directamente sobre el directorio raíz del volumen Linux. Si Usted creó el dominio o subdominio con panel de control no es necesario crear el directorio. 1) Creación manual del directorio y subdirectorios necesarios: mkdir /www-bibliotek mkdir /www-bibliotek/propios 2) Creación de un usuario especial (bibliotek_admin) y específico para administrar todo lo relacionado a BiblioTEK, como cambiar archivos de configuración, ejecutar tareas de mantenimiento, acceder por ftp, etc. adduser bibliotek_admin -home /www-bibliotek Nota: Se le pedirá que le asigne contraseña al usuario bibliotek_admin. Asigne y anote la contraseña para este usuario. p.e. juanito45z El usuario deberá pertenecer al grupo www-data, relacionado con Apache Web Server. usermod -a -G www-data bibliotek_admin El nuevo usuario bibliotek_admin debe ser propietario del directorio /www-bibliotek chown bibliotek_admin.www-data www-bibliotek Si Usted cuenta con CPanel o Plesk, quizá ya tiene un usuario creado para administrar el dominio. Verifique esto. INSTALANDO EL CODIGO MAESTRO DE LA APLICACION Inicie sesión en el servidor con SSH o terminal, como usuario administrador de dominio bibliotek_admin (obviamente también funcionará ingresar como root sin embargo es deseable reducir al mínimo el uso de root por motivos de seguidad). Si utiliza una conexión remota SSH, le recomendamos utilizar la herramienta Putty. Al ingresar como usuario bibliotek_admin, será llevado automáticamente al directorio de BiblioTEK. Si ingresa como root deberá situarse en el directorio con el comando cd /wwbibliotek 1) Asegúrese de que en el servidor ya está instalada el comando git. Si el comando git no estuviera instalado, ingrese como root y ejecute: sudo apt-get install git-core HT México Servicios y Consultoría SA de CV Página [5]
2) Clone el repositorio público disponible en github. git clone https://github.com/htmexico/bibliotek.git Al concluir el proceso tendremos el directorio /www-bibliotek/bibliotek 3) Muchas de las siguientes tareas podrán ser realizadas a través de una conexión FTP (p.e. usando Filezilla) dirigida a la IP de su servidor: Ejemplo de conexión ftp: Servidor ftp: 193.45.33.44 Usuario: bibliotek_admin Contraseña: juanito45z Las instrucciones para instalar un servidor ftp no están cubiertas por este manual. INSTALANDO LA PAGINA DE HOMEPAGE DE LA APLICACION Inicie sesión en el servidor con SSH o terminal, como usuario administrador de dominio bibliotek_admin. Probablemente quiera utilizar un cliente ftp para realizar el setup de su página inicial (homepage), lo cual también es posible. El objetivo de este proceso es establecer como directorio de respuesta primario de su sitio web en /www-bibliotek/ en este directorio colocaremos tres archivos de configuración inicial y activaremos el arranque del BiblioTEK. 1) Arranque una sesión de SSH o con su cliente ftp ubíquese en el directorio /wwwbibliotek/. 2) Cree o copia los archivos de funcionalidad de la página de inicio que fueron bajados e instalados por default en el directorio /www-bibliotek/bibliotek/ Para copiarlos al directorio /www-bibliotek use estas 3 instrucciones: cp BiblioTek/APP_CONFIG.php. cp BiblioTek/GLOBAL_CONFIG.php. cp BiblioTek/index_subdomain.php index.php 3) Ahora que los tres archivos ya están presentes en nuestro directorio, proceda a editar el archivo APP_CONFIG.php y coloque los siguientes valores: $ACCESS_CFG->id_biblioteca = 1; $ACCESS_CFG->codigo_cuenta = "mibiblioteca"; $ACCESS_CFG->banner = "propios/banner_biblioteca.jpg"; $ACCESS_CFG->http_public_dir = "http://222.111.23.1/"; Por ahora BiblioTEK solo soporta una biblioteca por instalación, por lo cual el valor de id_biblioteca siempre será UNO. Para codigo_cuenta usted podrá inventar cualquier valor quizá el prefijo o dominio de internet de su institución. HT México Servicios y Consultoría SA de CV Página [6]
En el apartado banner indique un archivo gráfico de entre 900-1000px de ancho por 100px de alto. Diséñelo y súbalo al directorio /www-bibliotek/propios. En http_public_dir coloque la dirección IP pública (o bien el subdomino propagado y configurado en su DNS particular). 4) Edite el archivo GLOBAL_CONFIG.php y coloque los siguientes valores: $www_dir = "http://222.111.23.1/bibliotek/"; $app_dir = "/www-bibliotek/bibliotek/"; En $www_dir coloque la dirección IP pública o bien el subdomino propagado y configurado en su DNS particular. En $app_dir coloque la ruta física donde se instaló el código de Bibliotek. 5) Es posible que en este momento su servidor Apache siga mostrando la página web default, por lo cual ahora procederemos a configurar la respuesta real de BiblioTEK. Para esto deberá iniciar una sesión SSH como usuario root. Ingrese al subdirectorio /etc/apache2/sites-available y duplique el archivo de configuración default que ha creado durante la instalación default. cd /etc/apache2/sites-available cp 000-default.conf bibliotek.conf Edite el nuevo archivo bibliotek.conf y modifique la línea DocumentRoot para apuntar hacia el nuevo directorio /www-bibliotek. # vi o nano bibliotek.conf Los siguientes ejemplos harán que nuestro ejemplo funcione correctamente: DocumentRoot /www-bibliotek/ <Directory /www-bibliotek/> Options -Indexes FollowSymLinks MultiViews AllowOverride None Require all granted </Directory> Sugerencia: El archivo de bitácora de errores de bibliotek.conf puede ser cambiado en lugar de utilizar el archivo default error.log,.p.e. ErrorLog ${APACHE_LOG_DIR}/biblio-error.log CustomLog ${APACHE_LOG_DIR}/biblio-access.log Nota: Si está configurando para que el servidor responda a un nombre de dominio o subdominio, deberá configurar adicionalmente la directiva ServerName. ServerName bibliotecaunion.colunion.edu HT México Servicios y Consultoría SA de CV Página [7]
Si en su servidor coexisten varias páginas o sitios web, solicite ayuda para que este nuevo sitio funcione como un subdominio virtual o con aliases. Nota: Si el servidor estará dedicado a BiblioTEK, deshágase de la configuración default para apache. a2dissite 000-default.conf 6) Active su nuevo sitio para Bibliotek y reinicie su servicio apache2 a2ensite bibliotek.conf service apache2 restart Nota: En este punto deberá corregir cualquier problema en su configuración de apache bibliotek.conf, hasta que la página index.php responda en su servidor. 7) Compruebe que lo realizado hasta el momento funcione correctamente, abra su navegador y teclee su http://www.xxx.yyy.zzz (indicando su IP pública). Si bien el servicio aún no está funcionando al 100%, Usted ya no debe encontrar errores típicos de error de configuración de apache. Se espera que su sitio web ya esté respondiendo y le indique un error Error connecting to FB DB CONFIGURANDO EL ACCESO A LA BASE DE DATOS Inicie sesión en el servidor con SSH o terminal, como usuario root o usuario administrador de dominio (bibliotek_admin). También puede ingresar a través de ftp. 1. Edite el archivo de configuración de base de datos, llamado config_db.inc.php que se encontrará en /www-bibliotek/bibliotek. # vi o nano /www-bibliotek/bibliotek/config_db.inc.php 2. Tomando como referencia el alias y contraseña que ya configuramos en una sección anterior (Instalando Firebird como soporte de base de datos), confirme los parámetros: $CFG->db_host $CFG->db_name $CFG->db_user = 'localhost'; = 'biblio'; // indique el alias = 'SYSDBA'; HT México Servicios y Consultoría SA de CV Página [8]
$CFG->db_pass = 'supasswordsysdba'; Por default hemos ilustrado la instalación de la base de datos firebird en el mismo servidor que incluye Apache, PHP y Firebird, así que en el valor db_host es válido la palabra localhost. En el apartado o variable db_name coloque el alias previamente establecido. El usuario default (db_user) siempre es SYSDBA, Usted puede dar de alta un usuario específico para la aplicación BiblioTEK pero eso es un tema que no será cubierto en este documento. La contraseña usted debió anotarla desde el paso 2 de esta manual. 3. Compruebe nuevamente lo realizado hasta el momento, abra su navegador y teclee su http://www.xxx.yyy.zzz (indicando su IP pública). Deberemos tener algo como lo siguiente: AFINANDO LA FUNCIONALIDAD a. Coloque su Banner. Usted requerirá un gráfico de entre 900 y 100 pixeles de ancho por 100 pixeles de alto, que será su banner llámelo banner_biblioteca.jpg y súbalo a /www-bibliotek/propios. En la siguiente imagen se muestra un ejemplo de banner: HT México Servicios y Consultoría SA de CV Página [9]
b. BiblioTek enviará diversos mensajes por correo electrónico, configure una cuenta de salida editando el archivo /www-bibliotek/bibliotek/email.inc.php, <?php unset($email); global $EMAIL; $EMAIL = new stdclass(); // Usted debe proporcionar estos datos $EMAIL->smtp_host = "mail.yourdomain.edu"; $EMAIL->smtp_user = "service@yourdomain.edu"; $EMAIL->smtp_pass = ""; $EMAIL->smtp_port = 25; $EMAIL->image_background = "http://www.yourdomain.edu/custom/logofondomail.jpg"; $EMAIL->font_default_css = "font-family:verdana,arial,helvetica; font-size:12px; font-color: black; ";?> Los mensajes de correo electrónico son creados usando un gráfico jpg como fondo, Usted deberá diseñarlo y configurarlo en $EMAIL->image_background. Experimente con libertad acerca de las características, colores y tamaños del archivo, para mejores resultados elija un archivo jpg/png de 15Kb o menor con una resolución de 450px de ancho por 200px de alto. La imagen se colocará a la derecha y al fondo del texto del correo electrónico Recomendación Importante: Algunos de nuestros usuarios utilizan servicios especializados gratuitos o de bajo costo como Mandrill y SendGrid. Esto les asegura que los mensajes de email sean entregados masivamente con una alta garantía, si Usted utiliza una cuenta interna es probable que sus mensajes sean marcados como spam o su IP pueda ser colocada en listas negras rápidamente. c. Establecimiento de robots para realizar trabajos automatizados diariamente y por hora. Algunas de las prestaciones de BiblioTEK permiten la generación de mensajes automatizados derivados de los mismos eventos que se presentan dentro de la biblioteca, además de otras funciones que deben realizarse periódicamente. Para que estos mensajes y funciones se realicen sin intervención humana debemos configurar un par de procesos que serán ejecutados todos los días y cada hora. /www-bibliotek/phps/cron_hourly_service.php /www-bibliotek/phps/cron_daily_service En Linux Usted podrá incorporar las siguientes líneas en su archivo /etc/crontab o ejecutar el panel de control (CPanel o Plesk) para incorporar ambos trabajos: # BiblioTEK # 1 * * * * root wget http://www.xxx.yyy.zzz/bibliotek/phps/cron_hourly_service.php # 1 4 * * * root wget http://www.xxx.yyy.zzz/bibliotek /phps/cron_daily_service.php HT México Servicios y Consultoría SA de CV Página [10]
El primero de ellos se ejecutará cada hora, -todos los días (en el minuto 1)-. El segundo se ejecutará a las 4:01am todos los días. Usted puede elegir libremente la hora en que desea ejecutar el proceso diario, pero se sugiere que sea durante un horario que no haya otras tareas ejecutándose. Si Usted insertó las líneas manualmente, para activarlas y que los procesos se ejecuten automáticamente reinicie el servicio cron con la línea: service cron restart d. Para el cálculo correcto de fechas, asegúrese de que el archivo /etc/php5/apache2/php.ini contiene las siguientes líneas con estos valores (exactamente en el formato que se muestra): ; Default timestamp format. ibase.timestampformat = "%Y-%m-%d %H:%M:%S" ; Default date format. ibase.dateformat = "%Y-%m-%d" ; Default time format. ibase.timeformat = "%H:%M:%S" e. Haga que su servidor responda a un subdominio o nombre de dominio. Este documento está redactado considerando la respuesta del servidor solamente a través de una dirección IP pública. Al liberar el servicio a su comunidad escolar o usuarios en general, se recomienda que el servidor responda a un nombre de dominio o subdominio. Dependiendo de su experiencia existen múltiples alternativas para estos efectos: Usted puede adquirir un dominio especial y exclusivo para BiblioTEK. Existen múltiples empresas que ofrecen esta posibilidad. Posteriormente deberá mapear o ligar ese nombre de dominio a la dirección IP de su servidor, seguramente. Usted puede tener un dominio previamente y quisiera que su servicio BiblioTEK responda a un subdominio, entonces deberá mapear ese subdominio a través de su configuración DNS como un registro A. Aquí observamos al mismo servicio BiblioTEK respondiendo en un subdominio. HT México Servicios y Consultoría SA de CV Página [11]