Configuring DeepScan

This document helps system administrators and operators to configure and manage their DeepScan instance.

    Basically, the DeepScan instance can be configured by the file conf.yaml:

Configuring local GitLab

Registering your DeepScan OAuth application

  • Login to an administrator account on GitLab
  • Navigate to User Settings > Applications
  • Under Add new application, input values in Name and Redirect URI
    • Redirect URI should be in the format: <YOUR_DEEPSCAN_URL>/auth/gitlab/callback
  • Under Scopes, check api and read_user checkboxes
    • api: Grants complete read/write access to the API, including all groups and projects
    • read_user: Grants read-only access to the authenticated user's profile which includes username, public email, and full name
  • Click the Save application button for adding DeepScan application
  • Set the generated Application ID and Secret in the conf.yaml file
  • Register GitLab app
      Note: The following values MUST be matched with the configuration file
      • The base URL of Redirect URI must be same with baseUrl defined in the conf.yaml file
      • The Application ID, Secret must be same with auth.git.clientID, auth.git.clientSecret defined the conf.yaml file

Allowing GitLab outbound requests

  • Access the GitLab Admin Area via GitLab administrator user account
    • Click the Admin Area icon in the top menu or visit /admin on GitLab
  • Navigate to Admin area > Settings > Network
  • Expand the Outbound requests section
  • Check the "Allow requests to the local network from hooks and services" checkbox
  • Hit the Save changes button
  • GitLab network settings

Configuring DeepScan

  • Create the conf.yaml file in the path specified in the environment variable DEEPSCAN_DATA for the configuration of DeepScan On-premise
  • MUST define Base URL(baseUrl), GitLab information(auth.git), PostgreSQL database(db*) and license key(licenseKey)
  • Save the conf.yaml file and restart DeepScan for the changes to take effect
  • The following configuration in the conf.yaml file is minimally required. Make sure that it is properly configured for your environment. Otherwise, DeepScan will not work at its best.
  • # base URL is public URL that user will connect.
    baseUrl: <YOUR_DEEPSCAN_URL>
    
    # Server port sets the port of host to be bound with 80 port of container.
    # If falsy, use port from <YOUR_DEEPSCAN_URL>
    serverPort: <YOUR_DEEPSCAN_PORT>
    
    licenseKey: <YOUR_DEEPSCAN_LICENSE_KEY>
    
    dbHost: <YOUR_POSTGRES_IP_ADDRESS>
    dbName: <YOUR_POSTGRES_DB_NAME>
    dbUser: <YOUR_POSTGRES_DB_USER>
    dbPassword: <YOUR_POSTGRES_DB_PASSWORD>
    
    # Contact's email address to support system-wide operations
    supportEmail: <YOUR_DEEPSCAN_SUPPORT_EMAIL>
    
    auth:
      git:
        name: <YOUR_GITLAB_NAME>
        baseURL: <YOUR_GITLAB_SERVER_IP_ADDRESS>:<YOUR_GITLAB_SERVER_PORT>
        # Assumes you configured the DeepScan application on your GitLab and acquired its ID and secret
        clientID: <YOUR_GITLAB_APPLICATION_ID>
        clientSecret: <YOUR_GITLAB_APPLICATION_SECRET>
      # Set the DeepScan administrator with GitLab account's email
      adminEmails:
        - <YOUR_DEEPSCAN_ADMINISTRATOR_EMAIL>
    

Configuring email settings

Email settings MUST be configured so that DeepScan will able to send notification emails, like analysis reports and team invitations.

# configure the email SMTP settings
email:
  enable: true
  productName: <PRODUCT_NAME_USED_IN_EMAIL>
  supportEmailAddr: <support@your-deepscan-site.com>
  nodemailerOptions:
    port: <YOUR_SMTP_SERVER_PORT>
    host: <YOUR_SMTP_SERVER_HOST>
    # Enable to use an encrypted connection. The default value is false.
    secure: false
    # Enable to log. The default value is false.
    logger: false
    # Enable to debug. The default value is false.
    debug: false
    auth:
      user: <USER_NAME>
      pass: <USER_PASSWORD>

Note: For more details, see Nodemailer SMTP Options.

