Install

These installation guidelines apply to installing Metaport CE on self-managed hosting.

Docker

Evaluation / Quickstart

If you just want to quickly evaluate or run Metaport in a local environment, use the following minimal instructions:

Create a new directory somewhere e.g. metaport and copy this config file into it.
Copy this example .env file into the current directory and make any changes you need.
Create self-signed SSL certificate files for nginx using the following command:

openssl req \
  -subj "/C=GB/CN=metaport.dev" \
  -addext "subjectAltName = DNS:metaport.dev" \
  -x509 \
  -nodes \
  -days 365 \
  -newkey rsa:2048 \
  -keyout ./metaport.dev.key \
  -out ./metaport.dev.crt

Create a new docker-compose.yml file with the following contents:

services:
  www:
    image: nginx:1.25.3-alpine
    volumes:
      - ./metaport.conf:/etc/nginx/conf.d/metaport.conf
      - ./metaport.dev.crt:/etc/nginx/metaport.dev.crt
      - ./metaport.dev.key:/etc/nginx/metaport.dev.key
      - mp-volume:/var/www/html/metaport
    ports:
      - "443:443"

  app:
    image: dcentrica/metaport-server:1.0.0-beta3-rc1
    volumes:
      - ./metaport.key:/etc/metaport.key
      - mp-volume:/var/www/html/metaport
    ports:
      - "9000:9000"
    env_file:
      - ./.env

  db:
    image: mariadb:10.11.10
    volumes:
      - .dev/data:/var/lib/mysql
    environment:
      MARIADB_ROOT_PASSWORD: "${DB_ROOT_PASSWORD}"
      MARIADB_USER: "${SS_DATABASE_USERNAME}"
      MARIADB_PASSWORD: "${SS_DATABASE_PASSWORD}"
      MARIADB_DATABASE: "${SS_DATABASE_NAME}"

volumes:
  mp-volume:

Create an entry for metaport.dev in your hosts file, then bring up all the services with docker compose up -d.
Finally, generate a master encryption key with docker compose exec app /bin/bash -c './bin/genkey.sh /etc/metaport.key' and point a browser athttps://metaport.dev/`.

Development Environments

The easiest way to install and run Metaport is to clone the repo and run docker compose up -d --build in the project root. See the dev docs for more. In this case, docker compose uses the Dockerfile found in .dev/services/app/Dockerfile.

Production Environments

No-one should be using docker compose in production! Use an officially available image from Docker Hub.

If any of your team's applications will be reporting-in to the server using the EMAIL transport method, then payloads are sent as encrypted attachments, the key for which is generated automatically by Metaport and is available from your friendly Metaport administrator.

Ideally, you shouldn't be using an email transport at all, and should always first consider using HTTP, but we understand there are many ways to skin the proverbial cat.

Tip

Private key storage: The Metaport server provides a basic set of defaults for private key storage by saving the key to a user-only readable directory located off the web root (see .env.example). However, the lengths you want to go to secure that key are dependent on how sensitive your business considers the data to be. An alternative to saving the key, is to consider a vault system hosted by your cloud provider of choice, or even the use of an HSM mounted as a volume in the same location.

Scheduled Tasks

In order for scheduled notifications to be sent, a single cron entry should be setup to run every minute which calls a controller to perform the actual notification.

See: .docker/dev/services/cron

Kubernetes

Helm chart to come.

Mail

Email is one way notifications are sent from Metaport to a team's recipients with the result of their policies when run. You'll need to setup a mail sending service such as Mailgun for example. Ensure you properly copy & paste the DSN you're provided into your Metaport server's .env file or in CI or Docker image build processes, as the value of the MP_MAIL_DSN environment variable. If you're running Metaport in a containerised environment, you'll need to rebuild the image each time you change anything in .env or use Docker's build args instead.

You'll also need a mailbox with a known email address which Metaport will connect-to for downloading your app's latest data. You'll need to provide the mailbox's address and connection credentials into the Metaport UI within your Team's "settings" area.

Be sure to set a valid email address for use in from and reply-to headers, by using the MP_NOTIFICATION_EMAIL_FROM environment variable. If it isn't set, mail may not be delivered properly, or without errors.

Environment Variables

Review the full range of available environment variables in the .env.example file, and see the agent docs also.

System Components

"Components" in Metaport are the system's own representation of what the system's default EOL (End of Life) backend calls "Products": The things which make-up an application such as operating-systems, language runtimes and frameworks. For reporting purposes, Metaport maps each of these to one of three "types":

"Host" e.g. Ubuntu, Alpine or Windows
"Runtime" e.g. Python, PHP or Java
"Framework" e.g. Django, Laravel or Drupal

The currently supported range of system components can be found in the default EndOfLifeDotDate class, which at time of writing (October '24) is limited to the following, because they are a minimum subset of those available from the default backend: (See this issue which describes the best way forward with this):

Ubuntu: (Host)
Debian: (Host)
Alpine: (Host)
Windows: (Host)
Php: (Runtime)
Python: (Runtime)
Java: (Runtime)
Oracle-jdk: (Runtime)
Perl: (Runtime)
Dotnet: (Runtime)
Nodejs: (Runtime)
Spring: (Framework)
Drupal: (Framework)
Symfony: (Framework)
Laravel: (Framework)
Silverstripe: (Framework)
Django: (Framework)
React: (Framework)
Nextjs: (Framework)
Jquery: (Framework)
Angularjs: (Framework)
Angular: (Framework)
Nuxt: (Framework)
Moodle: (Framework)
Umbraco: (Framework)

Warning

These cannot be modified, but there are plans to open this up. What system admin users can do is configure a subset of these components and their versions in the system's "Settings" area.

A crontab should be setup so that the system can automatically fetch updates from the currently configured EOL backend.

See: "Scheduled Tasks" above.

Comissioning and Superuser

Once Metaport is running on a server somewhere for the first time, a logical structure of Organisation, Team, Application and User records needs to be setup by a superuser. How to decide who is awarded this role is outside the scope of this documentation, but Metaport does support the existence of multiple superusers.

Organisation

Login as a superuser and proceed to the "Organisations" section. Select the "Add Organisation" button and fill in all the fields as required.

Create as many organisations as your company or business requires.

Team

Login as a superuser and proceed to the "My Teams" section. Select the "Add Team" button and fill in all the fields as required.

Create as many teams as your company or business requires.

Application

While most of the data for each application you wish to track in Metaport, is reported by the applications themselves, an app needs to be setup with a subset of information in Metaport first.

Login as a superuser and proceed to the "My Teams" section. Select the appropriate team and navigate to the "Applications" tab. Select the "Add Application" button. The basic fields needed are: "Application Name", "Domain" and "Transport Mode".

Users

Login as a superuser and proceed to the "Accounts" section. Select the "Add Member" button and fill in the fields as required. When reviewing the appropriate selection to make from the "Groups" menu, refer to the table given in the security section for guidance on which groups to apply to the user account(s) you wish to create. In summary there are "Administators", "Owners", "Managers" and "Users".

Developer Bundle

When setting up an application, to make the job of developers as easy as possible, Metaport users can generate a "Bundle" of credentials from the "Application" Metaport UI, to pass onto the development team for that app. Using these credentials, CI pipelines and automated processes can be setup with ease. Look at the blue buttons and UI controls along the bottom of the "Application" Metaport UI.