Install on an Embedded cluster

Introduction

⚠️ Note that embedded installations are not recommended for production use and are better suited for trial or Proof of Concept (PoC) purposes. More information here.

GitGuardian can be installed with an embedded Kubernetes distribution packaged with it and supports deployment on bare metal, private, or public clouds.

Prerequisites

Required Infrastructure

1. Linux Virtual Machine: See system requirements for detailed hardware and OS specifications.

   Example VM instances that meet minimum requirements:

   • AWS: m7a.2xlarge (8 vCPUs, 32 GiB RAM)
   • GCP: n2-standard-8 (8 vCPUs, 32 GB RAM)
   • Azure: Standard_D8s_v5 (8 vCPUs, 32 GiB RAM)

Additional Requirements

2. License File: Download your GitGuardian license from the portal. See license management for instructions.

3. Network Access: Ensure your cluster meets the network requirements.

4. Domain Name: A Fully Qualified Domain Name (FQDN) for accessing the application. See system requirements.

Requirements

Review the complete system and network requirements before proceeding.

Installation

Embedded cluster

Contact the GitGuardian team at support@gitguardian.com to obtain your license ID. The license is embedded directly in the installer bundle, eliminating the need for a separate license file download.

To begin the installation, execute the following commands on your host system. The installation process takes approximately 5 minutes to complete. Consider using a terminal multiplexer like screen or tmux to prevent interruption due to connection loss. Replace your_license with the license ID provided by the GitGuardian team.

LICENSE_ID=your_license
curl -f https://replicated.app/embedded/gitguardian/stable -H "Authorization: $LICENSE_ID" -o gitguardian.tgz
tar -xvzf gitguardian.tgz
sudo ./gitguardian install --license license.yaml

info

Airgap

To use in airgap mode, use this instead:

LICENSE_ID=your_license
curl -f https://replicated.app/embedded/gitguardian/stable?airgap=true -H "Authorization: $LICENSE_ID" -o gitguardian.tgz
tar -xvzf gitguardian.tgz
sudo ./gitguardian install --license license.yaml --airgap-bundle gitguardian.airgap

HTTP Proxy

To use an HTTP proxy, use this instead:

LICENSE_ID=your_license
curl -f https://replicated.app/embedded/gitguardian/stable -H "Authorization: $LICENSE_ID" -o gitguardian.tgz
tar -xvzf gitguardian.tgz
sudo ./gitguardian install --license license.yaml \
  --http-proxy http://proxy.example.com:8080 \
  --https-proxy http://proxy.example.com:8080

For proxies with authentication, include credentials in the URL:

sudo ./gitguardian install --license license.yaml \
  --http-proxy http://username:password@proxy.example.com:8080 \
  --https-proxy http://username:password@proxy.example.com:8080

For detailed proxy configuration instructions, including troubleshooting authenticated proxies, see the HTTP Proxy documentation.

You will be prompted to enter the Admin console password. This password is used to manage the GitGuardian application and is different from the GitGuardian dashboard password that you will configure later.

If you are prompted to select from multiple network interfaces, choose the one connected to your private network.

This will install a single node-managed Kubernetes cluster with everything it needs to run the GitGuardian application.

Once the installation is completed, instructions will appear on how to access the Admin Console.

note

The deployment namespace for KOTS (and GitGuardian) cannot be changed at this time.

Application

With the embedded Kubernetes cluster now set up, let's move on to installing the GitGuardian application.

1. Access the Admin Console with the link provided and configure TLS. You have the option to upload your TLS certificates or use self-signed ones.

2. Enter the password provided at the end of the cluster installation.

3. You can see cluster status (with one node currently). Then click continue.

4. Configure the application by completing all the required fields:

   • Application Hostname: Enter the Fully Qualified Domain Name (FQDN) for the GitGuardian application.
   • Admin User Fields: These fields are used to create the first GitGuardian user. You'll need to change the password upon the first login.

Additional configuration options include:

• Scaling: Adjust the number of replicas for each application component. For more details, visit the Scaling page.
• Prometheus: Activate an exporter for Prometheus.
• TLS Certificate: This is for the GitGuardian Application. You can either use auto-generated self-signed certificates or upload your own. For self-signed or private CA certificates, disable SSL verification for the GitHub webhook. Learn more on the Configure TLS certificates page.
• Custom Certificate Authority: Provide a custom CA if necessary.
• HTTP(s) Proxy: Refer to the proxy section if needed.
• Databases/Datastores: Choose between using embedded PostgreSQL/Redis or an external one. For more information, see Configure your database.
• Load balancer considerations: To use the embedded cluster behind a load balancer, please read Configure your instance to work behind a load balancer.

5. Check if preflight checks pass.

Requirements

Preflight checks are critical for a successful installation. The following rules apply:

• ❌ Preflight Check Failures: If preflight checks fail, the installation must not continue until the targeted environment meets all requirements. Please reach out to our support team if needed.
• ⚠️ Preflight Check Warnings: If preflight checks return warnings, the installation can proceed, but it is recommended that you address these warnings to comply with our recommendations.

6. Launch

The first installation of the GitGuardian application requires a few minutes to create all database objects. Once the process is completed, you will be able to log in to the dashboard using the administrator user you defined.

Save the Data Encryption Key

caution

GitGuardian encrypts all sensitive information in the database using an encryption key (aka Django Secret Key). In case of disaster recovery, this key will be needed to restore your data.

You should save it and keep it in a secure location. Use the following command to display the key:

sudo ./gitguardian shell
kubectl get secrets gim-secrets -o jsonpath='{.data.DJANGO_SECRET_KEY}' | base64 -d

Troubleshooting

If you encounter issues during the installation process, you can generate a support bundle for the GitGuardian team to diagnose and resolve problems more efficiently. See the support bundle documentation for detailed instructions.

Next Steps

After successful installation:

• Access your GitGuardian instance using the hostname you configured
• Log in with the administrator credentials you set up (change the temporary password on first login)
• Configure email settings for notifications
• Set up SSO and SCIM integration (optional)
• Integrate your first repositories to begin secret detection