Configuring log settings

Log settings can be configured to your liking.

logDir: <LOG_FILE_PATH>
logOptions:
  console:
   # enable should be true or false. The default value is true.
    enable: true
    # level should be one of '', 'error', 'warn', 'info', 'verbose', 'debug', 'silly'. The default value is 'info'.
    level:
    # Enable to colorize log message. The default value is false.
    colorize:
    # Enable to use JSON formatting. The default value is false.
    json:
  file:
    # enable should be true or false. The default value is true.
    enable: true
    level:
    colorize:
    filename:
    json:
    # A string representing the moment.js date format to be used for log file rotating daily.
    # For more details, see winston-daily-rotate-file.
    # eg. {filename: 'deepscan%DATE%.log', datePattern: '-yyyyMMdd'}
    datePattern:
  slack:
    # enable should be true or false. The default value is false.
    enable: false
    webhookUrl:
    username:

Configuring IP whitelist

To monitor DeepScan's internal metrics, the requesting IP needs to be included in IP whitelist. The DeepScan do not apply a rate limit to all requests from IP whitelist.

To set IP whitelist, copy the license key provided and then paste it into the monitoringIpWhitelist field in conf.yaml:

# The default value is '127.0.0.1'. Use IP or CIDR format such as "127.0.0.1" or "192.168.1.0/24".
monitoringIpWhitelist:
  - 127.0.0.1

Managing licenses

You MUST have a license to activate DeepScan On-premise. By purchasing the product, you are granted a license for your company.

To set a license, please do the following:

  • Copy the license key provided, then paste it into the licenseKey field in conf.yaml:
    licenseKey: <YOUR_DEEPSCAN_LICENSE_KEY>
  • Review the license details in the Overview > License section of System Settings
    License details

You can view the license details:

  • Expiration Date: License expiration date
  • Users Limit: Number of total users who can sign in
  • LoC Limit: LoC (Lines of Code) is the total number of lines that you can analyze
    • Project LoC by its branch is the count of source lines in the file (excluding empty lines, white space lines, comment lines and style tag in the Vue template)
    • LoC of the largest branch from projects are counted toward the limit
What happens when your license expires:
  • DeepScan On-premise will lock down main features like analyzing projects, etc.
  • In order to get back all previous functionality, a new license must be set in the conf.yaml file

Using an external DB

  • Modify the docker-stack-external-db.yml file to use your external DB instead of the one in the container
  • MUST set additional DB configuration in the conf.yaml file:
  • dbHost: <YOUR_POSTGRES_IP_ADDRESS>
    dbName: <YOUR_POSTGRES_DB_NAME>
    dbUser: <YOUR_POSTGRES_DB_USER>
    dbPassword: <YOUR_POSTGRES_DB_PASSWORD>
  • Run the following command to deploy the DeepScan Docker stack
  • $ docker stack deploy --compose-file scripts/on-premise/docker-stack-external-db.yml deepscan-stack

Customizing appearances

For DeepScan On-premise, it is possible to customize the login page and global footer.

If you would like to add your custom login page or global footer, set the property/value pair in the conf.yaml file.

By default, the login page shows the login button and the DeepScan logo. Also, the footer shows the DeepScan logo and the links to the help documentation and our hosted service.

Default login page
appearance:
  loginHTMLText: ''
  footerHTMLText: `
<div class='default-footer'>
    <div class='container'>
        <div>
        <address>DeepScan</address>
            <ul class='link-menu-bar'>
                <li><a class='link-menu-bar-item' href='/docs/'>Help</a></li>
                <li><a class='link-menu-bar-item' href='https://deepscan.io/' target="_blank">About DeepScan</a></li>
            </ul>
        </div>
    </div>
</div>`

The following is an example of a custom login page:

appearance:
  loginHTMLText: `
<div>
    <center>
        <h4>Sign in with GitLab via LDAP</h4>
        <a href="<YOUR_COMPANY_LINK>" target="_blank">Create Account</a> | <a href="<YOUR_COMPANY_LINK>" target="_blank">Help</a>
    </center>
</div>`

Update the instance using the following command to apply the changes made.

$ docker service update deepscan-stack_core --force