Running an Amaru Node on Mainnet: Advanced Installation

This page covers installing the binary, running it as a systemd service under its own dedicated system user, and the ongoing operation and maintenance of that deployment. It assumes the host has already been hardened, see System Hardening first if you haven’t done that yet.

1. Installing Amaru as a systemd service

version reference

Amaru releases follow a calendar-based scheme (e.g. 10.11.20260827). Always check the releases page for the latest version before installing. Amaru is still in an exploratory phase, so expect frequent releases and occasional breaking changes.

For production use, run amaru under systemd so it restarts automatically on failure or reboot. The Debian / RPM package is the recommended path as it installs a dedicated amaru system user and the amaru.service unit for you.

Debian / RPM package — recommended for systemd deployments

Debian/Ubuntu:

VERSION=10.11.20260827 ARCH=x86_64  # check releases page for latest; also available for aarch64
curl -fsSL -o amaru-$VERSION-linux-$ARCH.deb "https://github.com/pragma-org/amaru/releases/download/v$VERSION/amaru-$VERSION-linux-$ARCH.deb"
sudo apt install ./amaru-$VERSION-linux-$ARCH.deb

Fedora/RHEL/CentOS:

VERSION=10.11.20260827 ARCH=x86_64  # check releases page for latest; also available for aarch64
curl -fsSL -o amaru-$VERSION-linux-$ARCH.rpm "https://github.com/pragma-org/amaru/releases/download/v$VERSION/amaru-$VERSION-linux-$ARCH.rpm"
sudo dnf install ./amaru-$VERSION-linux-$ARCH.rpm

Running Amaru as a systemd service

The Debian and RPM packages don’t just ship the amaru binary, they also install a dedicated amaru system user, a systemd unit, and a default environment file.

TUI Limitation

The use of the TUI is currently only possible when running Amaru directly in a CLI. -> A way of using the TUI as a detached process is being explored by the team. Please refer to #Monitoring section to learn how to retrieve logs and metrics when Amaru is running as a service.

The systemd unit (Debian)

• amaru user’s home is under /var/lib/amaru with nologin
• amaru.service is installed at /usr/lib/systemd/system/amaru.service but not enabled or started.
• amaru-bootstrap.service is installed at /usr/lib/systemd/system/amaru-bootstrap.service but not enabled or started.
• amaru.env is installed as /etc/default/amaru

/etc/default/amaru

AMARU_NETWORK=mainnet
AMARU_DB_CHAIN=/var/lib/amaru/chain.mainnet.db
AMARU_DB_LEDGER=/var/lib/amaru/ledger.mainnet.db
AMARU_DB_CHAIN_AUTOMATIC_MIGRATION=true
AMARU_PID_EXPORT=/run/amaru/amaru.pid
AMARU_WITH_JSON_TRACES=true

2. Bootstrapping the node

Assuming you are using the default db location:

cd /var/lib/amaru

Note

Because the /var/lib/amaru folder is owned by the user amaru you need to run commands using sudo -u amaru. Also the Amaru user is set to nologin for security concerns.

Amaru bootstraps itself with Mithril-derived snapshots:

sudo -u amaru amaru node bootstrap --network mainnet

Alternatively, you can also run the one-shot bootstrap service:

sudo systemctl enable --now amaru-bootstrap.service
sudo systemctl start amaru-bootstrap

This downloads a window of pre-generated, Mithril-derived ledger snapshots from Amaru’s snapshot bucket and imports them directly into the chain and ledger databases. amaru node run then only needs to sync the blocks produced since then.

/var/lib/amaru/
├── chain.mainnet.db/
├── ledger.mainnet.db/
└── snapshots/

Note

Bootstrap fails if the target directories (chain or ledger) already contain data, remove them first before re-bootstrapping: amaru node rm --wipe-all-dbs --network mainnet or rm -rf chain.mainnet.db/ ledger.mainnet.db/

If you want to start from a specific epoch instead of the latest available snapshot:

