Installation

There are two options for installing CodeScene:

  • CodeScene inside a Docker container (recommended)

  • Standalone CodeScene Application

Run CodeScene Application inside a Docker container

We provide a codescene/codescene docker image on Docker Hub . This Docker image makes it easy to get an instance of CodeScene up and running within a well-defined environment.

Stored Data

The docker image defines a volume at /codescene for storing data. Make sure that a bind mount or a docker volume is defined for /codescene when starting the container to persist your data beyond the life of the Docker container.

The /codescene volume will be used by CodeScene for storing cloned Git repositories and analysis result files. When using an internal database, it will also be also stored under /codescene.

User configuration

This image runs CodeScene as a dedicated codescene user (UID 10999) inside the container. It also creates the codescene user group (GID 10999) and set it as the primary group for the user.

The user has /codescene as the home directory. This is useful when making ssh configuration since ssh configuration for the codescene user will, by default, be stored in /codescene/.ssh and persisted along with the other data.

Note that on startup, everything in the /codescene volume will be automatically set to be owned by the codescene user (files’ group is not changed, so you might still see root as the group).

Git repository access

To analyze code located on remote servers, CodeScene needs to be able to clone it with Git. For public repositories, cloning via https is sufficient, but for private repositories authentication credentials will be required, for which SSH keys are the recommended form.

To use SSH keys with this image, create an SSH key (EdDSA) inside the container as the codescene user:

docker exec -it -u codescene [CONTAINER] ssh-keygen -q -t ed25519 -C "codescene" -N '' -f "/codescene/.ssh/id_ed25519"

replace [CONTAINER] with your container name, the ssh key will be created on the default location with no passphrase.

Add the corresponding public key to your repository provider to provide access for CodeScene to your git repositories. The public key can be displayed with:

docker exec -it -u codescene [CONTAINER] ssh-keygen -y -t ed25519 -f "/codescene/.ssh/id_ed25519"

replace [CONTAINER] with your container name

For testing the ssh access to your repository provider after adding the ssh key, you can use a command similar to:

docker exec -it  -u codescene [CONTAINER]  ssh -T git@github.com

replace [CONTAINER] with your container name

Using local repositories

CodeScene is also able to analyze repositories on local storage, which is storage within Docker container, if using Docker. If you want to analyze repositories that are local folders in Docker host, you’ll need to mount them into the CodeScene Docker container.

Example: Run CodeScene using docker-compose

  1. Use this docker-compose.yml to configure CodeScene with data persisted the stored data on a docker volume :

    version: '3'
services:
  codescene:
    image: codescene/codescene:latest
    ports:
      - 3003:3003
    volumes:
      - codescene:/codescene

