Installing DeepScan

This document helps system administrators and operators to set up, customize and update a DeepScan instance.

Requirements

Hardware Requirements
  • 2-core CPU, 4-core or more recommended
  • 2GB of RAM, 8GB or more recommended
Service Requirements
  • Linux: Need to support Docker Swarm environment
Docker Information

Our distributed Docker image has the following packages:

  • Ubuntu 16.04 64-bit
  • Java 8
  • Node.js 12
  • PostgreSQL 10

If you want to use an external PostgreSQL, follow this guide.

Supported Platforms
  • GitHub Enterprise Server 2.18+
  • GitLab Community Edition stable release (9.X+)
  • GitLab Enterprise Edition stable release (9.X+)
  • The latest Chrome, Firefox, Edge and Safari web browsers

Installing using Docker

First of all, you need to setup the host environment for Docker.

  1. Choose a location and create the directory where the DeepScan distribution will be unzipped and data will be stored. We will use /opt/deepscan in this document.
    $ sudo mkdir -p /opt/deepscan
  2. Download and unzip the distribution file into the directory.
    $ cd /opt/deepscan
    $ unzip <download_directory>/deepscan-<version>.zip
    
  3. The directory structure looks like the following:
    /opt/deepscan/
    └── deepscan-<version>
        ├── deepscan-<version>.tar          # DeepScan Docker image
        ├── docker-stack-external-db.yml    # Docker stack configuration to use an external DB
        └── docker-stack.yml                # Docker stack configuration
    
  4. We use docker-stack.yml to run DeepScan with Redis and PostgreSQL easily.
    The stack file requires two environment variables set: DEEPSCAN_DATA for DeepScan directory and PORT for host port.
  5. $ export DEEPSCAN_DATA=/opt/deepscan    # Will be mounted with /data in the Docker container
    $ export PORT=5012                      # Host port that will be bound with port in the docker container
    
  6. Run the following commands to load DeepScan Docker image into local registry.
  7. $ docker load -i deepscan-<version>/deepscan-<version>.tar
    1ea5a27b0484: Loading layer [==================================================>]  123.5MB/123.5MB
    24ab7de5faec: Loading layer [==================================================>]  11.78kB/11.78kB
    ...
    Loaded image: deepscan:<version>
    
  8. Verify that the image is loaded successfully.
  9. $ docker image ls deepscan
    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
    deepscan            <version>           c1ebadc8b76a        19 hours ago        1.27GB
    
  10. You can delete the deepscan-<version>.tar file as it is not used anymore.

Configure DeepScan

DeepScan is working as an OAuth application with your local GitLab or GitHub.

You need to add the DeepScan application in your Git server before running DeepScan. Read Configuring GitHub Enterprise or Configuring local GitLab to get an application id and secret for DeepScan.

Then, create /opt/deepscan/conf.yaml and fill it with your environment.

The following is the minimal configurations:

  1. The base URL for DeepScan service: Set to the same port as the PORT environment variable
  2. The Git service URL, client id, and client secret
  3. The license key

GitHub Example

baseUrl: http://your.host:5012
auth:
    git:
        type: GitHub
        name: GitHub
        baseURL: http://your.local.github
        clientID: 76a2d3a494a0c882e86023893787b2e4b5da...
        clientSecret: 3e760eb805172c457aebdf7d2691f376cb2...
licenseKey: owJ4nJvAy8z......

GitLab Example

baseUrl: http://your.host:5012
auth:
    git:
        type: GitLab
        name: GitLab
        baseURL: http://your.local.gitlab
        clientID: 76a2d3a494a0c882e86023893787b2e4b5da...
        clientSecret: 3e760eb805172c457aebdf7d2691f376cb2...
licenseKey: owJ4nJvAy8z......

Running DeepScan

Before running DeepScan, check whether you setup your Git server and configured DeepScan:

Then, you can run DeepScan as the following:

  1. If you have not yet initialized Docker swarm environment in host, run the following command to initialize it.
    $ docker swarm init
  2. Run the following command to run the DeepScan Docker stack. It will run DeepScan, Redis and PostgreSQL services.
    $ docker stack deploy --compose-file deepscan-<version>/docker-stack.yml deepscan
    Creating network deepscan_default
    Creating service deepscan_core
    Creating service deepscan_redis
    Creating service deepscan_postgres
    
  3. Verify that the stack is deployed.
    $ docker stack ps deepscan
    ID                  NAME                        IMAGE                NODE                DESIRED STATE       CURRENT STATE                ERROR               PORTS
    sahm2vwysg4u        deepscan_core.1             deepscan:<version>   myhost              Running             Running 1 second ago
    97ttoc387438        deepscan_postgres.1         postgres:10-alpine   myhost              Running             Running about a minute ago
    4x6myrw9hkhg        deepscan_redis.1            redis:5-alpine       myhost              Running             Running about a minute ago
    
  4. You can now browse DeepScan at the baseUrl defined in the conf.yaml file.
  5. If you encounter problems trying to start, see the debugging guide.

Updating DeepScan

You can update DeepScan as the following:

  1. Download and unzip the updated DeepScan Docker image.
  2. Verify environment variables DEEPSCAN_DATA and PORT are correct.
  3. Run the following commands to load and start the updated DeepScan Docker stack.
  4. $ cd $DEEPSCAN_DATA
    $ docker service update --force deepscan_core