Skip to main content

Getting Started

Welcome to the Comper private beta! This guide will help you get started with understanding your software landscape.

Private Beta: Comper is currently in private beta. You'll need a Docker Hub access token to download the Docker image. Contact us to receive your access key.

Prerequisites​

Before you begin, make sure you have:

  • Docker installed on your system (with docker compose support)
  • Access to your repositories via GitHub, GitLab, Azure DevOps, or Bitbucket
  • An API key or token for your version control system (or use local disk for locally checked out repos)
  • Docker Hub access token - Contact us to receive your access key

System Requirements​

Database​

We use Postgres and use max 50 connections by default. Make sure your DB can handle that. Size it to 1GB RAM + 5GB disk, and expand for larger teams.

Disk​

Comper will clone all your repos and maintain a lot of metadata, so for the non-database part, expect to use your git repo size * 2. We suggest starting with 10GB and expanding when needed.

CPU​

During the initial sync, we use a LOT of CPU resources to analyze all the git repos. The more CPU you throw at it, the faster it gets. After we're done analyzing the git repos, we use next to nothing.

Installation​

1. Get Docker Hub Access​

Contact us to receive your Docker Hub access token. Once you have it:

docker login -u comperio

Use the token provided to you when prompted for the password.

2. Docker Compose Setup​

We recommend using Docker Compose for deployment. Here's a sample docker-compose.yml:

volumes:
  postgres:

services:
  postgres:
    image: postgres:17
    ports:
      - 5432:5432
    volumes:
      - postgres:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=loco
      - POSTGRES_USER=loco
      - POSTGRES_DB=comper
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U loco -d comper"]
      interval: 5s
      timeout: 5s
      retries: 5

  mailhog:
    image: mailhog/mailhog
    ports:
      - 1025:1025
      - 8025:8025

  app:
    image: comperio/comper:latest
    ports:
      - 8001:8001
    depends_on:
      postgres:
        condition: service_healthy
      mailhog:
        condition: service_started
    environment:
      - DATABASE_URL=postgres://loco:loco@postgres:5432/comper
      - JWT_SECRET=ZWVuZzh0ZWl0MnpvaDRXYTgK
      - WORKERS=2
      - FRONTEND_URL=http://localhost:8001
      - PASSWORDS_ENABLED=true
    volumes:
      - /path/to/comper/storage:/comper/storage
      - /path/to/your-local-repos:/comper/repos

Important: Replace the volume paths (/path/to/comper/storage and /path/to/your-local-repos) with paths appropriate for your system. If you're paranoid and want to change the JWT secret, change it to something secure.

3. Start the Services​

Run:

docker compose up -d

Access Comper at http://localhost:8001

First Steps​

1. Create an Account​

Just sign up in the system. Go to localhost:8001 to access the interface.

2. Create a Board​

Create a board, then navigate to settings on the left, go to Sources and configure your source.

For local directories: Use the directory /comper/repos (mapped to your local repos in the docker-compose file). Just clone the repos you're interested in to that directory, and Comper will be able to scan them.

For cloud providers: You can sync with your GitHub, GitLab, Azure DevOps, or Bitbucket account. For Bitbucket, we suggest going with personal access tokens, as the other solutions require premium plans.

3. Repository Analysis​

Comper will start analyzing the repos in four steps for each:

  1. Fetch - Download/clone the repository
  2. Shallow inspection - Look at what is in the HEAD commit
  3. History parsing - Look at contribution stats over time
  4. Deep inspection - Get authorship stats (think massive git blame stats)

After step 2, we already show something on the board, and you can use "Auto Layout" and save to put things in a nice place. However, statistics won't work yet and authorship stats also won't work.

In these steps you can expect a LOT of CPU, disk and network traffic.

In the bottom left you can see the progress and queue of tasks. If the number says "0", we are completely done.

Note: Our feedback in the UI when there are errors isn't great yet, so keep an eye on the logs of the application to see if there are any errors.

4. Deduplicate Contributors​

When the analysis is underway, go to settings again, then to Contributors. The idea is to create "Contributors" from "Aliases". Each contributor (an actual person) might have multiple git aliases.

Under "Active Duty" you can mark users as still being with the company or already left.

Once you've done this, the bus factor calculation starts making sense.

Explore the Canvas​

  • Zoom In: Click or use the scroll wheel to zoom into specific areas
  • Zoom Out: See the big picture of your entire codebase
  • Navigate: Click and drag to pan around the canvas

Tips for Success​

  • Start Small: Begin with a single repository or team to get familiar with Comper
  • Use Filters: Filter by language, team, or individual to focus on specific areas
  • Monitor Progress: Check the queue status in the bottom left to see analysis progress
  • Check Logs: If something seems wrong, check the application logs for detailed error messages

Next Steps​

  • Learn about the Board - the main canvas and collaboration features
  • Configure Board Settings - administration and configuration
  • Check out our FAQ
  • Contact us if you need help

Support​

Need assistance? Reach out to us through: