# Installation¶

CodeScene is quite flexible in that you can run it in any environment that meets the requirements specified in Configure your Environment.

In general, there are two popular options for hosting CodeScene:

• CodeScene inside a Docker container: We have an example on a docker file here, including an example on how to configure SSL. With this option, you could also deploy CodeScene to a private cloud (e.g. aws). In this case, you’d use the standalone CodeScene application.
• CodeScene hosted by Tomcat: Tomcat might be an option if you already host other applications on Tomcat.

## Run the Standalone CodeScene Application¶

The easiest way to get CodeScene up and running is 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.

### 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. In most cases 4G of RAM is more than enough, but if your codebase has large files (we mean really large, like +30,000 lines of code) you may need more memory to run the X-Ray analyses.

Note that Java’s virtual machine has a system dependent maximum that is typically lower than the total RAM available. That means you need to specify a higher threshold yourself when starting CodeScene. You do that by providing the -Xmx flag to java.

Here’s an example that shows how to allocate 10 gigabyte of RAM for CodeScene:

java -Xmx10G -jar codescene.standalone.jar


Note that the order of the arguments matter in this case.

### 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: Run CodeScene in Kubernetes¶

Finally – and entirely optional – the CodeScene standalone JAR could also be run on Kubernetes. This might be an option if your organization already uses Kubernetes as a container management tool.

Follow the instructions here to setup CodeScene on Kubernetes.

## Run CodeScene in Tomcat¶

CodeScene is delivered as a WAR file (Web application ARchive). We recommend that you deploy it using Tomcat (https://tomcat.apache.org/index.html).

### Specify a file folder for the database¶

CodeScene uses an embedded database. That means, you don’t have to install any database or drivers yourself. However, you need to specify a path to a file folder where CodeScene is allowed to store its database. Here’s how you configure Tomcat to do that:

1. Open the file context.xml located under the conf directory in your Tomcat installation.
2. Add an <Environment> tag to context.xml that specifies the path to a folder you want to use for the database (see the example below).
3. Save context.xml.

Here’s an example on how context.xml may look on a Windows installation (note that you need to modify the path to fit your environment):

<Context>
<WatchedResource>WEB-INF/web.xml</WatchedResource>
<WatchedResource>${catalina.base}/conf/web.xml</WatchedResource> <Environment name="empear.dbpath" value="C:\\some\\path\\to\\the\\database\\empear.codescene" type="java.lang.String"/> </Context>  In case you run on a Linux-based system, you just specify a different path format. For example: <Context> <WatchedResource>WEB-INF/web.xml</WatchedResource> <WatchedResource>${catalina.base}/conf/web.xml</WatchedResource>
<Environment name="empear.dbpath"
type="java.lang.String"/>
</Context>


Optionally, you can specify a custom username and password to access the database. By default, CodeScene uses the ‘sa’ user with an empty password.

Add empear.dbuser and empear.dbpassword to the Context environment properties to customize DB username/password.

### Deploy the codescene.war¶

Once Tomcat is up and running, with your modified context.xml, you just copy the codescene.war to the webapps folder in your Tomcat installation.

### Access CodeScene¶

By default, Tomcat will launch CodeScene on port 8080 and at the path /codescene/. If you’re logged in on the server, you access the application on http://localhost:8080/codescene/login. You should see the activation screen in your web browser (see Fig. 1).