volumes:
  codescene:

  2. Run docker-compose up -d to start the CodeScene instance.

  3. Run docker-compose exec -u codescene codescene ssh-keygen to generate an SSH key inside the container with no passphrase.

  4. Run docker-compose exec -u codescene codescene ssh-keygen -y to display the public SSH key.

  5. Add that key to a user on your repository provider with read access to your repositories.

  6. Go to the CodeScene URL (http://localhost:3003), validate and login using your license credentials, and create projects using the Specify Remotes option.

Example: Run CodeScene using docker

  1. Run docker run to start CodeScene (in this case with /codescene bound to a subdirectory):

    docker run -d -it -p 3003:3003 \
        --name codescene \
        -v codescene:/codescene \
        codescene/codescene

  2. Run docker exec -it  -u codescene codescene ssh-keygen to generate an SSH key inside the container with no passphrase.

  3. Run docker exec -it  -u codescene codescene ssh-keygen -y to display the public SSH key.

  4. Add that key to a user on your repository provider with read access to your repositories.

  5. Go to the CodeScene URL (http://localhost:3003), validate and login using your license credentials, and create projects using the Specify Remotes option.

Custom settings

Java settings

For advanced use cases, the CodeScene docker image uses a JAVA_OPTIONS environment variable to make it possible to set custom Java settings.

As an example, to specify a custom trust store containing self-signed certificates you could do something like this in docker-compose.yml:

environment:
    - JAVA_OPTIONS=-Djavax.net.ssl.trustStore=/java-truststore.ks -Djavax.net.ssl.trustStorePassword=mypwd

volumes:
   - /my-truststore.ks:/java-truststore.ks

Timezone

CodeScene, in general, uses the host system’s default timezone. In this docker image, UTC is set as the default timezone. The timezone can be overridden via CODESCENE_TIMEZONE environment variable - e.g. in docker-compose.yml:

environment:
    - CODESCENE_TIMEZONE=Europe/Stockholm

Notes for Windows deployments

When deploying the CodeScene docker image in a Windows deployment, it is important to use WSL2 and to run docker from the Linux shell used as the WSL2 distro. The bind mount directory used for CodeScene data must reside inside Linux and may not be shared from the Windows drive via /mnt/c or similar. More details are described in the WSL 2 Best Practices and WSL 2 Backend Details .

Support for ARM architecture

Each image is available for x86/amd64 and arm64 architecture. When pulling the image, Docker should automatically pick the right one.

If it doesn’t, just add --platform to docker pull command. Example command to pull arm64 that will work optimally on Mac with M1 chip:

docker pull --platform linux/arm64 codescene/codescene

Run the Standalone CodeScene Application

Install the Supporting Tools

You need the following prerequisites to run CodeScene as a standalone application:

  • A Java run-time (or JDK if you run from the command prompt), 64-bit version, Java 17+. You ensure you have the right Java version by typing java -version in a command prompt.

  • Have a Git client on your path since the tool will assume there’s an executable named git somewhere. Your Git client has to be at least version 2.32. You ensure you have the right Git client version by typing git --version in a command prompt.

  • SSH client for use with Git when accessing repositories protected by a pair of public/private keys.

Please note that you can specify a custom Git client in the Configuration section once you login to CodeScene.

See also Configure your Environment for Git SSH key instructions.

Start CodeScene

You start CodeScene by launching the standalone JAR:

java -jar codescene.standalone.jar

This will launch a web application that listens on port 3003 (you can override that by setting a different port through the environment variable CACS_RING_PORT.

Once you’ve launched the codescene.standalone.jar you just point your web browser to localhost:3003 to access CodeScene.

Define the Root Paths for Persistent Data

CodeScene creates a local database for the analysis configurations. By default the database file resources/caacs_enterprise.db.mv.db is created in the working folder (that is, the directory where you run CodeScene).

You can override the default and provide a custom path through the environment variable CODESCENE_DB_PATH. Note that you need to specify a complete file name. As an example, if you specify /User/Services/CodeScene/configuration, CodeScene will create a persistent database file named /User/Services/CodeScene/configuration.mv.db.

CodeScene will also need access to a writeable file system where it can store analysis results and cloned Git remotes. In some environments (e.g. Docker) you might want to constrain those paths so that users don’t specify paths to a non-persistent storage. You do this by two optional environment variables:

  1. CODESCENE_ANALYSIS_RESULTS_ROOT : Specifies the root path to where all analysis results will be written. CodeScene auto-generates a folder for each analysis project.

  2. CODESCENE_CLONED_REPOSITORIES_ROOT : Specifies the root path to where Git remotes will be cloned locally. CodeScene auto-generates a folder for each analysis project.

The advantage of specifying these two optional environment variables is that the user won’t have to deal with configuring the result paths – it’s automated – and analysis results are always stored to a known partition.

Configure the available Memory

RAM is a critical resource for CodeScene. We recommend at least 4 GB of RAM. If your codebase has large files or you analyze large repositories you might need more memory.

The Java’s virtual machine (JVM) has a system dependent maximum for “max heap” size that is typically 1/4 of RAM. You can set the max heap size to a larger value via -Xmx or -XX:MaxRAMPercentage (50-60 is a good value - we use 60 in our Java settings).

On large codebases with large hotspots (e.g. thousands of lines of code in each file) you also want to increase the stack size for the JVM to allow efficient code health calculations. You do this with the -Xss flag.

Here’s an example that shows how to allocate 60% of RAM as max heap size and 2 MB for each thread’s stack:

java -XX:MaxRAMPercentage=60 -Xss2m -jar codescene.standalone.jar

Note that the order of the arguments matter in this case (-jar must come only after the other flags).

Configure HTTP server’s thread count

Requests to HTTP Server for UI dashboard, REST API and various Webhooks by 3rd party systems such as GitHub, Bitbucket, Azure etc. are served by 8 threads. You can change this via CODESCENE_SERVER_THREADS environment variable.

Avoid missing stack traces

In some situations, the JVM skips stack trace generation and you won’t get full stack strace details which may make troubleshooting more difficult. You’ll find a message indicating this happened in the logs, e.g.:

java.lang.ClassCastException
Stack trace of root exception is empty; this is likely due to a JVM optimization that can be disabled with -XX:-OmitStackTraceInFastThrow.

You can disable this optimization and make sure stack traces are always visible by using the -XX:-OmitStackTraceInFastThrow flag when starting the application:

java -XX:-OmitStackTraceInFastThrow -jar codescene.standalone.jar

Optional: Specify a Path Prefix

In some network configurations, it may be necessary to access CodeScene with a path prefix, for example as internal.example.com/codescene. This might arise when CodeScene is one of several services running on the same server or it is not possible to attribute a dedicated subdomain for CodeScene. While a proxy server can be configured to correctly direct incoming requests, all the links in CodeScene, by default, are relative to the root path, /.

To avoid this, CodeScene can be run with the CODESCENE_PATH_PREFIX environment variable. The value supplied will be prepended to all internal CodeScene links. If used, the path prefix value should begin with a slash but contain no other slashes, spaces or non-alphanumeric characters besides - or _. Thus, for internal.example.com/codescene, CODESCENE_PATH_PREFIX would be set to /codescene.

Database for persisting System and Analysis Configurations

CodeScene comes with a built-in embedded database (H2) that persists all the data in a single file. Usually, database access is not a performance bottleneck (it might become an issue if you use a shared file system).

This default option is the recommended choice.

It’s important to backup the database regularly. See DB Backup for description of various backup options

Set up an External Database

CodeScene also supports external database engines mysql (minimum version: 5.7.x or 8.0.x) and mariadb (minimum version: 10.4.6). This is an option for organizations that want a more fine-grained control over operations and backups.

Note: you can also migrate your existing CodeScene data from H2 to MySQL.

Add if not exist to your mysql or mariadb server configuration the following

[mysqld]
lower_case_table_names = 1
sql_generate_invisible_primary_key = 0 #only for mysql >= 8.0.30

First, you need to create a new database user and the database:

  • create user: MySQL 5.7 , MySQL 8.0 , MariaDB 

    CREATE USER 'sa'@'localhost' IDENTIFIED BY '';

  • create database: MySQL 5.7 , MySQL 8.0 , MariaDB 

    CREATE DATABASE codescene CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

  • grant privileges:

    GRANT ALL PRIVILEGES ON codescene.* TO 'sa'@'localhost';

If needed, you can then update your CodeScene DB configuration as shown in the DB Configuration section.

Secure DB connections

For secure connections, your database server must support TLS 1.1 or later. Configuring your MySQL or MariaDB server to support secure DB connections is vendor-dependent.

See relevant info for:

For Azure MySQL server, you can find relevant info here:

Check also CODESCENE_DB_SSL_MODE in the next section.

DB Configuration

CodeScene is using the following environment variables when connecting to the database - you can tweak them to connect to an external database (instead of the default H2 db).

DB Backup

It’s important to backup the database regularly. All CodeScene’s configuration (projects, global configuration, etc.) is stored in the database and you will have to re-create it from scratch if the database is corrupted.

The exact mechanism for performing backups depends on the deployment option you’ve chosen:

  • for H2 the built-in embedded database (H2)

    • CodeScene creates a DB backup file on each start-up in db-backups folder located the same location like the original DB file. The backup file is compressed using zip and the file name contains the timestamp when the backup was performed. Please copy this DB backup file to your persistent backup location as needed. See also Define the Root Paths for Persistent Data.

    • The automatic backup on start-up can be disabled by setting the environment variable CODESCENE_DB_BACKUP_ON_STARTUP=false

    • The automatic backup on start-up will be skiped if the number of backups per day is excedeed, the default value is 20 and can be changed using environment variable CODESCENE_DB_BACKUP_MAX_PER_DAY

    • An on-demand backup can be performed by calling the api end point /maintenance/db-backup .

    • CodeScene checks periodically (default is each 4h) the number of backup files present and performs a clean up as follows

      • all db backups newer then 10 days will be kept, you can define your own value by setting the environment variable CODESCENE_DB_BACKUP_MAX_DAYS_TO_KEEP

      • from the db backup files older then value of CODESCENE_DB_BACKUP_MAX_DAYS_TO_KEEP only newest 10 backups will be kept, you can define your own value by setting the environment variable CODESCENE_DB_BACKUP_MAX_FILES

  • for MySQL follow the instructions from MySQL Backup .

  • for MariaDB follow the instructions from MariaDB Backup .

A simple Cron job might work just fine. For the “public cloud” option, it’s usually better to use a managed solution, e.g. Azure Backup .

(External) DB Performance

The default H2 database is stored in a file on a local disk that is supposed to be fast.

Normally, CodeScene does not impose a heavy load on the database. Using a slower database will generally not affect the duration of analyses. The user interface, and in particular the main projects dashboard page, may appear slower in some cases.

If you use an external database like MySQL make sure that network latency isn’t high (tens of milliseconds). It’s recommended to host your database in the same datacenter as CodeScene. If you use managed DB services like Amazon RDS or Azure Database, make sure to deploy them in the same region.

Configure additional users

You are granted administration privileges each time you login with your license credentials (note that you can do that at any time, for example to administrate users).

You can add new users and assign them roles in the global configuration. Users and Roles describes this in greater detail.