Skip to content

Installation

Jump to bottom
Mark E. Haase edited this page Nov 13, 2024 · 5 revisions

Web Application

  1. Install Docker tools:

  2. Download the latest docker-compose.yml from the GitHub repo, or run this command to download it from the command line:

    $ curl -LO https://github.com/center-for-threat-informed-defense/tram/raw/main/docker/docker-compose.yml

  3. Edit the settings in docker-compose.yml. See Environment Variables for more information.

  4. Use Docker Compose to start the TRAM containers.

    • Run this command from the same directory where you downloaded docker-compose.yml: 
      $ docker compose up
    • The first time you run this command, it will download about 1GB of Docker images. This requires a connection to the internet. If your environment does not have a connection to the internet, refer to Air Gap Installation.
    • Once the images are downloaded, TRAM will do a bit of initialization. The following output lines indicate that TRAM is ready to use: 
      tram_1   | [2022-03-30 16:18:44 +0000] [29] [INFO] Starting gunicorn 20.1.0
tram_1   | [2022-03-30 16:18:44 +0000] [29] [INFO] Listening at: http://0.0.0.0:8000 (29)
    • Note: the log shows the IP address 0.0.0.0, but TRAM requires connections to use one of the hostnames defined in the ALLOWED_HOSTS environment variable.

  5. Navigate to http://localhost:8000/ and login using the username djangoSuperuser and the password that you specified in docker-compose.yml. Screenshot 2023-08-27 at 7 26 18 PM

  6. To shut down TRAM, type Ctrl+C in the shell where docker compose up is running.

Environment Variables

The following variables can be customized in your docker-compose.yml.

Variable Required Description
ALLOWED_HOSTS Yes A list of hostnames that TRAM can be served from.
DJANGO_SUPERUSER_USERNAME Yes The username for the TRAM super user (the default account you sign in with).
DJANGO_SUPERUSER_PASSWORD Yes The password for the TRAM super user.
DJANGO_SUPERUSER_EMAIL Yes The email address for the TRAM super user. (Not used in pratice, doesn't need to be a real address.)
DATA_DIRECTORY No Any ML data and DB data is stored at the path indicated at this environment variable. Defaults to ./data.
SECRET_KEY No A cryptographic secret used by Django. This secret can be generated using this command: $ python3 -c "import secrets; print(secrets.token_urlsafe())" If not provided, then a random secret is created at startup.
DEBUG No Set to `true` or `yes` to enable Django debug mode, otherwise debug mode is disabled.

Air Gap Installation

If you are unable to pull images from Docker Hub (i.e. due to corporate firewall, airgap, etc.), it is possible to download the images and move them onto the Docker host manually:

  1. Pull the images onto a machine that is able to access Docker Hub:

    $ docker pull ghcr.io/center-for-threat-informed-defense/tram:latest
$ docker pull ghcr.io/center-for-threat-informed-defense/tram-nginx:latest

  2. Export the Docker images to compressed archive (.tgz) format:

    $ docker save ghcr.io/center-for-threat-informed-defense/tram:latest \
    | gzip > tram-latest.tgz
$ docker save ghcr.io/center-for-threat-informed-defense/tram-nginx:latest \
    | gzip > tram-nginx-latest.tgz

  3. Confirm that the images were exported correctly.

    ls -lah tram*.tgz
-rw-r--r--  1 johndoe  wheel   345M Feb 24 12:56 tram-latest.tgz
-rw-r--r--  1 johndoe  wheel   9.4M Feb 24 12:57 tram-nginx-latest.tgz

  4. Copy the images across the airgap.

    • This step will depend on your deployment environment, of course.

  5. Import the Docker images on the Docker host.

    $ docker load < tram-latest.tgz
$ docker load < tram-nginx-latest.tar.gz

  6. Confirm that the images were loaded on the Docker host.

    $ docker images | grep tram
ghcr.io/center-for-threat-informed-defense/tram-nginx   latest    8fa8fb7801b9   2 weeks ago    23.5MB
ghcr.io/center-for-threat-informed-defense/tram         latest    d19b35523098   2 weeks ago    938MB

  7. From this point, you can follow the main installation instructions above.

Troubleshooting

[97438] Failed to execute script docker-compose

If you see this stack trace:

Traceback (most recent call last):
  File "docker-compose", line 3, in <module>
  File "compose/cli/main.py", line 81, in main
  File "compose/cli/main.py", line 200, in perform_command
  File "compose/cli/command.py", line 60, in project_from_options
  File "compose/cli/command.py", line 152, in get_project
  File "compose/cli/docker_client.py", line 41, in get_client
  File "compose/cli/docker_client.py", line 170, in docker_client
  File "docker/api/client.py", line 197, in __init__
  File "docker/api/client.py", line 221, in _retrieve_server_version
docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', ConnectionRefusedError(61, 'Connection refused'))
[97438] Failed to execute script docker-compose

Then most likely reason is that Docker is not running and you need to start it.

Clone this wiki locally