diff --git a/CHANGELOG.md b/CHANGELOG.md index 24e01e8d7..a4efc4d3c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [3.1.1dev] - 2026-06-18 : +## [3.1.1] - 2026-06-18 : ### Credits diff --git a/LEAME.md b/LEAME.md index adc005608..5631daf5d 100644 --- a/LEAME.md +++ b/LEAME.md @@ -15,7 +15,6 @@ Esta guia es para la actualizacion del despliegue institucional de iSkyLIMS usan - [Configurar `my_prod_settings_iskylims.txt`](#configurar-my_prod_settings_iskylimstxt) - [Backup antes de actualizar](#backup-antes-de-actualizar) - [Ejecutar la actualizacion](#ejecutar-la-actualizacion) - - [Caso especial: actualizacion desde 3.0.0 a 3.1.0](#caso-especial-actualizacion-desde-300-a-310) - [Comprobaciones posteriores](#comprobaciones-posteriores) - [Rollback](#rollback) - [Reparar permisos](#reparar-permisos) @@ -236,32 +235,7 @@ El script: No usa la accion `install` porque este procedimiento asume una base de datos institucional ya existente. -## Caso especial: actualizacion desde 3.0.0 a 3.1.0 - -La actualizacion desde 3.0.0 a 3.1.0 requiere pasos extra porque hay cambios de datos que necesitan scripts especificos: - -- `convert_rawtop_counter_to_int` antes de migraciones; -- `library_pool_to_many_relation` despues de migraciones; -- exportar antes la relacion `wetlab_library_pool.id -> run_process_id_id`. - -Exporta el fichero necesario: - -```bash -mysql --user= --password --host= --port= iskylims \ - -e "SELECT id, run_process_id_id FROM wetlab_library_pool" \ - > /tmp/library_pool_run_process.tsv -``` - -Ejecuta la actualizacion especial: - -```bash -bash container_install.sh --engine podman --install_conf conf/my_prod_settings_iskylims.txt --action upgrade \ - --script_before convert_rawtop_counter_to_int \ - --script_after library_pool_to_many_relation,/tmp/library_pool_run_process.tsv \ - 2>&1 | tee ./iskylims_podman_upgrade_3_0_0_to_3_1_0_$(date +%Y%m%d_%H%M%S).log -``` - -Usa este comando solo para esa actualizacion concreta. Para actualizaciones posteriores, usa el comando generico de la seccion anterior. +Si la version instalada necesita scripts de migracion de datos, sigue la [guia de actualizacion especifica para esa version](docs/upgrades/README.md) en lugar de ejecutar solamente el comando generico. ## Comprobaciones posteriores diff --git a/README.md b/README.md index f183408aa..d2fa315c8 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![Django](https://img.shields.io/static/v1?label=Django&message=4.2&color=blue?style=plastic&logo=django)](https://github.com/django/django) [![Python](https://img.shields.io/static/v1?label=Python&message=3.8.10&color=green?style=plastic&logo=Python)](https://www.python.org/) [![Bootstrap](https://img.shields.io/badge/Bootstrap-v5.0-blueviolet?style=plastic&logo=Bootstrap)](https://getbootstrap.com) -[![version](https://img.shields.io/badge/version-3.0.0-orange?style=plastic&logo=GitHub)](https://github.com/BU-ISCIII/iskylims.git) +[![version](https://img.shields.io/badge/version-3.1.1-orange?style=plastic&logo=GitHub)](https://github.com/BU-ISCIII/iskylims.git) The introduction of massive sequencing (MS) in genomics facilities has meant an exponential growth in data generation, requiring a precise tracking system, from library preparation to fastq file generation, analysis and delivery to the researcher. Software designed to handle those tasks are called Laboratory Information Management Systems (LIMS), and its software has to be adapted to their own genomics laboratory particular needs. iSkyLIMS is born with the aim of helping with the wet laboratory tasks, and implementing a workflow that guides genomics labs on their activities from library preparation to data production, reducing potential errors associated to high throughput technology, and facilitating the quality control of the sequencing. Also, iSkyLIMS connects the wet lab with dry lab facilitating data analysis by bioinformaticians. @@ -24,20 +24,13 @@ Application servers run web applications for bioinformatics analysis (GALAXY), t - [Cron jobs inside the container](#cron-jobs-inside-the-container) - [Manage containers after installation](#manage-containers-after-installation) - [Upgrade docker deployment](#upgrade-docker-deployment) - - [Upgrade docker deployment v3.0.0 to 3.1.0](#upgrade-docker-deployment-v300-to-310) - - [Back up first](#back-up-first) - - [Refresh code and settings](#refresh-code-and-settings) - [Bare-metal deployment (Ubuntu/CentOS)](#bare-metal-deployment-ubuntucentos) - [Install](#install) - [Clone the repository](#clone-the-repository) - [Prepare the database](#prepare-the-database) - [Configure install\_settings.txt](#configure-install_settingstxt) - [Run install.sh](#run-installsh) - - [Upgrade (3.0.0 to 3.1.0)](#upgrade-300-to-310) - - [Back up first](#back-up-first-1) - - [Refresh code and settings](#refresh-code-and-settings-1) - - [Run upgrade steps requiring root](#run-upgrade-steps-requiring-root) - - [Run upgrade steps without root](#run-upgrade-steps-without-root) + - [Upgrade bare-metal deployment](#upgrade-bare-metal-deployment) - [Common operations (Docker + bare-metal)](#common-operations-docker--bare-metal) - [Database creation, users and grants](#database-creation-users-and-grants) - [Backups](#backups) @@ -323,40 +316,7 @@ bash container_install.sh --install_conf conf/my_prod_settings_iskylims.txt --ac The upgrade path rebuilds/restarts the container and runs `install.sh --bootstrap upgrade --tables` inside the app container. The app files are already baked into the rebuilt image; the bootstrap phase applies migrations with `--fake-initial`, refreshes `conf/first_install_tables.json`, refreshes static files, and skips superuser/demo/test data loading. -### Upgrade docker deployment v3.0.0 to 3.1.0 - -#### Back up first - -Run the backup steps in [Backups](#backups) first. - -For 3.0.0 -> 3.1.0, export the LibraryPool mapping first, then run the upgrade with pre/post scripts: - -```bash -mysql --user= --password= --host= --port= iskylims \ - -e "SELECT id, run_process_id_id FROM wetlab_library_pool" \ - > /tmp/library_pool_run_process.tsv -``` - -#### Refresh code and settings - -```bash -cd /iskylims -git pull -cp conf/docker_production_settings.txt my_prod_settings_iskylims.txt -sudo nano my_prod_settings_iskylims.txt -``` - -Ensure the file uses Linux-friendly encoding (UTF-8/ASCII) if you edit it on Windows. - -Keep the same `APP_UID`/`APP_GID` values in the selected install config before running the 3.0.0 -> 3.1.0 upgrade. - -Run upgrade command: - -```bash -bash container_install.sh --engine podman --install_conf my_prod_settings_iskylims.txt --action upgrade \ - --script_before convert_rawtop_counter_to_int \ - --script_after library_pool_to_many_relation,/tmp/library_pool_run_process.tsv 2>&1 | tee ./iskylims_docker_install_$(date +%Y%m%d_%H%M%S).log -``` +If the installed version requires data-migration scripts, follow the applicable [version-specific upgrade guide](docs/upgrades/README.md) instead of using only the generic command. ## Bare-metal deployment (Ubuntu/CentOS) @@ -415,34 +375,9 @@ sudo bash install.sh --install full --git_revision main --tables - If Apache is managed elsewhere, skip the automatic restart with `--skip_apache_restart`. -### Upgrade (3.0.0 to 3.1.0) - -Follow these steps to move from version 3.0.0 to the 3.1.x series. - -#### Back up first - -Run the backup steps in [Backups](#backups) first. -- Additionally, back up the full installation folder (for example `/opt/iskylims`) for bare-metal rollback. -- If you use library pools, export them before upgrading: +### Upgrade bare-metal deployment - ```bash -mysql --user= --password= --host= --port= iskylims \ - -e "SELECT id, run_process_id_id FROM wetlab_library_pool" \ - > /tmp/library_pool_run_process.tsv - ``` - -#### Refresh code and settings - -```bash -cd /iskylims -git pull -cp conf/template_install_settings.txt install_settings.txt -sudo nano install_settings.txt -``` - -Ensure the file uses Linux-friendly encoding (UTF-8/ASCII) if you edit it on Windows. - -#### Run upgrade steps requiring root +Run the backup steps in [Backups](#backups) first and back up the full installation folder (for example `/opt/iskylims`). Then refresh the repository and review the current installation settings template before upgrading. Update system and Python dependencies: @@ -452,19 +387,16 @@ sudo bash install.sh --upgrade dep 2>&1 | tee install_full.log Make sure the installation directory permissions allow the non-root step to write to `/opt/iskylims` (adapt your hardening script if paths changed). -#### Run upgrade steps without root - Upgrade the application code and database: ```bash -# with library pool restore -bash install.sh --upgrade app --git_revision main \ - --script_before convert_rawtop_counter_to_int \ - --script_after library_pool_to_many_relation,/tmp/library_pool_run_process.tsv +bash install.sh --upgrade app --git_revision main ``` Upgrades regenerate migrations and apply them with `--fake-initial` so existing tables remain intact, matching the Docker workflow. +If the installed version requires data-migration scripts, follow the applicable [version-specific upgrade guide](docs/upgrades/README.md) instead of using only the generic command. + ## Common operations (Docker + bare-metal) ### Database creation, users and grants diff --git a/UPGRADE_SCRIPTS.md b/UPGRADE_SCRIPTS.md index 919af840f..adec9c1ee 100644 --- a/UPGRADE_SCRIPTS.md +++ b/UPGRADE_SCRIPTS.md @@ -1,6 +1,8 @@ # Upgrade scripts This file lists data migration scripts and the version range they apply to. +For complete operator procedures, prerequisites, and container or bare-metal commands, see the [version-specific upgrade guides](docs/upgrades/README.md). + Run them with: ```bash diff --git a/container_install.sh b/container_install.sh index 8d93fba1d..bf79e7769 100644 --- a/container_install.sh +++ b/container_install.sh @@ -1,6 +1,6 @@ #!/usr/bin/bash -ISKYLIMS_VERSION="3.1.0" +ISKYLIMS_VERSION="3.1.1" usage() { cat << EOF diff --git a/core/templates/core/footer.html b/core/templates/core/footer.html index 6e70abfdc..3c14a3366 100644 --- a/core/templates/core/footer.html +++ b/core/templates/core/footer.html @@ -31,7 +31,7 @@
Powered by
-