sudo -u amaru amaru node bootstrap --network mainnet --epoch 602

Note

If the desired epoch snapshot is not available, the cli will respond by listing the usable epoch snapshot for the network.

3. Configuring the node

You can override the defaults in /etc/default/amaru or add new one as needed. Every amaru node run flag has a matching AMARU_* environment variable, for example:

/etc/default/amaru

[...]
AMARU_PEER=my-own-peer.example.com:3001
AMARU_PEERS_LISTEN_ON=0.0.0.0:3001
AMARU_PEERS_MAX_UPSTREAM=10
AMARU_WITH_OPEN_TELEMETRY=true
OTEL_METRIC_EXPORT_INTERVAL=1000

Note

AMARU_WITH_OPEN_TELEMETRY allow Amaru to send traces to the OTLP collector OTEL_METRIC_EXPORT_INTERVAL is the time between two OTLP metrics export (default is 60s, here set to 1s)

You can get the full config list with the TUI under the config menu (press ESC on the Config page to enter copy mode and select values with the terminal):

Here is the same config list in txt

┌─ [ AMARU ] [ CARDANO ] [ CONFIG ] ─────────────────────────────────────────────────────────────────────────────────  COPY MODE  ────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│┌─ Essential ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐┌─ Protocol Parameters · Network ─────────────────────────────────────────────────────────────┐│
││Option    Env           Value                                                                                                                   ││Parameter             Value                                                                  ││
││--network AMARU_NETWORK mainnet                                                                                                                 ││max block body size   90112                                                                  ││
│└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘│max transaction size  16384                                                                  ││
│┌─ Storage options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐│max block header size 1100                                                                   ││
││Option                          Env                                 Value                                                                       ││max tx ex units       {mem=16500000, cpu=10000000000}                                        ││
││--db-chain                      AMARU_DB_CHAIN                      ./chain.mainnet.db                                                          ││max block ex units    {mem=72000000, cpu=20000000000}                                        ││
││--db-chain-automatic-migration  AMARU_DB_CHAIN_AUTOMATIC_MIGRATION  false                                                                       ││max value size        5000                                                                   ││
││--db-ledger                     AMARU_DB_LEDGER                     ./ledger.mainnet.db                                                         ││max collateral inputs 3                                                                      ││
││--db-ledger-max-extra-snapshots AMARU_DB_LEDGER_MAX_EXTRA_SNAPSHOTS 0                                                                           │└─────────────────────────────────────────────────────────────────────────────────────────────┘│
│└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘┌─ Protocol Parameters · Economic ────────────────────────────────────────────────────────────┐│
│┌─ Peers options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐│Parameter                     Value                                                          ││
││Option                   Env                          Value                                                                                     ││min fee a                     44                                                             ││
││--peer                   AMARU_PEER                                                                                                             ││min fee b                     155381                                                         ││
││--peers-listen-on        AMARU_PEERS_LISTEN_ON        0.0.0.0:3000                                                                              ││stake credential deposit      2000000                                                        ││
││--peers-max-downstream   AMARU_PEERS_MAX_DOWNSTREAM   10                                                                                        ││stake pool deposit            500000000                                                      ││
││--peers-max-upstream     AMARU_PEERS_MAX_UPSTREAM     3                                                                                         ││monetary expansion            3/1000                                                         ││
││--peers-removal-cooldown AMARU_PEERS_REMOVAL_COOLDOWN 10min                                                                                     ││treasury expansion            1/5                                                            ││
││--peers-snapshot         AMARU_PEERS_SNAPSHOT         embedded (16f0489218fe4c4605b24f28a9d5489f1ab808f2)                                       ││min pool cost                 170000000                                                      ││
││--peers-mix              AMARU_PEERS_MIX              static!2@15m, inbound~6, shared~6, snapshot~3@1h, ledger~3@24h                            ││lovelace per UTxO byte        4310                                                           ││
│└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘│prices                        {mem=577/10000, cpu=721/10000000}                              ││
│┌─ TUI options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐│collateral percentage         150                                                            ││
││Option              Env                     Value                                                                                               ││ref script fee per byte       15/1                                                           ││
││--tui-off           AMARU_TUI_OFF           false                                                                                               ││max ref script size per tx    204800                                                         ││
││--tui-log-retention AMARU_TUI_LOG_RETENTION 104857600 B                                                                                         ││max ref script size per block 1048576                                                        ││
│└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘│ref script stride             25600                                                          ││
│┌─ Advanced options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐│ref script multiplier         6/5                                                            ││
││Option                 Env                        Value                                                                                         │└─────────────────────────────────────────────────────────────────────────────────────────────┘│
││--submit-api-listen-on AMARU_SUBMIT_API_LISTEN_ON disabled                                                                                      │┌─ Protocol Parameters · Governance ──────────────────────────────────────────────────────────┐│
││--pid-export           AMARU_PID_EXPORT           disabled                                                                                      ││Parameter                 Value                                                              ││
││--trace-buffer         AMARU_TRACE_BUFFER         disabled                                                                                      ││pool max retirement epoch 18                                                                 ││
││--trace-buffer-dump    AMARU_TRACE_BUFFER_DUMP    disabled                                                                                      ││optimal stake pools       500                                                                ││
│└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘│pledge influence          3/10                                                               ││
│┌─ Network global parameters overrides (for custom devnets) ─────────────────────────────────────────────────────────────────────────────────────┐│min committee size        7                                                                  ││
││Option        Env               Value                                                                                                           ││max committee term length 146                                                                ││
││--era-history AMARU_ERA_HISTORY mainnet                                                                                                         ││gov action lifetime       6                                                                  ││
│└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘│gov action deposit        100000000000                                                       ││
│┌─ Network global parameters ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐│drep deposit              500000000                                                          ││
││Option                      Env                                    Value                                                                        ││drep expiry               20                                                                 ││
││--consensus-security-param  AMARU_GLOBAL_CONSENSUS_SECURITY_PARAM  2160                                                                         │└─────────────────────────────────────────────────────────────────────────────────────────────┘│
││--epoch-length-scale-factor AMARU_GLOBAL_EPOCH_LENGTH_SCALE_FACTOR 10                                                                           │                                                                                               │
││--active-slot-coeff-inverse AMARU_GLOBAL_ACTIVE_SLOT_COEFF_INVERSE 20                                                                           │                                                                                               │
││--max-lovelace-supply       AMARU_GLOBAL_MAX_LOVELACE_SUPPLY       45000000000000000                                                            │                                                                                               │
││--slots-per-kes-period      AMARU_GLOBAL_SLOTS_PER_KES_PERIOD      129600                                                                       │                                                                                               │
││--max-kes-evolution         AMARU_GLOBAL_MAX_KES_EVOLUTION         62                                                                           │                                                                                               │
││--system-start              AMARU_GLOBAL_SYSTEM_START              1506203091000                                                                │                                                                                               │
│└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘                                                                                               │
│                                                                                                                                                                                                                                                 │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── <esc> NORMAL MODE ─┘

