Oracle Linux Production Install

1. Set up system dependencies

sudo dnf -y update

curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -

sudo dnf install -y nodejs git
sudo npm install -g yarn

Check if they are installed:

node --version
npm --version
yarn --version
git --version

2. Install and start PostgreSQL

The repository RPM filename is noarch, but the URL directory is architecture-specific (for example x86_64 or aarch64). Detect your architecture and use it in the repo URL:

ARCH="$(uname -m)"
sudo dnf install -y "https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-${ARCH}/pgdg-redhat-repo-latest.noarch.rpm"
sudo dnf -qy module disable postgresql
sudo dnf install -y postgresql18 postgresql18-server
sudo /usr/pgsql-18/bin/postgresql-18-setup initdb
sudo systemctl enable postgresql-18
sudo systemctl start postgresql-18

If you want to use another version, follow the PostgreSQL Red Hat guide.

PostgreSQL version must be 13 or later:

psql --version

3. Clone Heimdall2

git clone https://github.com/mitre/heimdall2
cd heimdall2

4. Configure PostgreSQL authentication and database user

# Switch to the OS postgres user
sudo -u postgres -i
# Start the Postgres terminal
psql postgres

In psql terminal:

# Create the database user
CREATE USER <username> with encrypted password '<password>';
ALTER USER <username> CREATEDB;
\q

# Switch back to your original OS user
exit

5. Install project dependencies and generate backend env file

Note

If you do not want to place your credentials in the .env for security reasons, you can set them manually as environment variables before running the setup:

export DATABASE_USERNAME=<username>
export DATABASE_PASSWORD=<password>
export ADMIN_PASSWORD=<password>

(Make sure to set the DATABASE_USERNAME and DATABASE_PASSWORD fields with the values you set for PostgresDB in the previous step.)

Make sure that these commands are executed in the root directory of the repository to generate a new .env file for other environment variables:

yarn install --frozen-lockfile
./setup-dev-env.sh

At a minimum, manually update apps/backend/.env to set NODE_ENV=production

NODE_ENV=production

Additional configuration values can be set, see Environment Variables Configuration.

Note

The .env file in the root repository is for the Docker deployment of the Heimdall application. Running a local build will use the .env file in the apps/backend directory for the database configurations.

6. Create, migrate, and seed the database

yarn backend sequelize-cli db:create
yarn backend sequelize-cli db:migrate
yarn backend sequelize-cli db:seed:all

7. Build and start Heimdall in production

yarn build
yarn start

Note

This application does not terminate TLS/HTTPS connections itself. It listens for plain HTTP traffic and must be deployed behind a TLS-terminating reverse proxy (for example, NGINX or a cloud load balancer) that handles certificates and forwards requests to the application over HTTP.

8. Troubleshooting

8.1 Verify Password Format (Optional)

If PostgreSQL database creation fails, or login is unsuccessful, follow this sequence.

1. Check how PostgreSQL stored the role password:

   sudo -u postgres psql postgres -c "SELECT rolname, rolcanlogin, rolpassword FROM pg_authid WHERE rolname='<username>';"

2. If rolpassword does not start with SCRAM-SHA-256, reconfigure password encryption and reset the user password:

   sudo -u postgres psql postgres -c "ALTER SYSTEM SET password_encryption = 'scram-sha-256';"
   sudo -u postgres psql postgres -c "SELECT pg_reload_conf();"
   sudo -u postgres psql postgres -c "ALTER USER <username> WITH ENCRYPTED PASSWORD '<password>';"

3. Verify local host authentication is using SCRAM in pg_hba.conf. Run this from your original OS user shell:

   sudo vi "$(sudo -u postgres psql -tAc "show hba_file;")"

   That command opens the active pg_hba.conf path returned by PostgreSQL. Scroll to the bottom and make sure the loopback host rules are exactly:

   # IPv4 local connections
   host    all             all             127.0.0.1/32            scram-sha-256
   
   # IPv6 local connections
   host    all             all             ::1/128                 scram-sha-256
   

4. Reload PostgreSQL:

   sudo systemctl reload postgresql-18

8.2 PostgreSQL on a Separate Server

If PostgreSQL is hosted on a different server than the Heimdall2 application server, update both pg_hba.conf and postgresql.conf.

In pg_hba.conf, allow the Heimdall2 application server IP:

host    all    all    <Application_Server_IP>/32    scram-sha-256

In postgresql.conf, set listen_addresses so PostgreSQL listens on the database server interfaces:

listen_addresses = '0.0.0.0'

Note

pg_hba.conf controls which remote clients are allowed to connect, and listen_addresses controls which addresses PostgreSQL binds to on the database server itself. See the PostgreSQL documentation for listen_addresses. Do not use CIDR notation or the application server IP for listen_addresses. This setting must use *, 0.0.0.0, or an IP address assigned to the PostgreSQL server itself.

8.3 Offline Dependency and Build Workaround

If package installation or Yarn commands behave unexpectedly in an offline environment, one option is to prepare the dependencies outside the restricted network and then transfer them in.

1. Build Heimdall2 on a connected system.

   On a system that has internet access and can build Heimdall2 successfully, install dependencies and build the application:

   cd heimdall2
   yarn install --frozen-lockfile
   yarn build

   After the build completes, create a tarball of the entire Heimdall2 repository so it includes the checked-out source, installed dependencies, and built artifacts:

   cd ..
   tar -czf heimdall2.tar.gz heimdall2

2. Create an npm cache tarball for npx fallback.

   If the offline Yarn setup does not work correctly on its own, transferring the npm cache can allow Yarn to still be invoked through npx.

   First, determine the current npm cache path:

   npm config get cache

   If the cache path is the default ~/.npm, create the tarball like this:

   tar -czf ~/.npm_cache.tar.gz .npm

3. Extract the npm cache in the offline environment.

   By default, extract the npm cache into ~/.npm:

   tar -xzf npm_cache.tar.gz -C ~

   If that location is mounted with noexec, check by reviewing /etc/fstab:

   cat /etc/fstab

   If needed, configure npm to use a different cache directory:

   npm config set cache '<path>'

   The npm cache is transferred as a fallback in case the offline Yarn setup does not work correctly on its own. In that case, having the npm cache available allows Yarn to be invoked through npx, which is why Yarn commands in this workflow should be prefixed with npx rather than relying on a separate global Yarn installation.

   For example:

   npx yarn --version

4. Extract the Heimdall2 repository archive.

   Extract heimdall2.tar.gz into the location where you want the Heimdall2 repository to live. For example, if you want it under /repos:

   tar -xzf heimdall2.tar.gz -C /repos

   Because the archive contains the full repository after installation and build, it should already include the required node_modules content and build output. In most cases, after extracting it, all that remains is to enter the Heimdall2 repository and start the application:

   cd /repos/heimdall2
   npx yarn start

5. Build individual packages if the full build stalls.

   If npx yarn build still fails or appears to stall, build each package individually from the following directories:

   • apps/frontend
   • apps/backend
   • libs/hdf-converters
   • libs/inspecjs

   You can run the following commands from the Heimdall2 root directory:

   cd apps/frontend
   npx yarn build
   
   cd ../backend
   npx yarn build
   
   cd ../../libs/hdf-converters
   npx yarn build
   
   cd ../inspecjs
   npx yarn build

   After building each package individually, return to the Heimdall2 root directory and start the application:

   cd ../..
   npx yarn start