Heimdall Lite^© vs. Heimdall Server^©

The Heimdall^© application is distributed in two forms:

1. Heimdall Lite^©, which is the frontend webapp component, and is used for simple ad-hoc use cases where storing security data long-term is not required
2. Heimdall Server^©, which consists of
   1. The frontend application
   2. A database for backend storage of security data
   3. An NGINX webserver to handle incoming requests

If you want to quickly use Heimdall^© to examine test data, use Heimdall Lite^©. If you want to use Heimdall^© to track your security posture over time, and serve as the repository for your organization's security data, use Heimdall Server^©.

See below for installation instructions for both Lite and Server. There are multiple methods for installing Server; we recommend using the Docker Compose method for ease of use. A Helm chart is also available.

Heimdall Lite^©

Heimdall Lite^© is published to npmjs.org and is available here.

Running via npm/npx

You can globally install and run the Heimdall Lite^© node package using npm.

npm install -g @mitre/heimdall-lite
heimdall-lite

Alternatively, you can run using npx. If you are running this often, consider installing globally to make your subsequent npx commands faster.

npx @mitre/heimdall-lite

Running via Docker

You can run Heimdall Lite^© using Docker, using the following command:

docker run -d -p 8080:80 mitre/heimdall-lite:release-latest

You can then access Heimdall Lite^© at http://localhost:8080.

If you would prefer to run the bleeding edge version of Heimdall-Lite, replace mitre/heimdall-lite:release-latest with mitre/heimdall-lite:latest.

Heimdall Server^© - Docker

Heimdall Server^© consists of the same front end as Heimdall Lite^©, a database to store data, and an NGINX webserver to handle TLS communication. Using Docker and Docker Compose packages these things together to provide a simple deployment experience.

Heimdall^©'s frontend container image is distributed on DockerHub, and on Iron Bank.

Setup Docker Container (Clean Install)

1. Install Docker
2. Download and extract the most recent Heimdall^© release from our releases page. Alternatively, you can clone Heimdall^©'s GitHub source code repository and navigate to the heimdall2 folder.
3. Navigate to the base folder where docker-compose.yml is located.
4. By default Heimdall^© will generate self-signed certificates that will last for 7 days. Self-signed certificates are not appropriate for production deployments. For production use, place your organization's certificate files in ./nginx/certs/ with the names ssl_certificate.crt and ssl_certificate_key.key respectively. For development use, you can use the default generated certificates, which means you do not need to put any certificate files in the ./nginx/certs/ folder. 
   1. NGINX Configuration Note: You can configure NGINX settings by changing values in the nginx/conf/default.conf file.
5. Run the following commands in a terminal window from the Heimdall^© source directory. For more information on the .env file, visit Environment Variables Configuration. 
   ./setup-docker-env.sh # If you would like to further configure your Heimdall instance, edit the .env file generated after running the previous line docker-compose up
6. Navigate to https://127.0.0.1. You should see the application's login page. (Note that if you used the option to generate your own self-signed certs, you will get warnings about them from your browser.)

Updating Docker Container

Starting with version 2.5.0, Heimdall on Docker uses SSL by default. Place your certificate files in ./nginx/certs/ with the names ssl_certificate.crt and ssl_certificate_key.key respectively.

A new version of the docker container can be retrieved by running:

docker compose pull
docker compose up -d

This will fetch the latest version of the container, redeploy if a newer version exists, and then apply any database migrations if applicable. No data should be lost by this operation.

Stopping the Container

From the source directory you started from run:

docker compose down

Helm Chart

https://github.com/mitre/heimdall2-helm

Running via Cloud.gov

Cloud.gov is a FEDRAMP moderate Platform-as-a-Service (PaaS). This repository includes a sample manifest.yml.example file ready to be pushed and run the latest version of Heimdall2 as a container. Make a copy of the example file and update the key values as appropriate. $ cp manifest.yml.example manifest.yml

Setup a cloud.gov account - https://cloud.gov/docs/getting-started/accounts/

Install the cf-cli - https://cloud.gov/docs/getting-started/setup/

Run the following commands in a terminal window from the Heimdall source directory.

$ cd ~/Documents/Github/Heimdall2
$ cf login -a api.fr.cloud.gov  --sso 
# Follow the link to copy the Temporary Authentication Code when prompted

4. Setup a demo application space

$ cf target -o sandbox-rename create-space heimdall2-rename

5. Create a postgresql database

# Update manifest.yml file to rename application and database key name
$ cf marketplace
$ cf create-service aws-rds medium-psql heimdall2-rename
$ cf create-service-key heimdall2-db-rename heimdall2-db-test-key
$ cf push

You should be returned the URL for your new test instance to navigate to.

Note: This is only for demonstration purposes, in order to run a production level federal/FISMA system. You will need to contact the cloud.gov program and consult your organization's security team (for risk assessment and an Authority to Operate).