Instalación en una máquina local

Es importante destacar que existen requerimientos mínimos de hardware para poder ejecutar el aplicativo en función de las herramientas que se deseen utilizar. A continuación, se presenta una tabla que describe las distintas funciones junto con sus requerimientos mínimos correspondientes.

Descripción	Requerimientos
Módulo de catalogación: Esta funcionalidad permite catalogar y organizar nuevos recursos en base a un formulario descrito por el usuario. Los procesamientos deben estar límitados a uno al tiempo para evitar sobrecargar la máquina.	4GB RAM
Búsqueda avanzada con cruces de información relacionada al procesamiento de texto, OCR, transcripción y etiquetado automático.	16GB RAM

Instalación de Docker en la máquina

Para instalar ArchiHUB en una máquina local, es necesario contar con Docker y docker compose instalados en el sistema operativo. Docker es una herramienta que permite virtualizar los diferentes servicios necesarios para el correcto funcionamiento del archivo. A lo largo de esta guía, se mostrará cómo utilizar esta herramienta para poner en marcha el archivo, realizar copias de seguridad y actualizar la herramienta.

Además de Docker, el instalador necesita git y openssl. En Windows, ejecuta los comandos de esta guía desde WSL o desde Git Bash.

Componentes de ArchiHUB

El sistema ArchiHUB está compuesto por dos componentes principales:

Backend: una API desarrollada en Python con FastAPI que sirve como base del sistema. Usa MongoDB como base de datos, Elasticsearch para las búsquedas y Celery con Redis para la fila de procesamientos.
Frontend: una aplicación Next.js, servida detrás de nginx, que gestiona todas las tareas de catalogación, procesamiento y consulta.

El frontend es intercambiable: la API permite desarrollar interfaces personalizadas según los requerimientos de cada usuario.

El repositorio getting-started centraliza las diferentes formas de instalar ArchiHUB. Para una instalación en una sola máquina se usan los archivos de la carpeta local-machine, que ya incluye el frontend compilado. El backend se descarga durante la instalación.

Instalación

Descargar el repositorio con los scripts de instalación

git clone https://github.com/Archihub-App/getting-started
cd getting-started/local-machine

Ejecutar el instalador
Ventana de terminal
```
./install.sh
```
El instalador:
- crea el archivo archihub/.env a partir de archihub/.env.bak, con contraseñas y llaves generadas al azar para esta instalación;
- crea las carpetas de datos (original, temporal, userfiles, webfiles, data/mongodb y data/elastic);
- descarga el backend en archihub/backend.
Si archihub/.env ya existe, el instalador no lo modifica: sus credenciales son las de la base de datos ya creada. En cambio, la carpeta archihub/backend sí se borra y se descarga de nuevo, junto con los plugins instalados en ella; para actualizar una instalación existente sigue la guía de actualización en lugar de volver a ejecutar el instalador. Para descargar una rama concreta del backend usa BACKEND_BRANCH=<rama> ./install.sh.
Revisar el archivo archihub/.env

Cada variable está explicada en el mismo archivo. Las más importantes son:
- ENVIRONMENT_NAME: da nombre a la base de datos y al índice de búsqueda (archihub-<nombre>).
- BACKEND_PORT: puerto en el que se publica el backend. Por defecto es 11000.
- REDIRECT_URL: dirección pública del frontend, usada en los correos de recuperación de contraseña.
No cambies FERNET_KEY una vez que el aplicativo esté en uso: con ella se cifran datos como las llaves de los proveedores de IA, que no se pueden leer con una llave distinta. MONGO_INITDB_ROOT_PASSWORD solo se aplica al crear la base de datos; cambiarla después exige cambiar también la contraseña del usuario en MongoDB.
Revisar la dirección del backend en el frontend