4. Running the node as a systemd service

The amaru.service is not enabled by default, enable it so it can restart on failure or reboot :

sudo systemctl enable amaru.service
sudo systemctl start amaru

You can then read Amaru logs with journalctl -fu amaru

5. Logs, Metrics and Monitoring

Amaru uses OpenTelemetry to export its Metrics, Logs and Traces.

When running Amaru in CLI use --with-open-telemetry:

amaru --with-open-telemetry node run --network preprod

When running Amaru as a systemd service set the env variable AMARU_WITH_OPEN_TELEMETRY:

/etc/default/amaru

AMARU_WITH_OPEN_TELEMETRY=true
OTEL_METRIC_EXPORT_INTERVAL=1000

Note

OTEL_METRIC_EXPORT_INTERVAL is the time between two OTLP metrics export (default is 60s, here set to 1s)

A complete Monitoring stack is available in the Amaru repository

After cloning the repo, run :

docker compose -f monitoring/docker-compose.yml up -d

The stack includes:

• OpenTelemetry Collector on localhost:4317 (OTLP/gRPC)
• Tempo for spans and span-derived metrics
• Prometheus for application and span-derived metrics
• Loki for OpenTelemetry logs and their structured metadata
• Grafana with all three data sources provisioned and trace-to-log correlation enabled

