SourceTraq's Self-Hosted Containerized Deployment empowers organizations to run the full analytics and reporting system within their own infrastructure. It combines the frontend user interface and automated PDF report generation into a Docker container, offering complete control over scheduling, configuration, and data management.

• Docker Engine: Installed and running on the target host machine. The containerized app runs using Node.js and Puppeteer inside the container.
• Internet Connection: Required to pull the Docker image initially, and for connecting to cloud-based repository hosts like GitHub Cloud or GitLab Cloud.
• Network Access to Repositories: If integrating with internal or self-hosted repositories such as BitBucket Data Center, direct network access to these APIs is required.
• Port Availability: Ports 80 (HTTP) and/or 443 (HTTPS) should be free for binding by the container service.
• Optional SSL Certificates: For HTTPS configuration, provide valid SSL certificate and key files within the mounted configuration folder.

The official SourceTraq Docker image is published on Docker Hub, and initial download will be close to 1GB of data. Updates after the initial download are typically smaller in size. To pull the latest image, use:

This command downloads the stable version containing the Node.js backend, frontend static bundle, and Puppeteer for PDF generation.

Keep in mind to periodically pull the newest image to obtain bug fixes and feature updates, as automatic update mechanisms are not included.

To explore the list of available SourceTraq container images, including different versions and tags, you can visit the official Docker Hub repository here: https://hub.docker.com/r/utilsware/sourcetraq.

This resource provides information about published images, tags, and their corresponding documentation, assisting you in selecting the appropriate version for your deployment needs.

The SourceTraq container reads configuration and stores data within a shared mounted folder, typically named shared. This folder contains:

• config.json: Main configuration file defining integrations, scheduler, authentication, and network settings.
• output/ folder: Contains generated PDF reports organized by date.
• SSL certificate files: If HTTPS is enabled, this folder also stores cert.pem and key.pem or other valid certificate files.
• data and output files: Automatically managed queue file that tracks scheduled and manual PDF generation tasks.

This setup guarantees persistence: data and configuration survive container removal or recreation, providing continuity and ease of maintenance.

Example config.json file