Version 3.1.0

+

Version 3.1.1

diff --git a/docs/upgrades/2.3.0-to-3.0.0.md b/docs/upgrades/2.3.0-to-3.0.0.md new file mode 100644 index 000000000..7f7e7dacf --- /dev/null +++ b/docs/upgrades/2.3.0-to-3.0.0.md @@ -0,0 +1,23 @@ +# Upgrade from 2.3.0 to 3.0.0 + +This upgrade includes application data changes that require dedicated Django scripts. Back up the database and installation before proceeding. + +## Migration scripts + +Run the following scripts as part of the upgrade: + +```bash +python manage.py runscript rename_app_name +python manage.py runscript migrate_sample_type +python manage.py runscript migrate_optional_values +``` + +The scripts perform these changes: + +- `rename_app_name` updates stored application names after the iSkyLIMS application rename. +- `migrate_sample_type` converts legacy SampleType optional-field indexes to the new mandatory-field names. +- `migrate_optional_values` moves project option-list values into `SamplesProjectsTableOptions`. + +Run them against the upgraded application code and the intended production database. Verify the database backup and settings before executing them. The script inventory is maintained in [UPGRADE_SCRIPTS.md](../../UPGRADE_SCRIPTS.md). + +After completing this upgrade, follow the [3.0.0 to 3.1.0](3.0.0-to-3.1.0.md) guide before moving to later versions. diff --git a/docs/upgrades/3.0.0-to-3.1.0.md b/docs/upgrades/3.0.0-to-3.1.0.md new file mode 100644 index 000000000..2590a6e3a --- /dev/null +++ b/docs/upgrades/3.0.0-to-3.1.0.md @@ -0,0 +1,51 @@ +# Upgrade from 3.0.0 to 3.1.0 + +This upgrade requires a data export and scripts on both sides of the database migrations. Back up the database, persistent documents, configuration, and installation files before proceeding. + +## Required order + +1. Export the existing LibraryPool-to-RunProcess mapping. +2. Run `convert_rawtop_counter_to_int` before migrations. +3. Apply the normal database migrations. +4. Run `library_pool_to_many_relation` after migrations, passing the exported mapping. + +Export the mapping before changing the database schema: + +```bash +mysql --user= --password --host= --port= iskylims \ + -e "SELECT id, run_process_id_id FROM wetlab_library_pool" \ + > /tmp/library_pool_run_process.tsv +``` + +## Container deployment + +Keep the existing `APP_UID` and `APP_GID` values in the selected installation configuration. For rootless Podman, run: + +```bash +bash container_install.sh --engine podman \ + --install_conf conf/my_prod_settings_iskylims.txt \ + --action upgrade \ + --script_before convert_rawtop_counter_to_int \ + --script_after library_pool_to_many_relation,/tmp/library_pool_run_process.tsv \ + 2>&1 | tee ./iskylims_podman_upgrade_3_0_0_to_3_1_0_$(date +%Y%m%d_%H%M%S).log +``` + +For Docker, replace `--engine podman` with `--engine docker` and use the appropriate installation configuration path. + +## Bare-metal deployment + +Update dependencies first: + +```bash +sudo bash install.sh --upgrade dep 2>&1 | tee install_full.log +``` + +Then upgrade the application and run the scripts in their required order: + +```bash +bash install.sh --upgrade app --git_revision 3.1.0 \ + --script_before convert_rawtop_counter_to_int \ + --script_after library_pool_to_many_relation,/tmp/library_pool_run_process.tsv +``` + +Use this special procedure only when crossing from `3.0.0` to `3.1.0`. Later upgrades should use the generic instructions unless another version-specific guide says otherwise. diff --git a/docs/upgrades/README.md b/docs/upgrades/README.md new file mode 100644 index 000000000..b31b848c6 --- /dev/null +++ b/docs/upgrades/README.md @@ -0,0 +1,17 @@ +# Version-specific upgrade guides + +Use these guides when an upgrade crosses a version boundary that requires special data migration or preparation. For upgrades without a listed special path, use the generic procedure in the main [README](../../README.md). Institutional rootless Podman deployments should also follow the current operational guidance in [LEAME](../../LEAME.md). + +Always back up the database, application configuration, persistent documents, and installation files before upgrading. + +## Upgrade path + +Apply every relevant guide in order when skipping releases: + +1. [2.3.0 to 3.0.0](2.3.0-to-3.0.0.md) +2. [3.0.0 to 3.1.0](3.0.0-to-3.1.0.md) +3. 3.1.0 to 3.1.1: no special data-migration scripts are required; use the generic upgrade procedure. + +The supported historical starting point is written as `2.3.0`, rather than `2.x`, because that is the version explicitly documented by the migration scripts. + +For a developer-oriented inventory of all migration scripts, see [UPGRADE_SCRIPTS.md](../../UPGRADE_SCRIPTS.md). diff --git a/install.sh b/install.sh index aa7b09c26..cf802e441 100644 --- a/install.sh +++ b/install.sh @@ -1,6 +1,6 @@ #!/bin/bash -APP_VERSION="3.1.0" +APP_VERSION="3.1.1" # usage: prints the command line help and usage examples. usage() { diff --git a/leame_actualizaciones_previas.md b/leame_actualizaciones_previas.md deleted file mode 100644 index c68cf701a..000000000 --- a/leame_actualizaciones_previas.md +++ /dev/null @@ -1,288 +0,0 @@ -# iSkyLIMS - -[![Django](https://img.shields.io/static/v1?label=Django&message=4.2&color=azul?style=plastic&logo=django)](https://github.com/django/django) -[![Python](https://img.shields.io/static/v1?label=Python&message=3.8.10&color=verde?style=plastic&logo=Python)](https://www.python.org/) -[![Bootstrap](https://img.shields.io/badge/Bootstrap-v5.0-azulvioleta?style=plastic&logo=Bootstrap)](https://getbootstrap.com) -[![versión](https://img.shields.io/badge/versión-3.0.0-naranja?style=plastic&logo=GitHub)](https://github.com/BU-ISCIII/iskylims.git) - -La introducción de la secuenciación masiva (MS) en las instalaciones de genómica ha significado un crecimiento exponencial en la generación de datos, lo que requiere un sistema de seguimiento preciso, desde la preparación de la biblioteca hasta la generación de archivos fastq, el análisis y la entrega al investigador. El software diseñado para manejar esas tareas se llama Sistemas de Gestión de Información de Laboratorio (LIMS), y su software debe adaptarse a las necesidades particulares de su laboratorio de genómica. iSkyLIMS nace con el objetivo de ayudar con las tareas de laboratorio húmedo e implementar un flujo de trabajo que guíe a los laboratorios de genómica en sus actividades, desde la preparación de la biblioteca hasta la producción de datos, reduciendo los posibles errores asociados a la tecnología de alto rendimiento y facilitando el control de calidad de la secuenciación. Además, iSkyLIMS conecta el laboratorio húmedo con el laboratorio seco, facilitando el análisis de datos por parte de bioinformáticos. - -![Imagen](img/iskylims_scheme.png) - -De acuerdo con la infraestructura existente, la secuenciación se realiza en un instrumento Illumina NextSeq. Los datos se almacenan en un dispositivo de almacenamiento masivo NetApp y los archivos fastq se generan (bcl2fastq) en un clúster de cómputo de alto rendimiento Sun Grid Engine (SGE-HPC). Los servidores de aplicaciones ejecutan aplicaciones web para el análisis bioinformático (GALAXY), la aplicación iSkyLIMS y alojan la capa de información de MySQL. El flujo de trabajo de iSkyLIMS WetLab se ocupa del seguimiento y las estadísticas de la ejecución de la secuenciación. El seguimiento de la ejecución pasa por cinco estados: "registrado", el usuario de genómica registra la nueva ejecución de la secuenciación en el sistema, el proceso esperará hasta que la ejecución se complete en la máquina y los datos se transfieran al dispositivo de almacenamiento masivo; "Envío de hoja de muestra", el archivo de hoja de muestra con la información de la ejecución de la secuenciación se copiará en la carpeta de ejecución para el proceso de bcl2fastq; "Procesamiento de datos", se procesan los archivos de parámetros de ejecución y los datos se almacenan en la base de datos; "Estadísticas en ejecución", los datos de desmultiplexación generados en el proceso de bcl2fastq se procesan y almacenan en la base de datos, "Completado", todos los datos se procesan y almacenan correctamente. Se proporcionan estadísticas por muestra, por proyecto, por ejecución y por investigación, así como informes anuales y mensuales. El flujo de trabajo de iSkyLIMS DryLab se encarga de la solicitud de servicios de bioinformática y estadísticas. El usuario solicita servicios que pueden estar asociados con una ejecución de secuenciación. Se proporciona seguimiento de estadísticas y servicios. - -- [iSkyLIMS](#iskylims) - - [Instalación](#instalación) - - [Requisitos previos](#requisitos-previos) - - [Instalación de iSkyLIMS en Docker](#instalación-de-iskylims-en-docker) - - [Instalación de iSkyLIMS en su servidor con Ubuntu/CentOS](#instalación-de-iskylims-en-su-servidor-con-ubuntucentos) - - [Clonar el repositorio de GitHub](#clonar-el-repositorio-de-github) - - [Crear la base de datos de iSkyLIMS y otorgar permisos](#crear-la-base-de-datos-de-iskylims-y-otorgar-permisos) - - [Configuración de ajustes](#configuración-de-ajustes) - - [Ejecutar el script de instalación](#ejecutar-el-script-de-instalación) - - [Actualización a la versión 3.0.0 de iSkyLIMS](#actualización-a-la-versión-300-de-iskylims) - - [Prerrequisitos](#prerrequisitos) - - [Clonar el repositorio de GitHub](#clonar-el-repositorio-de-github-1) - - [Configuración de opciones](#configuración-de-opciones) - - [Ejecución del script de actualización](#ejecución-del-script-de-actualización) - - [Pasos que necesitan permisos de adminsitración](#pasos-que-necesitan-permisos-de-adminsitración) - - [Pasos que no necesitan de permisos de administración](#pasos-que-no-necesitan-de-permisos-de-administración) - - [Qué hacer si algo falla](#qué-hacer-si-algo-falla) - - [Pasos finales de configuración](#pasos-finales-de-configuración) - - [Configuración de SAMBA](#configuración-de-samba) - - [Verificación de correo electrónico](#verificación-de-correo-electrónico) - - [Configurar el servidor Apache](#configurar-el-servidor-apache) - - [Verificación de la instalación](#verificación-de-la-instalación) - - [Documentación de iSkyLIMS](#documentación-de-iskylims) - -## Instalación - -Si tienes algún problema o deseas informar de algún error, por favor, publícalo en [issue](https://github.com/BU-ISCIII/iSkyLIMS/issues) - -### Requisitos previos - -Antes de comenzar la instalación, asegúrate de lo siguiente: - -- Tienes privilegios de **sudo** para instalar los paquetes de software adicionales que iSkyLIMS necesita. -- Dependencias: - - Librerías: -``` - yum groupinstall "Development tools" - yum install zlib-devel bzip2-devel openssl-devel \ - wget httpd-devel mysql-libs sqlite sqlite-devel \ - mariadb-devel mysql-client libffi-devel \ - gnuplot cifs-utils -``` - - lsb_relase: - - RedHat/CentOS: `yum install redhat-lsb-core` - - Ubuntu: `apt install lsb-core lsb-release` -- Base de datos MySQL > 8.0 o MariaDB > 10.4 -- Tienes configurado un servidor local para enviar correos electrónicos. -- git > 2.34 -- Tienes Apache servidor v2.4 -- Tienes Python > 3.8 (si lo compilas debes haber instalado previamente las dependecias de arriba) -- Tienes una conexión a la carpeta compartida de Samba donde se almacenan las carpetas de ejecución (por ejemplo, galera/NGS_Data). -- Dependencias: - - -### Instalación de iSkyLIMS en Docker - -Puedes probar iSkyLIMS creando un contenedor Docker en tu máquina local. - -Clona el repositorio de GitHub de iSkyLIMS y ejecuta el script de Docker para crear el contenedor Docker. - -```bash -git clone https://github.com/BU-ISCIII/iSkyLIMS.git iSkyLIMS -sudo bash docker_install.sh -``` - -El script crea un contenedor de Docker Compose con 3 servicios: - -- web1: contiene la aplicación web iSkyLIMS -- db1: contiene la base de datos MySQL -- samba: contiene el servidor Samba - -Después de crear Docker y tener los servicios en funcionamiento, la estructura de la base de datos y los datos iniciales se cargan en la base de datos. Cuando se complete este paso, se le pedirá que defina al superusuario que tendrá acceso a las páginas de administración de Django. Puede escribir cualquier nombre, pero recomendamos que utilice "admin", ya que más adelante se le pedirá un usuario administrador cuando defina la configuración inicial. - -Siga el mensaje de instrucciones para crear la cuenta del superusuario. - -Cuando el script finalice, abra su navegador escribiendo **localhost:8001** para acceder a iSkyLIMS - -### Instalación de iSkyLIMS en su servidor con Ubuntu/CentOS - -#### Clonar el repositorio de GitHub - -Abra una terminal de Linux y vaya a un directorio donde se descargará el código de iSkyLIMS - -```bash -cd -git clone https://github.com/BU-ISCIII/iskylims.git iskylims -cd iskylims -``` - -#### Crear la base de datos de iSkyLIMS y otorgar permisos - -1. Cree una nueva base de datos llamada "iskylims" (esto es obligatorio). -2. Cree un nuevo usuario con permisos para leer y modificar esa base de datos. -3. Anote el nombre de usuario, la contraseña y la información del servidor de la base de datos. - -#### Configuración de ajustes - -Copia la plantilla de ajustes iniciales en un archivo llamado `install_settings.txt` - -```bash -cp conf/template_install_settings.txt install_settings.txt -``` - -Abra el archivo de configuración con su editor favorito para establecer sus propios valores para la base de datos, la configuración de correo electrónico y la dirección IP local del servidor donde se ejecutará iSkyLIMS. - -```bash -sudo nano install_settings.txt -``` - -#### Ejecutar el script de instalación - -iSkyLIMS debe instalarse en el directorio "/opt". - -Necesitará privilegios de administrador para instalar las dependencias. Para manejar diferentes responsabilidades de instalación dentro de la organización, donde es posible que no sea la persona con privilegios de administrador, nuestro script de instalación tiene estas opciones en el parámetro `--install`: - -- `dep`: para instalar los paquetes de software, así como los paquetes de Python dentro del entorno virtual. Se necesita permisos de administrador. -- `app`: para instalar solo el software de la aplicación iSkyLIMS sin necesidad de tener permisos de administrador. -- `full`: si tiene directamente permisos de administrador, puede instalar tanto las dependencias como la aplicación con esta opción. - -Ejecute uno de los siguientes comandos en una terminal de Linux para la instalación, de acuerdo con la descripción anterior. - -```bash -# para instalar solo las dependencias -sudo bash install.sh --install dep - -# para instalar la aplicación iskylims -bash install.sh --install app - -# para instalar ambos al mismo tiempo -sudo bash install.sh --install full -``` - -### Actualización a la versión 3.0.0 de iSkyLIMS - -Si ya tienes iSkyLIMS en la versión 2.3.0, puedes actualizar a la última versión estable, la 3.0.0. - -La versión 3.0.0 es una versión importante con actualizaciones significativas en dependencias de terceros como Bootstrap. También hemos realizado un gran trabajo en la refactorización y el cambio de nombres de variables/funciones que afectan a la base de datos. Para obtener más detalles sobre los cambios, consulta las notas de la versión. - -#### Prerrequisitos - -Debido a que en esta actualización se modifican muchas tablas en la base de datos, es necesario que hagas una copia de seguridad de: - -- La base de datos de iSkyLIMS. -- La carpeta de iSkyLIMS (carpeta de instalación completa, por ejemplo, /opt/iSkyLIMS). - -Se recomienda encarecidamente que hagas estas copias de seguridad y las guardes de manera segura en caso de que la actualización falle, para poder recuperar tu sistema. Por ejemplo crea una carpeta en `/home/dadmin/backup_pro` que contenga la base de datos y la carpeta de /opt/iskylims para tenerla a mano y poder [restaurar el sistema](#qué-hacer-si-algo-falla). - -#### Clonar el repositorio de GitHub - -También hemos cambiado la forma en que se instala y actualiza iSkyLIMS. A partir de ahora, iSkyLIMS se descarga en una carpeta del usuario y se instala en otro lugar (por ejemplo, /opt/). - -Abre una terminal de Linux y dirígete a un directorio donde se descargará el código de iSkyLIMS. - -```bash -cd < directorio distinto al directorio de instalación > -git clone https://gitlab.isciii.es/BU-ISCIII/iskylims.git iskylims -cd iskylims -``` - -#### Configuración de opciones - -Copia la plantilla de configuración inicial en un archivo llamado install_settings.txt - -```bash -cp conf/template_install_settings.txt install_settings.txt -``` - -Abre el archivo de configuración con tu editor favorito para establecer tus propios valores para la base de datos, la configuración de correo electrónico y la dirección IP local del servidor donde se ejecutará iSkyLIMS. -> Si utilizas un sistema basado en Windows para modificar el archivo, asegúrate de que el archivo se guarde con una codificación amigable para Linux, como ASCII o UTF-8. - -```bash -nano install_settings.txt -``` - -#### Ejecución del script de actualización - -Si en tu organización se requiere que las dependencias u otros elementos que necesiten permisos de administrador sean instalados por una persona diferente a la que instala la aplicación, puedes utilizar el script de instalación en varios pasos de la siguiente manera. - -El script te irá solicitando confirmación en algun paso, si todo está yendo bien sin errores deberás pulsar `y` o `yes` según te lo solicite. - -> Nota: Los errores: "ERROR 1064 (42000) at line 1: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'query' at line 1" son normales ya que se trata del título de las sentencias sql que no deben ejecutarse. Se puede ignorar. - -##### Pasos que necesitan permisos de adminsitración - -En primer lugar, debes cambiar el nombre de la carpeta de la aplicación en la carpeta de instalación (`/opt/iSkyLIMS`): - -```bash -# Necesitas ser usuario root para realizar esta operación -sudo mv /opt/iSkyLIMS /opt/iskylims -``` - -Asegúrate de que la carpeta de instalación tenga los permisos correctos para que la persona que instala la aplicación pueda escribir en esa carpeta. - -```bash -# En el caso de que tengas un script para esta tarea. Necesitarás ajustar este script de acuerdo al cambio en el nombre de la ruta: /opt/iSkyLIMS a /opt/iskylims -sudo /scripts/hardening.sh -``` - -En la terminal de Linux, ejecuta uno de los siguientes comandos que mejor se adapte a ti: - -```bash -# para actualizar solo las dependencias del software. ES NECESARIO DISPONER DE PERMISOS DE ROOT. -sudo bash install.sh --upgrade dep - -# PARA INSTALAR AMBAS COSAS AL MISMO TIEMPO. REQUIERE DE ROOT. SI SE VA A INSTALAR POR OTRA PERSONA SIN ROOT NO HACER ESTO. -sudo bash install.sh --upgrade full --ren_app --script drylab_service_state_migration --script rename_app_name --script rename_sample_sheet_folder --script migrate_sample_type --script migrate_optional_values --tables -``` - -##### Pasos que no necesitan de permisos de administración - -A continuación instalamos la aplicación de iskylims usando el siguiente comando: - -```bash -# para actualizar la aplicación de iskylims, incluyendo los cambios necesarios para la versión en base de datos. NO ES NECESARIO DISPONER DE PERMISOS ROOT. -bash install.sh --upgrade app --ren_app --script drylab_service_state_migration --script rename_app_name --script rename_sample_sheet_folder --script migrate_sample_type --script migrate_optional_values --tables -``` - -Por último, asegúrate que los permisos de la carpeta son correctos. - -```bash -# En el caso de que tengas un script para esta tarea. En esta versión han cambiado algunas rutas a ficheros, es posible que tengas que ajustar el script en consecuencia. -sudo /scripts/hardening.sh -``` - -#### Qué hacer si algo falla - -Cuando actualizamos la aplicación usando el script estamos realizando varios cambios en la base de datos. Si algo falla tenemos que restaurar el estado anterior, antes de que hubiesemos realizado ninguna acción. - -Necesitamos copiar de vuelta nuestro backup de carpet ade aplicación a /opt/iSkyLIMS (o la carpeta de instalación de nuestra elección), y restaurar la base de datos realizando algo como lo siguiente: - -```bash -sudo rm -rf /opt/iskylims -sudo cp -r /home/dadmin/backup_prod/iSkyLIMS/ /opt/ -sudo /scripts/hardening.sh -mysql -u iskylims -h dmysqlps.isciiides.es -p -# drop database iskylims; -# create database iskylims; -mysql -u iskylims -h dmysqlps.isciiides.es iskylims < /home/dadmin/backup_prod/bk_iSkyLIMS_202310160737.sql -``` - -### Pasos finales de configuración - -#### Configuración de SAMBA - -- Inicia sesión con la cuenta de administrador. -- Ve a Massive Sequencing -![Ir a WetLab](img/got_to_wetlab.png){width:50px} -- Ve a Configuración -> Configuración de SAMBA -- Completa el formulario con los parámetros apropiados para la carpeta compartida de SAMBA: -![Formulario SAMBA](img/samba_form.png) - -#### Verificación de correo electrónico - -- Ve a Massive Sequencing -- Ve a Configuración -> Configuración de correo electrónico -- Completa el formulario con los parámetros necesarios para la configuración de correo electrónico y trata de enviar un correo de prueba. - -#### Configurar el servidor Apache - -Copia el archivo de configuración de Apache que se encuentra en la carpeta `conf` según tu distribución dentro del directorio de configuración de Apache y cambia el nombre a iskylims.conf. Revisa cualquier requerimiento de tu sistema, se trata solo de un ejemplo. - -#### Verificación de la instalación - -Abre el navegador y escribe "localhost" o la "IP local del servidor" para comprobar que iSkyLIMS está en funcionamiento. - -También puedes verificar algunas funcionalidades mientras compruebas las conexiones de SAMBA y la base de datos usando: - -- Ve a [configurationTest](https://iskylims.isciii.es/wetlab/configurationTest/) -- Haz clic en Enviar -- Verifica todas las pestañas para asegurarte de que cada conexión sea exitosa. -- Ejecuta las 3 pruebas para cada máquina de secuenciación: MiSeq, NextSeq y NovaSeq. - -### Documentación de iSkyLIMS - -La documentación de iSkyLIMS está disponible en [https://iskylims.readthedocs.io/en/latest](https://iskylims.readthedocs.io/en/latest) diff --git a/readme_upgrade_docs_previous.md b/readme_upgrade_docs_previous.md deleted file mode 100644 index 66a597a94..000000000 --- a/readme_upgrade_docs_previous.md +++ /dev/null @@ -1,290 +0,0 @@ -# iSkyLIMS - -[![Django](https://img.shields.io/static/v1?label=Django&message=4.2&color=blue?style=plastic&logo=django)](https://github.com/django/django) -[![Python](https://img.shields.io/static/v1?label=Python&message=3.8.10&color=green?style=plastic&logo=Python)](https://www.python.org/) -[![Bootstrap](https://img.shields.io/badge/Bootstrap-v5.0-blueviolet?style=plastic&logo=Bootstrap)](https://getbootstrap.com) -[![version](https://img.shields.io/badge/version-3.0.0-orange?style=plastic&logo=GitHub)](https://github.com/BU-ISCIII/iskylims.git) - -The introduction of massive sequencing (MS) in genomics facilities has meant an exponential growth in data generation, requiring a precise tracking system, from library preparation to fastq file generation, analysis and delivery to the researcher. Software designed to handle those tasks are called Laboratory Information Management Systems (LIMS), and its software has to be adapted to their own genomics laboratory particular needs. iSkyLIMS is born with the aim of helping with the wet laboratory tasks, and implementing a workflow that guides genomics labs on their activities from library preparation to data production, reducing potential errors associated to high throughput technology, and facilitating the quality control of the sequencing. Also, iSkyLIMS connects the wet lab with dry lab facilitating data analysis by bioinformaticians. - -![Image](img/iskylims_scheme.png) - -According to existent infrastructure sequencing is performed on an Illumina NextSeq instrument. Data is stored in NetApp mass storage device and fastq files are generated (bcl2fastq) on a Sun Grid Engine High Performance Computing cluster (SGE-HPC). -Application servers run web applications for bioinformatics analysis (GALAXY), the iSkyLIMS app, and host the MySQL information tier. iSkyLIMS WetLab workflow deals with sequencing run tracking and statistics. Run tracking passes through five states: "recorded” genomics user record the new sequencing run into the system, the process will wait till run is completed by the machine and data is transferred to the mass storage device; “Sample sheet sent” sample sheet file with the sequencing run information will be copied to the run folder for bcl2fastq process; “Processing data” run parameters files are processed and data is stored in the database; “Running stats” demultiplexing data generated in bcl2fastq process is processed and stored into the database, “Completed” all data is processed and stored successfully. Statistics per sample, per project, per run and per investigation are provided, as well as annual and monthly reports. iSkyLIMS DryLab workflow deals with bioinformatics services request and statistics. User request services that can be associated with a sequencing run. Stats and services tracking is provided. - -- [iSkyLIMS](#iskylims) - - [Installation](#installation) - - [Pre-requisites](#pre-requisites) - - [iSkyLIMS docker installation](#iskylims-docker-installation) - - [Install iSkyLIMS in your server running ubuntu/CentOS](#install-iskylims-in-your-server-running-ubuntucentos) - - [Clone github repository](#clone-github-repository) - - [Create iskylims database and grant permissions](#create-iskylims-database-and-grant-permissions) - - [Configuration settings](#configuration-settings) - - [Run installation script](#run-installation-script) - - [Upgrade to iSkyLIMS version 3.0.0](#upgrade-to-iskylims-version-300) - - [Pre-requisites](#pre-requisites-1) - - [Clone github repository](#clone-github-repository-1) - - [Configuration settings](#configuration-settings-1) - - [Running upgrade script](#running-upgrade-script) - - [Steps requiring root](#steps-requiring-root) - - [Steps not requiring root](#steps-not-requiring-root) - - [What to do if something fails](#what-to-do-if-something-fails) - - [Final configuration steps](#final-configuration-steps) - - [SAMBA configurarion](#samba-configurarion) - - [Email verification](#email-verification) - - [Configure Apache server](#configure-apache-server) - - [Verification of the installation](#verification-of-the-installation) - - [iSkyLIMS documentation](#iskylims-documentation) - -## Installation - -For any problems or bug reporting please post us an [issue](https://github.com/BU-ISCIII/iSkyLIMS/issues) - -### Pre-requisites - -Before starting the installation make sure : - -- You have **sudo privileges** to install the additional software packets that iSkyLIMS needs. -- Database MySQL > 8.0 or MariaDB > 10.4 -- Local server configured for sending emails -- Apache server v2.4 -- git > 2.34 -- Python > 3.8 -- Connection to samba shared folder where run folders are stored (p.e galera/NGS_Data) -- Dependencies: - - lsb_release: - - RedHat/CentOS: ```yum install redhat-lsb-core``` - - Ubuntu: ```apt install lsb-core lsb-release``` - -### iSkyLIMS docker installation - -You can test iSkyLIMS by creating a docker container on your local machine. - -Clone the iSkyLIMS github repository and run the docker script to create the docker - -```bash -git clone https://github.com/BU-ISCIII/iSkyLIMS.git iSkyLIMS -sudo bash docker_install.sh -``` - -The script creates a docker compose container with 3 services: - -- web1: contains the iSkyLIMS web application -- db1: contains the mySQL database -- samba: contains samba server - -After Docker is created and services are up, database structure and initial data are loaded into database. When this step is completed, you will be asked to define the super user which will have access to django admin pages. You can type any name, but we recommend that you use "admin", because admin user is requested later on when defining the initial settings. - -Follow the prompt message to create the super user account. - -When script ends open your navigator typing **localhost:8001** to access to iSkyLIMS - -### Install iSkyLIMS in your server running ubuntu/CentOS - -#### Clone github repository - -Open a linux terminal and move to a directory where iSkyLIMS code will be -downloaded - -```bash -cd < your personal folder > -git clone https://github.com/BU-ISCIII/iskylims.git iskylims -cd iskylims -``` - -#### Create iskylims database and grant permissions - -1. Create a new database named "iskylims" (this is mandatory) -2. Create a new user with permission to read and modify that database. -3. Write down user, passwd and db server info. - -#### Configuration settings - -Copy the initial setting template into a file named install_settings.txt - -```bash -cp conf/template_install_settings.txt install_settings.txt -``` - -Open with your favourite editor the configuration file to set your own values for -database ,email settings and the local IP of the server where iSkyLIMS will run. - -```bash -nano install_settings.txt -``` - -#### Run installation script - -iSkyLIMS should be installed on the "/opt" directory. - -You will need sudo privileges for installing dependencies. In order to handle different installation responsibilities inside the organization, where you may not be the person with root privileges, our instalation script has these options in ```--install``` parameter: - -- dep: to install the software packages as well as python packages inside the virtual environment. Root is needed. -- app: to install only the iSkyLIMS application software without need of being root. -- full: if you directly have root permissions you can install both deps and app at the same time with this option. - -Execute one of the following commands in a linux terminal to install, according as -above description. - -```bash -# to install only software packages dependences -sudo bash install.sh --install dep - -# to install only iSkyLIMS application -bash install.sh --install app - -# to install both software -sudo bash install.sh --install full -``` - -### Upgrade to iSkyLIMS version 3.0.0 - -If you have already iSkyLIMS on version 2.3.0 you can upgrade to the latest stable version 3.0.0. - -Version 3.0.0 is a major release with important upgrades in third parties dependencies like bootstrap. Also, we 've done a huge work on refactoring and variables/function renaming that affects the database. For more details about the changes see the release notes. - -If you requires to upgrade from version 3.0.0 to the latest one 3.1.x and in your system you have already defined library pools, then you need to collect this data, before to run the upgrade script. For more information read [Pre-requisites for upgrade from 3.0.0 to 3.1.x](#pre-requisites-for-upgrade-from-30x-to-31x) - -#### Pre-requisites - -Because in this upgrade many tables in database are modified it is required that you backup: - -- iSkyLIMS database -- iSkyLIMS folder (complete installation folder, p.e /opt/iSkyLIMS) - -##### Pre-requisites for upgrade from 3.0.x to 3.1.x - -- Perform a backup of LibraryPool by running the folowing command - -```bash - mysql --user= --password= --host= --port= iskylims -e "SELECT* FROM wetlab_library_pool" > -``` - -It is highly recomended that you made these backups and keep them safely in case of upgrade failure, to recover your system. - -#### Clone github repository - -We've also change the way that iSkyLIMS is installed and upgraded. From now on iskylims is downloaded in a user folder and installed elsewhere (p.e /opt/). - -Open a linux terminal and move to a directory where iSkyLIMS code will be -downloaded - -```bash -cd < your personal folder > -git clone https://github.com/BU-ISCIII/iSkyLIMS.git iskylims -cd iskylims -``` - -#### Configuration settings - -Copy the initial setting template into a file named install_settings.txt - -```bash -cp conf/template_install_settings.txt install_settings.txt -``` - -Open with your favourite editor the configuration file to set your own values for -database ,email settings and the local IP of the server where iSkyLIMS will run. -> If you use a windows-based system for modifying the file, make sure the file is saved using a linux-friendly encoding like ASCII or UTF-8 - -```bash -sudo nano install_settings.txt -``` - -#### Running upgrade script - -If your organization requires that dependencies / stuff that needs root are installed by a different person that install the application the you can use the install script in several steps as follows. - -First you need to rename the folder app name in the installation folder (`/opt/iSkyLIMS`): - -##### Steps requiring root - -```bash -# You need root for this operation -sudo mv /opt/iSkyLIMS /opt/iskylims -``` - -Make sure that the installation folder has the correct permissions so the person installing the app can write in that folder. - -```bash -# In case you have a script for this task. You'll need to adjust this script according to the name changing: /opt/iSkyLIMS to /opt/iskylims -/scripts/hardening.sh -``` - -In the linux terminal execute one of the following command that fit better to you: - -```bash -# to upgrade only software packages dependences. NEEDS ROOT. -sudo bash install.sh --upgrade dep - -# to install both software. NEEDS ROOT. -sudo bash install.sh --upgrade full --ren_app --script drylab_service_state_migration --script rename_app_name --script rename_sample_sheet_folder --script migrate_sample_type --script migrate_optional_values --tables -``` - -##### Steps not requiring root - -Next you need to upgrade iskylims app. Please use the command below: - -```bash -# to upgrade only iSkyLIMS application including changes required in this release. DOES NOT NEED ROOT. -bash install.sh --upgrade app --ren_app --script drylab_service_state_migration --script rename_app_name --script rename_sample_sheet_folder --script migrate_sample_type --script migrate_optional_values --tables -``` - -Make sure that the installation folder has the correct permissions. - -```bash -# In case you have a script for this task. Some paths have changed in this version, so you may need to adjust your hardening script. -/scripts/hardening.sh -``` - -#### What to do if something fails - -When we upgrade using the installation script we are performing several changes in the database. If something fails we need to restore the app situation before anything happened and start all over. - -We need to copy back the full `/opt/iSkyLIMS` folder back to `/opt` (or your installation path preference), and restore the database doing something like this: - -```bash -sudo rm -rf /opt/iskylims -sudo cp -r /home/dadmin/backup_prod/iSkyLIMS/ /opt/ -sudo /scripts/hardening.sh -mysql -u iskylims -h dmysqlps.isciiides.es -# drop database iskylims; -# create database iskylims; -mysql -u iskylims -h dmysqlps.isciiides.es iskylims < /home/dadmin/backup_prod/bk_iSkyLIMS_202310160737.sql -``` - -### Final configuration steps - -#### SAMBA configurarion - -- Login with admin account. -- Go to Massive sequencing -![go_to_wetlab](img/got_to_wetlab.png){width:50px} -- Go to Configuration -> Samba configuration -- Fill the form with the appropiate params for the samba shared folder: -![samba form](img/samba_form.png) - -#### Email verification - -- Go to Massive sequencing -- Go to Configuration -> Email configuration -- Fill the form with the needed params for your email configuration and try to send a test email. - -#### Configure Apache server - -Copy the apache configuration file according to your distribution inside the apache configutation directory and rename it to iskylims.conf - -#### Verification of the installation - -Open the navigator and type "localhost" or the "server local IP" and check that iSkyLIMs is running. - -You can also check some of the functionality, while also checking samba and database connections using: - -- Go to [configuration test](https://iskylims.isciii.es/wetlab/configurationTest/) -- Click submit -- Check all tabs so every connectin is successful. -- Run the 3 tests for each sequencing machine: MiSeq, NextSeq and NovaSeq. - -### iSkyLIMS documentation - -iSkyLIMS documentation is available at [https://iskylims.readthedocs.io/en/latest](https://iskylims.readthedocs.io/en/latest)