El navegador llega al backend por la dirección URL_API del archivo archihub/frontend/build/public/config.json. Por defecto es http://localhost:11000, que sirve si usas el aplicativo desde la misma máquina y no cambiaste BACKEND_PORT. Si vas a acceder desde otros equipos, pon ahí la dirección de la máquina, por ejemplo http://192.168.1.20:11000.
Arrancar el aplicativo
Ventana de terminal
```
cd archihub
docker compose up -d --build
```
La primera vez se construyen las imágenes del backend y del frontend, lo que puede tardar varios minutos.
Verificar el estado de los servicios

Opción 1 - Docker Desktop: abre la pestaña “Containers” y verifica que el grupo archihub aparezca activo.

Opción 2 - Terminal:
Ventana de terminal
```
docker compose ps
```
Acceder a la aplicación

Abre http://localhost/ en el navegador. La primera vez, el aplicativo pide crear el usuario administrador y prepara la configuración inicial.

Nota: Si los servicios no aparecen como activos, espera unos minutos y verifica nuevamente. Elasticsearch es el que más tarda en arrancar, y el backend lo espera antes de iniciar.

Instalación sin el instalador

Si no puedes ejecutar install.sh, puedes hacer los mismos pasos a mano desde la carpeta local-machine:

Copia archihub/.env.bak a archihub/.env y reemplaza cada __GENERATE__ por un valor aleatorio. El propio archivo indica cómo generarlos: openssl rand -hex 32 para las contraseñas, JWT_SECRET_KEY y NODE_TOKEN, y openssl rand -base64 32 | tr '+/' '-_' para FERNET_KEY.
Crea las carpetas original, temporal, userfiles, webfiles, data/mongodb y data/elastic. Créalas con tu usuario antes de arrancar los contenedores: Elasticsearch no arranca si su carpeta de datos pertenece a root.

Descarga el backend en archihub/backend:

git clone https://github.com/Archihub-App/archihub-backend.git archihub/backend

Luego sigue desde el paso 3.

Organización de las carpetas

├── local-machine
│   ├── install.sh
│   ├── archihub
│   │   ├── .env
│   │   ├── docker-compose.yml
│   │   ├── frontend
│   │   ├── backend
│   ├── webfiles
│   ├── userfiles
│   ├── temporal
│   ├── original
│   ├── data
│   │   ├── mongodb
│   │   ├── elastic

archihub: la configuración de la instalación (.env y docker-compose.yml), el frontend compilado y el código del backend.
webfiles: ArchiHUB soporta una amplia variedad de documentos que puedes cargar sin preocuparte por el formato. Para facilitar la visualización y estandarizar los formatos, nuestra herramienta se encarga de generar versiones web de los documentos. Esto te permite acceder y ver tus archivos de manera consistente y sin complicaciones, independientemente del formato original.
userfiles: en esta carpeta se guardan los archivos generados por los usuarios, pueden ser reportes de procesamiento masivo o inventarios que se solicitan desde el módulo de catalogación.
temporal: para algunos casos de procesamiento es necesario manipular archivos temporales, esta carpeta se usa para eso.
original: acá se almacenan los archivos originales de los documentos. Se guardan en una estructura de carpetas por año y mes, y la ruta del original es la misma que la de las versiones web.
data: estos son los datos persistentes tanto de la base de datos como del índice. Esta carpeta es para uso exclusivo del sistema y no debe ser modificada.

Servicios

docker-compose.yml levanta MongoDB, Elasticsearch, Redis, el backend, un nodo de procesamiento para la fila por defecto y el frontend. MongoDB, Elasticsearch y Redis solo se publican en 127.0.0.1, de modo que no quedan expuestos a la red.

El archivo trae comentados otros servicios opcionales, que se activan quitando el comentario del bloque correspondiente:

celery_beat: el planificador de tareas periódicas. Debe haber uno solo en toda la instalación.
celery_worker_queues: un nodo para las filas high, medium y low, que usan algunos plugins (por ejemplo, la transcripción automática), en versión con y sin GPU. Ver nodos de procesamiento.
archihub_ollama: modelos de lenguaje locales. Ver Ollama.

Una vez estés listo podemos seguir con los primeros pasos en ArchiHUB.