Codechecker server

This repository contains required scripts and instructions for setting up, running and maintaining CodeChecker server.

Table of contents

• Setup server
• Setup authentication
  • Adding a new user as a server admin
  • Setting up command line access as a user
• Changing permissions
• Providing credentials to the CI runners
  • Setting up authentication in GitHub Actions
• Suggested user and group setup
• Creating new products - Codechecker integration in East
  • New product
  • Product permissions
• Relevant documentation

Setup server

1. Install Docker Engine:

./scripts/install_docker.sh

2. Start CodeChecker server.

./scripts/start_server.sh

3. Run the commands below to see the logs generated by the start_server.sh script to get the randomly generated superuser name and password.

docker ps -a

Above command will print information about running containers:

CONTAINER ID   IMAGE                                COMMAND                  CREATED         STATUS         PORTS                                       NAMES
d3d3c749c5fb   codechecker/codechecker-web:latest   "/tini -- /usr/local…"   3 minutes ago   Up 3 minutes   0.0.0.0:8001->8001/tcp, :::8001->8001/tcp   irnas-codechecker-software-codechecker-1

Note the CONTAINER ID of the codechecker/codechecker-web:latest container and run

docker logs <CONTAINER_ID>

Note the superuser credentials somewhere safe.

4. Test if you can access the server via 8001. If you are running this on a local development machine you can try opening 127.0.0.0:8001 url address in your browser. If you are running this on some AWS or Azure instance you will need to expose the IP and port.

Setup authentication

After first server run a workspace folder with default configuration files is created inside the project's root directory. This folder will later also contain database files created by CodeChecker.

Authentication is handled in the workspace/server_config.json file.

1. Open it and set authentication.enabled to true. Do the same for the authentication.method_dictionary.enabled.

2. Restart server for changes to take effect:

./scripts/stop_server.sh
./scripts/start_server.sh

3. Try opening the same IP address as before. A login will be required. You can login as superuser with previously printed credentials.

Adding a new user as a server admin

The authentication.method_dictionary contains a plaintext username:password credentials for authentication. If the user's login matches any of the credentials listed, the user will be authenticated.

Groups are configured in a map which maps to each username the list of groups the user belongs to.

For example, below snippet adds two users, admin and user which have passwords admin_pass and user_pass respectively. admin belongs to a groups admin and guest, while user only belongs to the guest group.

"method_dictionary": {
  "enabled" : true,
  "auths" : [
      "admin:admin_pass",
      "user:user_pass"
  ],
  "groups" : {
      "admin" : ["admin", "guest"],
      "user" : ["guest"]
  }
}

Important: When choosing passwords, use either 1Password generator, or some other password generator.

Setting up command line access as a user

Any CodeChecker commands that are accessing the server require login.

To perform that you need to run:

CodeChecker cmd login --url <server_url>
# or this if using east
east codechecker bypass cmd login --url <server_url>

Changing permissions

User and group permissions are managed via Web UI. EDIT GLOBAL PERMISSIONS is visible to the superuser and users with elevated permissions.

Providing credentials to the CI runners

Codechecker provides a way to specify credentials via file. This is a desired method for the GitHub Action Runners.

Steps:

1. Create a new user:password pair in workspace/server_config.json file.
2. Create two new secrets in the repository. Name them CODECHECKER_SERVER_URL and CODECHECKER_CREDENTIALS.
3. Set CODECHECKER_SERVER_URL to contain full url of the Codechecker server.

<url_to_server>

4. Set CODECHECKER_CREDENTIALS to contain whitespace-removed JSON string contains credential data.

{"client_autologin":true,"credentials":{"<url_to_server>":"<username>:<password>"}}

Setting up authentication in GitHub Actions

See below snippet on how to access the secrets in GitHub Actions.

steps:
  - name: Prepare CodeChecker password file
    env:
      CODECHECKER_CREDENTIALS: ${{ secrets.CODECHECKER_CREDENTIALS }}
    run: |
      echo $CODECHECKER_CREDENTIALS > ~/.codechecker.passwords.json

  - name: Login to CodeChecker server
    env:
      CODECHECKER_SERVER_URL: ${{ secrets.CODECHECKER_SERVER_URL }}
    run: |
      east codechecker bypass cmd login --url "$CODECHECKER_SERVER_URL"

Suggested user and group setup

Below setup is sufficient, if all users are allowed to access all projects stored on the CodeChecker server. Permissions can then be managed per group basis.

"method_dictionary": {
  "enabled" : true,
  "auths" : [
      "admin:admin_pass",
      "user_1:user1_pass",
      "user_2:user2_pass",
      "ci_runner:ci_runner_pass"
  ],
  "groups" : {
      "admin" : ["admin"],
      "user_1" : ["users"],
      "user_2" : ["users"],
      "ci_runner" : ["ci_runners"]
  }
}

• Admin is the only one with elevated permissions, he can create new products.
• Users can view projects.
• CI runners have store and access permissions.

Creating new products - Codechecker integration in East

New product

To create a new product navigate to your CodeChecker server and login.

Note

For the IRNAS server URL and password, check 1Password by searching irnas_user.

1. Click on the New Product button and fill in the fields URL endpoint, Display name with the name of the repository. For example, if the name of the repository is irnas-example-repository, then both fields should match it (see screenshot below).
2. Set Information Classification to Open classified.
3. Select the SQLite database type and name your database the same as URL endpoint and Display name fields. Click Save.

Note

Make sure that the URL endpoint of the product matches the exact name of the git repository. This is needed as the east codechecker store command finds out the name of the git repository and uploads any analyses to the <server_url>/<git_respository> endpoint.

Product permissions

You must give product permissions whenever you need user to access that product. This can be done by clicking on the pencil icon on the right side of the product row and selecting the PERMISSIONS tab.

You can assign permissions on the user level or group level. For bot users (usually CI accounts) is enough to have PRODUCT_ACCESS and PRODUCT_STORE permissions.

Note

For the GitHub Actions developed by IRNAS is required to give group ci_users PRODUCT_ACCESS and PRODUCT_STORE permissions. See image below.

Relevant documentation

• Docker Engine Installation
• CodeChecker Server Authentication
• CodeChecker Docker Compose setup