Skip to content

Install

Install

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

Tip

These instructions assume a Unix-like setup. If you're using Windows, your milage may vary.

Evaluation

1. Modify your hosts file with a metaport.dev entry.

2. Create a new directory and execute the following inside it:

curl -so metaport https://gitlab.com/dcentrica/metaport/metaport-server/-/raw/master/bin/quickstart.sh && chmod +x metaport && ./metaport

3. Point your browser at: https://metaport.dev/.

Troubleshooting: There are some known issues and workarounds. Refer to the "Evaluation" section of the troubleshooting guide. Guides: Consult the quickstart guide on provisioning data and users, as well as the agent documentation for how to send data to Metaport.

Development

Clone the repo and run docker compose -f docker-compose-dev.yml 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

Use an official Docker 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: .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 configure Metaport with SMTP config as an environment variable. 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.

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":

  1. "Host" e.g. Ubuntu, Alpine or Windows
  2. "Runtime" e.g. Python, PHP or Java
  3. "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 Metaport'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.