Installation on a local machine

It is important to note that there are minimum hardware requirements to be able to run the application depending on the tools to be used. Below is a table describing the different functions and their corresponding minimum requirements.

Description	Requirements
Cataloging module: This functionality allows cataloging and organizing new resources based on a form described by the user. Processing must be limited to one at a time to avoid overloading the machine.	4GB RAM
Advanced search with cross-referencing of information related to word processing, OCR, transcription and automatic labeling.	16GB RAM

Installing Docker

To install ArchiHUB on a local machine, you need Docker and docker compose installed on the operating system. Docker is a tool that virtualizes the different services the archive needs to work. Throughout this guide, we will show how to use it to start the archive, make backups and update the application.

Besides Docker, the installer needs git and openssl. On Windows, run the commands in this guide from WSL or Git Bash.

ArchiHUB components

The ArchiHUB system is made up of two main components:

Backend: a Python API built with FastAPI that serves as the foundation of the system. It uses MongoDB as its database, Elasticsearch for search and Celery with Redis for the processing queue.
Frontend: a Next.js application, served behind nginx, that handles all cataloging, processing and browsing tasks.

The frontend is interchangeable: the API allows custom interfaces to be built for each user’s requirements.

The getting-started repository gathers the different ways of installing ArchiHUB. A single-machine installation uses the files in the local-machine folder, which already includes the compiled frontend. The backend is downloaded during installation.

Installation

Download the repository with the installation scripts

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

Run the installer
Ventana de terminal
```
./install.sh
```
The installer:
- creates archihub/.env from archihub/.env.bak, with passwords and keys randomly generated for this installation;
- creates the data folders (original, temporal, userfiles, webfiles, data/mongodb and data/elastic);
- downloads the backend into archihub/backend.
If archihub/.env already exists, the installer leaves it alone: its credentials are the ones the existing database was created with. The archihub/backend folder, however, is deleted and downloaded again, together with any plugins installed in it; to update an existing installation, follow the update guide instead of running the installer again. To download a specific backend branch, use BACKEND_BRANCH=<branch> ./install.sh.
Review archihub/.env

Every variable is explained in the file itself. The most important ones are:
- ENVIRONMENT_NAME: names the database and the search index (archihub-<name>).
- BACKEND_PORT: the port the backend is published on. 11000 by default.
- REDIRECT_URL: the public address of the frontend, used in password-recovery emails.
Do not change FERNET_KEY once the application is in use: it encrypts data such as AI provider keys, which cannot be read with a different key. MONGO_INITDB_ROOT_PASSWORD is applied only when the database is created; changing it later also requires changing the user’s password in MongoDB.
Check the backend address in the frontend

The browser reaches the backend at the URL_API address in archihub/frontend/build/public/config.json. It defaults to http://localhost:11000, which works if you use the application from the same machine and did not change BACKEND_PORT. If other computers will access it, set the machine’s address there, for example http://192.168.1.20:11000.
Start the application
Ventana de terminal
```
cd archihub
docker compose up -d --build
```
The first run builds the backend and frontend images, which can take several minutes.
Check the status of the services

Option 1 - Docker Desktop: open the “Containers” tab and check that the archihub group is running.

Option 2 - Terminal:
Ventana de terminal
```
docker compose ps
```
Open the application

Go to http://localhost/ in your browser. On the first visit, the application asks you to create the administrator account and prepares the initial configuration.

Note: If the services do not show as running, wait a few minutes and check again. Elasticsearch takes the longest to start, and the backend waits for it.

Installing without the installer

If you cannot run install.sh, you can do the same steps by hand from the local-machine folder:

Copy archihub/.env.bak to archihub/.env and replace every __GENERATE__ with a random value. The file itself explains how to generate them: openssl rand -hex 32 for the passwords, JWT_SECRET_KEY and NODE_TOKEN, and openssl rand -base64 32 | tr '+/' '-_' for FERNET_KEY.
Create the folders original, temporal, userfiles, webfiles, data/mongodb and data/elastic. Create them as your own user before starting the containers: Elasticsearch does not start if its data folder belongs to root.

Download the backend into archihub/backend:

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

Then continue from step 3.

Folder layout

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

archihub: the installation’s configuration (.env and docker-compose.yml), the compiled frontend and the backend code.
webfiles: ArchiHUB supports a wide variety of documents that you can upload without worrying about the format. To facilitate viewing and standardize formats, our tool takes care of generating web versions of the documents. This allows you to access and view your files consistently and smoothly, regardless of the original format.
userfiles: this folder stores files generated by users, such as mass processing reports or inventories requested from the cataloging module.
temporal: for some processing cases it is necessary to manipulate temporary files, this folder is used for that.
original: the original files of the documents are stored here, in a folder structure by year and month. The path of the original is the same as that of the web versions.
data: this is the persistent data from both the database and the index. This folder is for system use only and should not be modified.

Services

docker-compose.yml starts MongoDB, Elasticsearch, Redis, the backend, a processing node for the default queue and the frontend. MongoDB, Elasticsearch and Redis are published on 127.0.0.1 only, so they are not exposed to the network.

The file also contains optional services, commented out; enable one by uncommenting its block:

celery_beat: the scheduler for periodic tasks. There must be exactly one in the whole installation.
celery_worker_queues: a node for the high, medium and low queues used by some plugins (for example, automatic transcription), in a version with and one without GPU. See processing nodes.
archihub_ollama: local language models. See Ollama.

Once you’re ready, we can continue with the first steps in ArchiHUB.