Installation
Prerequisites#
Hardware requirements#
- A GNU/Linux host, could be a Virtual Machine or a bare metal server
- CPU: 4 cores
- Memory: 8 GB
- Disk: at least 50 GB free disk space dedicated for application needs (SSD performance) (minimum recommended)
- If you want to scan large repositories, consider to increase available disk space
- A dedicated Linux account with sudo privileges (ex: app)
Software requirements#
- The Full Qualified Domain Name (FQDN) that you want to use for the application (ex: gitguardian.mycorp.local), could be an IP too
- A TLS certificate for HTTPS or follow the directive to create a self signed one (read for drawback below)
The following binaries/packages are needed:
| Binary/Packages | Version |
|---|---|
| docker | 19.03.5 |
| docker-compose | 1.27.2 |
| bash | >= 5.0 |
| gnupg | >= 2.2 |
| cUrl | * |
| crontab | * |
We provide an option during the installation to install these binaries (need external access to work). Supported GNU/Linux distributions:
| Distribution | Version | Name |
|---|---|---|
| Debian | 10 64Bits | Buster |
| Debian | 9 64Bits | Stretch |
| Ubuntu | 20.04 LTS 64Bits | The Focal Fossa |
| Ubuntu | 18.04 LTS 64Bits | Bionic Beaver |
| Ubuntu | 16.04 LTS 64Bits | Xenial Xerus |
| CentOS | 8 64Bits | |
| CentOS | 7 64Bits | |
| Amazon Linux | v2 64Bits |
Note: we highly recommend that you install the latest patch available for your distribution before starting the installation
If you want to use an other distribution, install these binaries by your own before launching the installation.
Network requirements#
For online installation:
- Outgoing access on TCP 443 (to download application tarball: https://get.gitguardian.com)
- Access to your distribution repositories (for dependencies installation)
- Access to docker repository (for docker installation: https://download.docker.com) (TCP 443)
- Access to github.com (for docker-compose installation: https://github.com) (TCP 443)
For offline installation, no external access is required.
Installation#
We advise you to use a dedicated linux user to install the application (ex: app). Don't forget to give sudo access to this user.
Configure the installation#
Inside your home directory, create a directory named gitguardian/ and inside a file name .preseed:
cdmkdir gitguardiancd gitguardiancat <<EOF > .preseedGG_CLIENT_ID=GG_CLIENT_KEY=GG_HOST=GG_SELFSIGNED=GG_TLS_CERT=GG_TLS_KEY=EOFWe will refer at gitguardian/ as the root directory of the application.
Edit the file .preseed and add you own value:
| Parameter | Description |
|---|---|
| GG_CLIENT_ID | You will receive this information during your onboarding |
| GG_CLIENT_KEY | We will send this value to you by SMS during your onboarding |
| GG_HOST | The FQDN (or the IP) that you want to use to reach the application |
| GG_SELFSIGNED | true means that we will generate a self signed certificate for HTTPS. This could be an easier solution to start the application if you don't have a valid certificate. When use true, GG_TLS_* values could be empty. |
| GG_TLS_CERT | The full path to a signed TLS certificate |
| GG_TLS_KEY | The full path to the associated private key |
Example with a self signed TLS certificate setup:
GG_CLIENT_ID=GGC_xxxxxxxxxxxxGG_CLIENT_KEY=GGK_yyyyyyyyyyyyGG_HOST=gitguardian.mycorp.localGG_SELFSIGNED=trueExample with a certificate signed by a CA:
GG_CLIENT_ID=GGC_xxxxxxxxxxxxGG_CLIENT_KEY=GGK_yyyyyyyyyyyyGG_HOST=gitguardian.mycorp.localGG_SELFSIGNED=falseGG_TLS_CERT=/etc/tls/cert.pemGG_TLS_KEY=/etc/tls/key.pemTLS PEM format for nginx#
You need:
- your server certificate (provided by your Certificate Authority)
- your intermediate certificates (provided by your Certificate Authority)
How to generate cert.pem file:
cat your_signed_cert.cert intermediate_cert.crt >> cert.pemOnce .preseed file is completed and saved, move to the next part.
Install the application (online mode)#
Note: online mode requires external access to our archive (see the URL below) as well as your distribution repository if you want to use our script to install software prerequisites.
Download our management CLI to install the application with the following command inside the root directory (/home/<USER>/gitguardian/):
curl -s https://get.gitguardian.com/manage.sh -o manage.sh && chmod +x manage.shStart the installation and automatically install software requirements:
./manage.sh install --install-depsStart the installation without installing software requirements (you will need to install these requirements independently):
./manage.sh installThe installation will continue without any needed interaction until the end.
Once the script has ended, you must create a the first account to be the owner of the workspace. This is the only account that will be allowed to log in should your SSO provider not be available.
The password is a one time password, and you will be required to update it after logging in.
# you may have to reload your shell to run this commanddocker-compose exec django python manage.py create_administrator --firstname <FirstName> --email <Email> --password <Password>Then, browse to the application using the GG_HOST value you configured beforehand.
Install the application (offline mode)#
Download our management CLI and the application tarball:
- Management CLI: https://get.gitguardian.com/manage.sh
- Application tarball: https://get.gitguardian.com/GGC_CLIENT_ID/latest
Replace GGC_CLIENT_ID inside the URL with your own value (sent during onboarding).
Upload these 2 files to your host:
- put
manage.shinside the root directory of the application (gitguardian/) - create a directory
download/insidegitguardian/and put the filegitguardian.latest.encinside
Fix permissions:
chmod +x manage.shDon't forget to install software requirements before starting the installation. Even in offline mode you can still use the option --install-deps if you have access to your distribution repository, docker repositories and GitHub (see requirements).
Start the installation and automatically install software requirements:
./manage.sh install --install-depsStart the installation without installing software requirements (you will need to install these requirements independently):
./manage.sh install --offlineThe installation will continue without interaction until the end.
Once the script has ended, you must create a the first account to be the owner of the workspace. This is the only account that will be allowed to log in should your SSO provider not be available.
The password is a one time password, and you will be required to update it after logging in.
# you may have to reload your shell to run this commanddocker-compose exec django python manage.py create_administrator --firstname <FirstName> --email <Email> --password <Password>Then, browse to the application using the GG_HOST value you configured beforehand.