> For the complete documentation index, see [llms.txt](https://es-kb.topopool.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://es-kb.topopool.com/primeros-pasos/instalacion.md).

# Instalación y actualización

## Antes de empezar

Existen tres formas de instalar cardano-node:

1. **Compilar desde el código fuente** (esta guía): más trabajo, pero control total sobre la versión y el entorno.
2. **Binarios pre-compilados**: descargá `cardano-node` y `cardano-cli` directamente desde los [releases en GitHub](https://github.com/IntersectMBO/cardano-node/releases). Más rápido si solo necesitás actualizar.
3. **Docker**: útil para entornos de prueba o si ya usás contenedores.

Las versiones que vamos a instalar en esta guía son:

| Componente   | Versión  |
| ------------ | -------- |
| GHC          | 9.6.7    |
| Cabal        | 3.12.1.0 |
| cardano-node | 11.0.1   |

***

## Crear el directorio para ejecutables

{% hint style="info" %}
Solo necesario en instalaciones nuevas.
{% endhint %}

```bash
mkdir -p ~/.local/bin
```

## Variables de entorno

Definimos las variables que necesita el nodo para funcionar correctamente. Abrimos `~/.bashrc` y agregamos al final:

{% hint style="info" %}
Reemplazá `TU_USUARIO` con tu nombre de usuario real. Podés verificarlo con `whoami`.

Solo necesario en instalaciones nuevas.
{% endhint %}

{% code title="\~/.bashrc" %}

```bash
# Cardano node
export PATH="/home/TU_USUARIO/.local/bin:$PATH"
export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"
export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"
export CARDANO_NODE_SOCKET_PATH=/home/TU_USUARIO/cardano-node/db/block/node.socket
```

{% endcode %}

Aplicamos los cambios a la sesión actual:

```bash
source ~/.bashrc
```

***

## Instalar ghcup

{% hint style="info" %}
Solo necesario en instalaciones nuevas.
{% endhint %}

`ghcup` es el gestor de toolchain de Haskell. Nos permite instalar y cambiar versiones de GHC y Cabal fácilmente sin ensuciar el sistema.

```bash
mkdir -p ~/src && cd ~/src
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh
```

Durante la instalación:

* Presioná **ENTER** dos veces para aceptar.
* Cuando pregunte por el **HLS** (Haskell Language Server), podés responder **NO** — no lo necesitamos.
* Cuando pregunte si agrega `ghcup` al `$PATH` automáticamente, respondé **YES**.

***

## Instalar GHC

{% hint style="info" %}
Podés saltar este paso si `ghcup list` ya muestra GHC 9.6.7 instalado y activo.
{% endhint %}

```bash
source ~/.bashrc

ghcup upgrade
ghcup install ghc 9.6.7
ghcup set ghc 9.6.7
ghc --version
```

***

## Instalar Cabal

{% hint style="info" %}
Podés saltar este paso si `ghcup list` ya muestra Cabal 3.12.1.0 instalado y activo.
{% endhint %}

{% tabs %}
{% tab title="Nueva instalación" %}

```bash
ghcup install cabal 3.12.1.0
ghcup set cabal 3.12.1.0
cabal --version

cabal clean && cabal update
```

{% endtab %}

{% tab title="Actualización" %}

```bash
ghcup install cabal 3.12.1.0
ghcup set cabal 3.12.1.0
# Eliminamos la versión anterior (ajustá el número según lo que tengas)
ghcup rm cabal 3.10.3.0
cabal --version

cabal clean && cabal update
```

{% endtab %}
{% endtabs %}

***

## Instalar libsodium (fork IOHK)

Cardano usa un fork de `libsodium` mantenido por IOHK que incluye funciones criptográficas adicionales no presentes en la versión oficial.

{% hint style="info" %}
Solo necesario en instalaciones nuevas.
{% endhint %}

```bash
cd ~/src

git clone https://github.com/input-output-hk/libsodium
cd libsodium
git checkout dbb48cc
./autogen.sh
./configure
make
sudo make install
```

***

## Instalar libsecp256k1

{% hint style="info" %}
Solo necesario en instalaciones nuevas o si venís de una versión anterior a la 1.35.0.
{% endhint %}

```bash
cd ~/src
git clone https://github.com/bitcoin-core/secp256k1
cd secp256k1
git checkout ac83be33
./autogen.sh
./configure --prefix=/usr --enable-module-schnorrsig --enable-experimental
make
sudo make install
```

***

## Instalar blst

La versión correcta de `blst` la obtenemos dinámicamente desde el `flake.lock` de `iohk-nix`, que es la fuente de verdad para las dependencias del proyecto:

```bash
BLST_VERSION=$(curl -s https://raw.githubusercontent.com/input-output-hk/iohk-nix/master/flake.lock | jq -r '.nodes.blst.original.ref')
echo "Usando blst versión: ${BLST_VERSION}"
```

Una vez identificada la versión, la instalamos:

```bash
cd ~/src

: ${BLST_VERSION:='v0.3.11'}
git clone --depth 1 --branch ${BLST_VERSION} https://github.com/supranational/blst
cd blst
./build.sh
cat > libblst.pc << EOF
prefix=/usr/local
exec_prefix=\${prefix}
libdir=\${exec_prefix}/lib
includedir=\${prefix}/include

Name: libblst
Description: Multilingual BLS12-381 signature library
URL: https://github.com/supranational/blst
Version: ${BLST_VERSION#v}
Cflags: -I\${includedir}
Libs: -L\${libdir} -lblst
EOF
sudo cp libblst.pc /usr/local/lib/pkgconfig/
sudo cp bindings/blst_aux.h bindings/blst.h bindings/blst.hpp /usr/local/include/
sudo cp libblst.a /usr/local/lib
sudo chmod u=rw,go=r /usr/local/{lib/{libblst.a,pkgconfig/libblst.pc},include/{blst.{h,hpp},blst_aux.h}}
```

***

## Clonar el repositorio de cardano-node

{% hint style="info" %}
Solo necesario en instalaciones nuevas.
{% endhint %}

```bash
cd ~
git clone https://github.com/IntersectMBO/cardano-node.git
```

***

## Backup de ejecutables (solo en actualizaciones)

{% hint style="warning" %}
Antes de sobreescribir los binarios actuales, guardamos una copia. Si algo falla, el rollback es inmediato.
{% endhint %}

```bash
cd ~/.local/bin
cp cardano-node cardano-node.10.x
cp cardano-cli cardano-cli.10.x
```

Ajustá el sufijo al número de versión que estás reemplazando.

***

## Compilar cardano-node 11.0.1

```bash
cd ~/cardano-node
git fetch --all --recurse-submodules --tags
git switch -d tags/11.0.1

echo "with-compiler: ghc-9.6.7" >> cabal.project.local

cabal update
cabal build exe:cardano-node cardano-cli
```

{% hint style="info" %}
Usamos `cabal build exe:cardano-node cardano-cli` en lugar de `cabal build all` porque compilar todo el repositorio incluye tests y herramientas auxiliares que no necesitamos, y lleva bastante más tiempo.

La compilación puede tomar entre 20 y 60 minutos dependiendo del hardware. Es normal.
{% endhint %}

***

## Copiar los ejecutables

Para actualizar puede que necesités detener el nodo primero:

```bash
sudo systemctl stop <NOMBRE-DEL-SERVICIO>
```

Copiamos los ejecutables recién compilados. Usamos `cabal list-bin` para encontrar la ruta exacta (el script `scripts/bin-path.sh` de versiones anteriores ya no existe):

```bash
cp -p "$(cabal list-bin cardano-node)" ~/.local/bin/
cp -p "$(cabal list-bin cardano-cli)" ~/.local/bin/

# Opcional: si también querés el submit-api
cp -p "$(cabal list-bin cardano-submit-api)" ~/.local/bin/
```

Verificamos la instalación:

```bash
cardano-node --version
cardano-cli --version
```

***

## Reiniciar el nodo

```bash
sudo systemctl restart <NOMBRE-DEL-SERVICIO>
```

Revisamos los logs para confirmar que arrancó correctamente:

```bash
journalctl -fu <NOMBRE-DEL-SERVICIO>
```

{% hint style="info" %}
**Primera arrancada después de una actualización mayor:**

Es normal que cardano-node elimine y reconstruya los snapshots del ledger en `db/ledger/` al iniciar por primera vez tras un update. No es un error — es parte de la migración del estado entre versiones. El nodo puede tardar más de lo habitual en sincronizarse durante este proceso.
{% endhint %}