Antora interfaces with git repositories using nodegit. During installation (specifically the default site generator), Antora downloads and installs nodegit automatically. But this step requires support from your system. If Antora fails to install or run, nodegit is the most probable culprit. This page helps you troubleshoot the problem.
If installation fails when it arrives at installing nodegit, the first thing to check is that you’ve satisfied all prerequisites. Specifically, you must have installed the base build tools for your system (Linux and macOS only).
If that doesn’t do the trick, or Antora fails at runtime, you may either need to patch your system or force nodegit to be recompiled.
The nodegit dependency may fail on certain Linux distributions when you attempt to install the default Antora site generator.
When the nodegit dependency fails, you’ll see the following error output to you terminal.
Error: libcurl-gnutls.so.4: cannot open shared object file: No such file or directory
This is an open issue in nodegit. See nodegit#1246.
If you see this error, you either need to create the missing symlink or force nodegit to be recompiled instead of using a precompiled binary. If you’re using Alpine Linux, you must force nodegit to recompile.
To create the missing symlink, run the following command:
$ sudo ln -s /usr/lib64/libcurl.so.4 /usr/lib64/libcurl-gnutls.so.4
If that fails, run:
$ sudo ln -s /usr/lib/libcurl.so.4 /usr/lib/libcurl-gnutls.so.4
Once you’ve made that symlink, run the
npm install command to install the site generator.
$ npm install -g @antora/site-generator-default
If you aren’t comfortable making a system-wide change, or you’re on Alpine Linux or RHEL, you can recompile nodegit on your machine instead.
Force nodegit to recompile by passing the
BUILD_ONLY=true environment variable to the
npm install command.
$ BUILD_ONLY=true npm install -g @antora/site-generator-default
Be aware that recompiling nodegit will make installation take considerably longer.