Note: this is only an example how to run CodeScene behind an nginx proxy server. The image in the docker-codescene/ directory isn't maintained and you should use https://hub.docker.com/r/empear/codescene instead
This repository is an example of how to run CodeScene in a Docker instance behind an nginx reverse proxy. Even if you are not using Docker, the nginx configuration may be helpful for running CodeScene behind nginx.
docker-compose is used here to run two Docker containers, one running
nginx, the other with CodeScene itself. The CodeScene
docker image can also be used by itself to
run CodeScene directly.
This assumes that you have a working Docker installation.
Clone this repository and go to the top level directory.
git clone [email protected]:empear-analytics/docker-codescene-nginx-self-signed-ssl.git
cd docker-codescene-nginx-self-signed-ssl
Install certbot on the host according to the instructions found here: https://certbot.eff.org/lets-encrypt/ubuntubionic-other
Replace **domain_name** with your correct domain name in docker-nginx/nginx.conf
The complete code is available in the using_letsecrypt_ssl branch - see https://github.com/empear-analytics/docker-codescene-nginx-self-signed-ssl/commit/1db5245b40b10ee954e3b23261f40b6e29a4b665.
The reverse proxy using Nginx is built like this:
docker build -t reverseproxy docker-nginx/
The CodeScene image is available from Docker Hub.
If you want to use a specific version of CodeScene, you can add a tag in the docker-compose.yml:
image: empear/ubuntu-onprem:latest
Use docker-compose to start both instances:
docker-compose up -d
docker pull empear/ubuntu-onprem
docker run -i -t -p 3003 \
--name myname \
--mount type=bind,source=$PWD/docker-codescene/codescene,destination=/codescene \
empear/ubuntu-onprem
To connect to this instance:
docker exec -i -t myname /bin/bash
In both the reverse proxy setup and the standalone version, the
/codescene directory is bound to the
docker-codescene/codescene directory
in this repository. It contains two directories, repos and
analyses that can be used to store Git repositories and the analysis
result files that CodeScene produces. CodeScene's internal database is
also stored in /codescene, as well as a logfile. By using these directories, your data
will be persisted beyond the life of the Docker container.
Both the standalone command presented above and the docker-compose configuration use the bind mount type, for
ease of demonstration and debugging. In a production setting, Docker
volumes would be a better
solution.
The configuration presented here uses CodeScene's optional environment
variables CODESCENE_ANALYSIS_RESULTS_ROOT and
CODESCENE_CLONED_REPOSITORIES_ROOT. Their purpose is to ensure that users cannot create
repositories or store analysis results outside of the /codescene
directory. In conjunction with the CODESCENE_DB_PATH, we can be sure
that all the necessary data for persisting CodeScene is in a single,
easy-to-manage location. You can of course adjust these variables to
fit your specific needs.
Whether you use volumes or bind mounts, they must be passed to the Docker container at run time.
In the full reverse proxy setup using docker-compose, this is done
in the volumes stanza of the configuration. The
docker-compose.yml file in this repository
uses a Docker volume. To use a bind mount with docker-compose, or
for more detailed instructions, please refer to the documentation
here.
For the standalone configuration using a bind mount, see Run CodeScene by itself without the reverse proxy. To use a Docker volume in the standalone configuration, you must first create a volume:
docker volume create codescene-volume
This volume can then be referenced when starting the Docker container:
docker run -i -t -p 3003 \
--name myname \
--mount type=volume,source=codescene-volume,target=/codescene \
empear/ubuntu-onprem
Please refer to the Docker documentation for instructions on managing your Docker volumes.
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. Private repositories will require authentication
credentials, for which SSH keys are the recommended form. (For
example, including user credentials in Git URLs is inherently insecure
for requests of an open network.)
However, it can be tricky to communicate SSH credentials to a Docker container in a way that allows CodeScene to run unattended. Here are some options.
If you are comfortable using SSH keys that do not require a
passphrase, the simplest solution is to bind a valid .ssh directory
on the host system to /root/.ssh inside the container.
With the standalone setup, this would mean supplying an additional
--mount argument to docker run, something like:
--mount type=bind,source=$HOME/codescene-git-keys,destination=/root/.ssh
With the docker-compose solution, you would add the following to the
volumes section of the codescene stanza:
-"${HOME}/codescene-git-keys:/root/.ssh"
The directory at $HOME/codescene-git-keys could be tested outside of
Docker to be sure that the SSH connection works correctly. Make sure
that known_hosts contains a reference to the servers you will be
cloning from.
For greater security, if your remote code is on GitHub, the solution above could be combined with GitHub's deploy keys.
When running on a Linux host, it may be possible to forward the host
machine's ssh-agent to the Docker container by mounting a volume
corresponding to $SSH_AUTH_SOCK (untested):
--mount type=bind,source=$(dirname $SSH_AUTH_SOCK),destination=$(dirname $SSH_AUTH_SOCK) \
-e SSH_AUTH_SOCK=$SSH_AUTH_SOCK
You may be able to use a dedicated Docker container to store SSH credentials. See:
In some situations, it may be necessary to run CodeScene under a path
rather than at the root, eg. example.com/codescene rather than
simply example.com.
To do this, you can use the CODESCENE_PATH_PREFIX by setting it in
the Dockerfile. The prefix you add
there will be appended to all internal links in CodeScene.
If you were to use this solution in conjunction with nginx, your nginx.conf file might include something like this:
location /codescene {
return 302 /codescene/;
}
location /codescene/ {
proxy_pass http://codescene:3003/;
proxy_redirect http:// $scheme://$http_host/codescene;
}
To adjust memory settings for CodeScene running inside a container,
you can set the JAVA_OPTIONS environment variable.
To set "max heap" explicitly use -Xmx:
# with explicit max memory => notice that -m 500M is ignored
docker run -p3103:3003 -m 500M -e JAVA_OPTIONS='-Xmx300m' --name codescene empear/ubuntu-onprem
VM settings:
Max. Heap Size: 300.00M
Ergonomics Machine Class: server
Using VM: OpenJDK 64-Bit Server VM
To let the JVM autodetect default settings based on the container's memory:
# with experimental options and autodetection
# note that -XX:+UseCGroupMemoryLimitForHeap has been deprecated
docker run -p3103:3003 -m 500M -e \
JAVA_OPTIONS='-XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap -XX:MaxRAMFraction=2' \
--mount type=bind,source=$PWD/docker-codescene/codescene,destination=/codescene \
--name codescene empear/ubuntu-onprem
VM settings:
Max. Heap Size (Estimated): 222.50M
Ergonomics Machine Class: server
Using VM: OpenJDK 64-Bit Server VM
Please note, that
support for -XX:+UseCGroupMemoryLimitForHeap has been deprecated in JDK 10
and is no longer needed.
For more details, see Java inside docker: What you must know to not FAIL.
CodeScene, in general, uses default system's timezone.
In our docker image we set the default timezone explicitly to UTC via CODESCENE_TIMEZONE env var.
This can be overriden when the docker image is run:
docker run -p3003 -e CODESCENE_TIMEZONE='Europe/Stockholm' empear/ubuntu-onprem
Note that if you use docker-compose you need to leave out quotes:
environment:
- CODESCENE_TIMEZONE=Europe/Stockholm
Browse to https://localhost. In order to use CodeScene, you will need a license. You can get a license on the Empear Customer Portal. For more information about CodeScene, see the CodeScene Documentation.
To stop the reverse proxy:
docker-compose down
- The contents of this repository are provided under the MIT License. Other licences may apply to the software contained in the Docker images referenced here.
Get more details at codescene.io.