See all details in the Amaru Monitoring Readme

Note

If you already have a running Monitoring Stack, feel free to setup the otlp collector to your needs.

For example if you are only interested in Prometheus metrics to scrape :

docker-compose.yml

services:
  otlp-collector:
    image: otel/opentelemetry-collector-contrib:0.133.0
    restart: unless-stopped
    volumes:
      - ./otlp-collector.yml:/etc/otlp-collector.yml
    command: ["--config", "/etc/otlp-collector.yml"]
    ports:
      - "127.0.0.1:4317:4317"
      - "127.0.0.1:8889:8889"

otlp-collector.yml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: "0.0.0.0:4317"

processors:
  batch:
  resource/drop_prometheus_labels:
    attributes:
      - key: service.instance.id
        action: delete
  transform/drop_scope:
    metric_statements:
      - context: scope
        statements:
          - set(name, "")
          - set(version, "")

exporters:
  prometheus:
    endpoint: "0.0.0.0:8889"
    add_metric_suffixes: false
    metric_expiration: 60s
  nop:

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [resource/drop_prometheus_labels, transform/drop_scope, batch]
      exporters: [prometheus]
    traces:
      receivers: [otlp]
      exporters: [nop]
    logs:
      receivers: [otlp]
      exporters: [nop]

Using the nop exporter allows otlp to receive logs and traces from Amaru and discard them after.

You can then scrape the metrics at 127.0.0.1:8889/metrics

$ watch -n1 "curl -s 127.0.0.1:8889/metrics | grep -E 'cardano_node_metrics_epoch_int{|cardano_node_metrics_blockNum_int{|cardano_node_metrics_slotInEpoch_int{' | sed 's/{/ /g' | cut -d' ' -f1,3 | column -t -s' ' "

cardano_node_metrics_blockNum_int     1.3850928e+07
cardano_node_metrics_epoch_int        651
cardano_node_metrics_slotInEpoch_int  153412

6. Administration & maintenance

Submitting a transaction

Start the node with --submit-api-listen-on or AMARU_SUBMIT_API_LISTEN_ON, then POST the CBOR-encoded transaction:

curl -X POST \
  --header "Content-Type: application/cbor" \
  --data-binary @tx.cbor \
  http://localhost:8090/api/submit/tx

See Amaru Submit API documentation for additional details.

Upgrading Amaru

Amaru is still in an exploratory phase, so check the release notes before every upgrade.

• Release Binaries — replace the amaru binary on your $PATH and restart the process.
• Debian/RPM package — download and install the new package the same way as the initial install. run systemctl restart amaru.service afterwards.
• Docker — pull the new tag and recreate the container.
• Homebrew / Nix — brew upgrade amaru / re-run the nix profile install command with the new ref.

Note

The packaged systemd service sets AMARU_DB_CHAIN_AUTOMATIC_MIGRATION=true (/etc/default/amaru) so Amaru migrates the on-disk chain database schema forward automatically on upgrade rather than requiring a manual wipe and re-bootstrap. Best practice is to back up --db-chain/--db-ledger before upgrading across a version that mentions ledger or chain database format changes in its release notes, so you can roll back if needed.

Caution

When using the CLI directly, AMARU_DB_CHAIN_AUTOMATIC_MIGRATION defaults to false, so if a db migration is needed, Amaru won’t start and will ask to use --db-chain-automatic-migration in order to perform the upgrade.