Installing FOSSA On-Premises

Overview

This guide walks through installing FOSSA Enterprise into an existing Kubernetes cluster using the official Helm chart. By the end, you'll have a running, verified FOSSA instance that your users can sign in to and import their first project.

The installation has four stages, and they build on each other in order:

1. Set up Helm and add the FOSSA chart repository.
2. Configure your Helm values for your environment.
3. Prepare your external services (database and object storage).
4. Install and verify the release.

Prerequisites

Before you start, confirm your cluster, database, object storage, and network meet the installation requirements. You'll also need the FOSSA image credentials from your account manager.

Set up Helm

FOSSA is distributed as an on-premises application using Helm, a tool for distributing applications that run on Kubernetes.

1. 1

   Install helm

   Follow Installing Helm, choosing a version compatible with your cluster (see Helm's Version Support Policy).

   Verify the install by running helm list. You should see a list of releases in your cluster's default namespace. It may be empty if you haven't installed any charts yet.

   Warning

   If helm can't connect to your cluster, first confirm kubectl cluster-info works. If that fails too, contact your Kubernetes cluster administrator; FOSSA does not install or manage Kubernetes clusters.

2. 2

   Add the FOSSA chart repository

   FOSSA's official charts are hosted at https://charts.fossa.com. Add the repository and pull the latest chart metadata:

   ShellCopy

   # Add the FOSSA Helm chart repository.$ helm repo add fossa https://charts.fossa.com"fossa" has been added to your repositories # Load the latest information from all chart repositories.$ helm repo update

3. 3

   Test your image credentials

   Confirm the FOSSA image credentials from your account manager work by logging in and pulling an image:

   ShellCopy

   # Follow the prompts for username and password$ docker login quay.io $ docker pull quay.io/fossa/fossa

   If the pull succeeds, your credentials are working.

Inspecting the chart (optional)

As a best practice, inspect a chart before installing it. FOSSA's fossa-core chart bundles a docs folder with this installation guide, a CHANGELOG.md (with breaking changes highlighted), and a commented values.yaml documenting every possible value.

# Download and unpack the chart into a temporary folder$ helm pull --untardir /tmp/fossa-helm --untar fossa/fossa-core

The fossa-core chart pulls in several sub-charts:

Don't use the chart's values.yaml directly. Instead, start from one of the provided initial value files, described next.

Configure your Helm values

With Helm set up, create a values file that describes your installation. Start from one of the three starter values files:

• simplified.values.yaml (recommended): for managed external hosting. Uses YAML anchors for simpler configuration.
• simplified.self-hosted.values.yaml: for self-hosting FOSSA's dependencies in-cluster.
• advanced.values.yaml: exposes the full chart configuration directly, without anchors.

All three configure the same underlying schema. As you edit, you can preview the fully rendered output (with anchors resolved) using:

# helm template RELEASE_NAME CHART_NAME [FLAGS]$ helm template fossa fossa/fossa-core --values YOUR_VALUES_FILE.yaml

Basic configuration

Start with the basics:

• Image credentials: set global.imageCredentials.username and global.imageCredentials.password to the values from your account manager.
• Encryption secret: set encryptionSecret to a random 64-character hexadecimal string. It encrypts application-level secrets such as VCS API keys. You generally shouldn't change it later; if you do, you may need to reconfigure all application-level credentials.
• Hostname and port: set hostname (a string) and port (an integer). The hostname must be reachable by your end users; you'll add a DNS entry for it later.

Configuring external services

Next, point FOSSA at its database, object storage, and email server. The field names below are for the simplified charts; for the advanced chart, reference the comments on each field.

Database connection

For a database using managed external hosting, set:

• postgres.host
• postgres.username
• postgres.password
• postgres.database (the dbname FOSSA should use in your Postgres server)

For a self-hosted database, FOSSA creates an in-cluster Postgres instance for you; set only the user to create:

• postgresAuth.username
• postgresAuth.password

S3-compatible object storage

For object storage using managed external hosting, set:

• storageCoreBucket
• storageHubbleBucket
• storageEndpoint
• storageRegion
• storageAuth.accessKey
• storageAuth.secretKey

For self-hosted object storage, FOSSA creates MinIO instances for you. The web application's object storage must be reachable by your end users (FOSSA uses CORS to upload and download files directly), so set storageHostname to a user-accessible hostname and add a DNS entry for it later. With managed external hosting you don't need storageHostname; the S3 endpoint is used instead.

Email server

All FOSSA installations use an external email server. Configure:

• email.from
• email.host
• email.port
• email.auth.user
• email.auth.pass

Make sure FOSSA can reach the SMTP server you configure.

Terminating SSL

If you host FOSSA behind HTTPS, you can configure its Kubernetes Ingress to terminate SSL:

• If your ingress controller automates HTTPS certificates via annotations, use ingressAnnotations to set them on the web application's Ingress.
• To manage TLS certificates manually, use ingressTLS to set the tls field of the web application's Ingress. You'll need to construct the corresponding Secret containing the certificate yourself.

Trusting self-signed certificates

If your network uses self-signed certificates, configure FOSSA to trust them with the trustedCertificates field. Its value is a map where each key is the certificate's hash with .0 appended, and the value is the certificate's contents. Generate the hash with openssl x509 -noout -hash -in certificate.pem:

trustedCertificates:  5a7a72df.0: |-    -----BEGIN CERTIFICATE-----    MIIFATCCAumgAwIBAgIRAKc9ZKBASymy5TLOEp57N98wDQYJKoZIhvcNAQELBQAw    ...    8iyIYUyQAbsvx8oD2M8kRvrIRSrRJSl6L957b4AFiLIQ/GgV2curs0jje7Edx34c    idWw1VrejtwclobqNMVtG3EiPUIpJGpbMcJgbiLSmKkrvQtGng==    -----END CERTIFICATE-----

Prepare your external services

If you're using managed external hosting, some setup happens on the service host itself, outside FOSSA and Kubernetes. Skip the section for any service you're self-hosting.

Database

1. 1

   Create the database

   A Postgres server can host multiple databases. FOSSA connects to the one named in your chart configuration, make sure it exists. For example, if your dbname is fossa:

   SQLCopy

   CREATE DATABASE fossa;

2. 2

   Grant schema permissions

   FOSSA creates two schemas within the database, fossa and hubble. Ensure the database user you configured has permission to create schemas.

Object storage

1. 1

   Create your buckets

   You may need to create the S3 buckets manually before they can be used. Use the same bucket names you configured in your chart.

2. 2

   Grant IAM permissions

   For each bucket, FOSSA needs GetObject, ListBucket, and PutObject. Configure these on the access/secret key or the IAM role attached to FOSSA's pods. Substitute your bucket names for <CORE_BUCKET_NAME> and <HUBBLE_BUCKET_NAME>:

   JSONCopy

   {    "Version": "2012-10-17",    "Statement": [        {            "Sid": "FOSSA",            "Effect": "Allow",            "Action": [                "s3:PutObject",                "s3:GetObject",                "s3:ListBucket"            ],            "Resource": [                "arn:aws:s3:::<CORE_BUCKET_NAME>/*",                "arn:aws:s3:::<CORE_BUCKET_NAME>",                "arn:aws:s3:::<HUBBLE_BUCKET_NAME>/*",                "arn:aws:s3:::<HUBBLE_BUCKET_NAME>"            ]        }    ]}

3. 3

   Configure CORS

   The web application's bucket must allow CORS, since FOSSA serves bucket contents over CORS requests. Substitute your hostname for <FOSSA_HOSTNAME>:

   JSONCopy

   [    {        "AllowedHeaders": [            "*"        ],        "AllowedMethods": [            "PUT"        ],        "AllowedOrigins": [            "<FOSSA_HOSTNAME>"        ],        "ExposeHeaders": [            "Content-Type",            "X-Content-Type-Options"        ],        "MaxAgeSeconds": 3000    }]

Install and verify FOSSA

With your cluster configured, external services ready, and values prepared, you're ready to install.

1. 1

   Choose a release name

   Installing a chart creates a Helm release, identified by a name that's unique within the cluster. This lets you run multiple FOSSA instances side by side (for example, staging alongside production). Name a release by how it'll be used, e.g. fossa-production or fossa-staging.

2. 2

   Install the release

   ShellCopy

   # helm install RELEASE_NAME CHART_NAME [FLAGS]$ helm install fossa-production fossa/fossa-core --values YOUR_VALUES_FILE.yaml --timeout 60m

3. 3

   Configure DNS

   While the install runs, set up DNS for your chosen hostnames:

   • A DNS entry for the FOSSA web application.
   • If you self-host object storage, a DNS entry for it as well.

   Point each entry at your configured Kubernetes ingress. The exact setup depends on your ingress controller. Consult its documentation for serving external DNS.

4. 4

   Verify your installation

   Once DNS is configured and helm install has completed, navigate to your new FOSSA instance. You'll be prompted to create a user and an organization, after which you can import your first project for analysis using the FOSSA CLI.

Congratulations, you've completed a base installation of FOSSA. 🎉

What's next

• Customizing your deployment: integrations, SSO, SAML/LDAP, and notification banners.
• Updating Helm values: apply configuration changes after install.
• Architecture Overview: how FOSSA's services connect inside your network.