{
  "useSSL": false,
  "integrations": [
    {
      "name": "Github React",
      "type": "GitHubCloud",
      "url": "https://github.com/facebook",
      "schedule": {
        "expression": "0 0 * * 1",
        "timezone": "UTC"
      },
      "auth": {
        "type": "oAuth",
        "secret": "gho_exampletoken123456",
        "username": ""
      },
      "dateRange": {
        "start": "-1m",
        "duration": "1m"
      },
      "query": [
        {
          "project": "facebook",
          "repository": "react",
          "branch": "main",
          "teams": []
        }
      ],
    },
    {
      "name": "BitBucket Server Project",
      "type": "BitBucketServer",
      "url": "https://bitbucket.company.local",
      "schedule": {
        "expression": "0 0 1 * *"
      },
      "auth": {
        "type": "BASIC",
        "secret": "bB_password_or_token",
        "username": "user1"
      },
      "dateRange": {
        "start": "-2m",
        "duration": "2m"
      },
      "query": [
        {
          "project": "PROJKEY",
          "repository": "project-repo",
          "branch": "develop",
          "teams": ["teamA", "teamB"]
        }
      ],
      "settings": {
        "prChangesDisplay": "none",
        "commitChangesDisplay": "none",
        "includeCommits": false,
        "includePRActivity": false,
        "includePRCommitMetrics": false,
        "teams": []
    }
  ],
  "email": {
    "to": "user1@example.com, user2@example.com",
    "cc": "cc1@example.com, cc2@example.com"
  }
}

Detailed Explanation of config.json Properties:

• useSSL (boolean, optional)
  Determines whether the container listens with HTTPS (true) or HTTP (false). When set to true, SSL certificate files must be provided.
• sslKeyFile (string, optional)
  Filename of the SSL private key file relative to the shared folder, used when useSSL is true. Example: "key.pem". This file must contain a valid private key.
• sslCertFile (string, optional)
  Filename of the SSL certificate file relative to the shared folder, used when useSSL is true. Example: "cert.pem". This file must contain a valid certificate corresponding to the private key.
• chromePath (string, optional)
  Absolute path to a custom Chrome or Chromium executable to use with Puppeteer inside the container. If omitted or empty, the bundled Chromium version within the container is used automatically.
• maxRetry (number, optional, default: 3)
  The maximum number of retries allowed for PDF generation jobs that fail due to transient errors before marking as permanently failed.
• networkWaitTimeout (number, optional, default: 120000)
  Timeout in milliseconds that Puppeteer waits for all network requests to complete before generating the PDF during report creation. Adjust if your repository APIs are slow or unreliable.
• integrations (array of objects, required)
  Defines one or more repository integrations. Each object contains:
  • name (string): Unique identifier for the integration used for logging and report filenames.
  • type (string): Repository type, e.g. BitBucketCloud, BitBucketServer, GitHubCloud, or GitLabCloud.
  • url (string): Base URL of the repository host. For repositories like GitHub or BitBucket Cloud, this URL can include the default project or workspace as the first path segment if applicable.
  • schedule (object, optional): Controls automatic PDF generation scheduling.
    • expression (string): Cron expression specifying the schedule. It should follow the standard cron format: `minute hour day-of-month month day-of-week`. Here are some examples:

      Expression	Description
      "0 0 1 * *"	Runs at midnight on the 1st day of every month.
      "0 0 1 1 *"	Runs at midnight on January 1st every year (New Year's Day).
      "0 0 1 1 0"	Runs at midnight on January 1st of every Sunday (quarterly on the first Sunday of Jan).
      "0 9 * * 1"	Runs at 09:00 AM every Monday.
      "0 0 * * 1"	Runs at midnight every Monday.
      "0 12 * * 1"	Runs at noon every Monday.
      "0 0 1 1,4,7,10 *"	Runs at midnight on the 1st of every quarter.
      "0 0 1 3,6,9,12 *"	Runs at midnight on the 1st of March, June, September, December (quarterly).

  • auth (object): Authentication method configuration with:
    • type (string): Either oAuth or BASIC.
    • secret (string): API key, OAuth token, or password.
    • username (string, optional): Required only for BASIC auth where username/password authentication is used.
  • dateRange (object): Specifies the time window of repository data to include in reports.
    • start (string): Relative start date expressed as negative offset, e.g., "-3m" for 3 months ago. Supports units: m (months), w (weeks), d (days), y (years).
    • duration (string, optional): Length of the reporting duration from start, e.g., "1m" for 1 month. If omitted, current date is taken as end date.
  • query (array): List of filters specifying projects, repositories, branches, and optionally teams for which reports are generated.
  • isActive (boolean): Enables or disables this integration without removing its configuration.
  • settings (object): Feature flags controlling which metrics and data are included in report generation and live views.
• email (object, optional): Can be specified at multiple levels—root, integration, query, or team. The union of all specified email addresses will be used for report notifications. The to and cc fields support either an array of strings or a comma-separated string. Example:

  "email": {
    "to": ["recipient1@example.com", "recipient2@example.com"],
    "cc": "cc1@example.com, cc2@example.com"
  }

Advanced Configurations

Optional configuration parameters include the path to Chrome (if you want to use a custom browser), network request timeout for page loads, SSL certificate files, and SMTP email settings.

Place the config.json and any SSL certificates into a folder on your host machine (e.g., /path/to/shared). Then start the Docker container mounting this folder as a volume for shared persistent data:

Note that:

• The shared folder will persist your configuration, scheduler data, queue, and generated reports.
• Ports 80 (HTTP) and 443 (HTTPS) are exposed; configure useSSL accordingly.
• Docker container runs Node.js backend, serves frontend UI at http://localhost, and processes scheduled PDF report generation.
• If mounting from Windows command line, replace /path/to/shared with your current directory using %cd% environment variable as shown:

After starting the container, you may access the SourceTraq UI and API at:

• HTTP: http://localhost or http://{your-server-ip or hostname}
• HTTPS: https://localhost or https://{your-server-ip or hostname} (if SSL enabled in configuration)

The UI provides analytics dashboards and report previews.

Ensure your network/firewall allows inbound traffic on ports 80/443 if accessing externally.

The SourceTraq container includes a scheduler that automatically generate report at regular interval:

The reports are stored under the output/YYYY_MM_DD/ subfolders inside the shared folder, grouped by generation date.

This automated approach ensures your organization always has up-to-date repository metrics reports without manual intervention.

To update SourceTraq settings such as adding new integrations, changing schedules, or editing authentication details:

1. Stop the running container:
docker stop sourcetraq-app
2. Edit the config.json file inside your mounted shared folder using any text editor.
3. Save your changes and restart the container:
docker start sourcetraq-app
4. The scheduler will pick up the new configuration automatically on next run.

Configuration changes take full effect without requiring image rebuild or container recreation.

Chrome Path: By default, the Docker container uses the bundled Chromium version for Puppeteer. If preferred, you may specify a custom Chrome executable path in the config file under the chromePath property. This supports using a different Chrome installation by absolute path.

Network Wait Timeout: The networkWaitTimeout configuration controls how long Puppeteer waits for network requests to complete before generating the PDF. Default is 120000 milliseconds (2 minutes). Adjust this if your environment has slower API response times.

SMTP configuration options are included in the config file for sending generated PDF reports automatically via email. Current support includes properties like:

• SMTP server address and port
• From email address
• To and CC recipient lists (arrays or comma-separated strings)
• Authentication credentials

Proper configuration of these properties enables automated distribution of generated reports via email.

The email object with to and cc fields can be specified at any level—root, individual integration, queries, or team levels. The union of all specified email addresses will be used for sending notifications.