Run Gemnasium Enterprise

Gemnasium Enterprise is shipped as a single, all-included docker image.

Download Gemnasium Enterprise

In order to be able to download the Gemnasium Enterprise docker image, you must have an account on Docker Hub.

Send us the name of the account used and we will share the image with that user.

QuickStart: Docker Compose

The easiest and fastest way to start with Gemnasium Enterprise is to use Docker Compose. Docker Compose is a command line tool available for free (and most of the time bundled with your Docker installation). With a single file, the minimum configuration needed by Gemnasium Enterprise is available at a glance. It’s a good start, and the configuration should be tuned up with the rest of this page sections for production.

Use this docker-compose.yml file to get started:

version: "3"
services:
  gemnasium:
    container_name: gemnasium
    build: .
    image: gemnasium/enterprise
    restart: unless-stopped
    ports:
      - "80:80"   # api unsecure
      - "443:443"  # api ssl
    environment:
      - EXTERNAL_URL=https://gemnasium.localhost
      - SMTP_SERVICE_HOST
      - SMTP_SERVICE_PORT
      - SMTP_USER_NAME
      - SMTP_PASSWORD
      - SMTP_INSECURE
      - LICENSE_KEY
    volumes:
        - gemnasium-data:/var/opt/gemnasium/
volumes:
    gemnasium-data:
        driver: local

Note

The env vars must be declared in docker-compose.yml otherwise they are ignored (see Environment Variables.).

Preparing volumes

Persistent volumes are needed to store Gemnasium Enterprise data. The easiest way to get started, is to create local volumes on your server, but it can be any kind of volume supported by the docker engine.

See also

Please refer to Docker Volumes for more information: https://docs.docker.com/engine/tutorials/dockervolumes/

To create local volumes, on you server:

docker volume create --name gemnasium-data
docker volume create --name gemnasium-logs

Configuring SSL

A valid certificate must be provided to run Gemnasium Enterprise with the integrated SSL web server. If you don’t have a valid certificate available, you can obtain one from Let’s Encrypt for free. Please refer to the Let’s Encrypt Certificates section. If you don’t need Gemnasium Enterprise to serve content on https directly, go directly to the section: Running without SSL.

The certificate files must be named after the server name.

Example: for gemnasium.example.com, the certificate files must be named:

  • gemnasium.example.com.cert.pem for the certificate
  • gemnasium.example.com.key.pem for its private key

Gemnasium will look for 2 files with the .cert.pem and .key.pem suffix.

If the certificate has an intermediate chain, it must concatenated after the server certificate:

cat server.cert.pem ca-chain.cert.pem > gemnasium.example.com.cert.pem

The 2 files must be available in /etc/gemnasium/ssl, inside the container.

docker run --detach  \
  --name gemnasium \
  --restart always \
  -v /host/path/to/ssl/:/etc/gemnasium/ssl \
  -p 80:80 -p 443:443 \
  -e LICENSE_KEY=YOUR_OWN_LICENSE_KEY \
  -v gemnasium-data:/var/opt/gemnasium/ \
  -v gemnasium-logs:/var/log/ \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gemnasium/enterprise:latest

Note

Gemnasium needs the docker socket to be mounted only if the Reports feature is being used. If not, the line -v /var/run/docker.sock:/var/run/docker.sock can be safely removed.

This will pull and start Gemnasium Enterprise. Your instance will be available at https://gemnasium.example.com after a few seconds.

If you need to use a different port for https than 443, use the EXTERNAL_URL env var to specify the full URL of your Gemnasium Enterprise server, including the port used:

docker run --detach  \
  --name gemnasium \
  --restart always \
  -v /host/path/to/ssl/:/etc/gemnasium/ssl \
  -p 80:80 -p 8443:443 \
  -e LICENSE_KEY=YOUR_OWN_LICENSE_KEY \
  -e EXTERNAL_URL=https://gemnasium.example.com:8443/ \
  -v gemnasium-data:/var/opt/gemnasium/ \
  -v gemnasium-logs:/var/log/ \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gemnasium/enterprise:latest

and start browsing https://gemnasium.example.com:8443/

Running without SSL

Warning

We strongly discourage running Gemnasium Enterprise without any SSL termination. This section is present if you already have SSL terminations, like secured reverse-proxies, ssl appliances, etc.

Run the image:

docker run --detach  \
  --name gemnasium \
  --restart always \
  -e REDIRECT_HTTP_TO_HTTPS=false \
  -e EXTERNAL_URL=http://gemnasium.example.com/ \
  -p 80:80 \
  -e LICENSE_KEY=YOUR_OWN_LICENSE_KEY \
  -v gemnasium-data:/var/opt/gemnasium/ \
  -v gemnasium-logs:/var/log/ \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gemnasium/enterprise:latest

Note

The environment variable REDIRECT_HTTP_TO_HTTPS is true by default, and must be false in this case.

The service is available after a few seconds on the port 80 of your server. Use the EXTERNAL_URL variable to specify the full URL of your Gemnasium Enterprise server, including the port if necessary.

SELinux

Gemnasium Enterprise can’t be run directly on SELinux servers, because:

  1. The volumes will be readonly by default
  2. The docker socket will be restricted to the host

Use this command instead:

docker run --detach  \
  --name gemnasium \
  --restart always \
  -v /host/path/to/ssl/:/etc/gemnasium/ssl \
  -p 80:80 -p 443:443 \
  -e LICENSE_KEY=YOUR_OWN_LICENSE_KEY \
  -v gemnasium-data:/var/opt/gemnasium/:Z \
  -v gemnasium-logs:/var/log/:Z \
  -v /var/run/docker.sock:/var/run/docker.sock:Z \
  gemnasium/enterprise:latest

This will label the content inside the container with the exact MCS label that the container will run with, basically it runs chcon -Rt svirt_sandbox_file_t -l s0:c1,c2 /var/db where s0:c1,c2 differs for each container.

Please refer to this project to install the proper SELinux module to fix the second point.

Volumes

Gemnasium is storing data in two folders, which should be mounted as volumes

Local location Location in container Usage
gemnasium-data (volume) /var/opt/gemnasium Gemnasium data
gemnasium-logs (volume) /var/log Gemnasium logs

Gemnasium data is composed mostly of the PostgreSQL database files, but also nsq data, etc. These files must be backed up, refer to the Data Backup. section.

The /var/log contains the OS logs, and everything dedicated to gemnasium in /var/log/gemnasium.

Finally, as explained in the Configuring SSL section, your certificate and key must be available in the /etc/gemnasium/ssl folder.

Logging

By default, all logs will be sent to the standard output of the container (stdout), along with files in /var/log. This makes it easier to troubleshoot if needed.

Graylog

Gemnasium Enterprise can be configured to log to a distant Graylog server. To enable this feature, use the following environment variables:

Env variables Usage
GRAYLOG_SERVICE_HOST Graylog input hostname/ip
GRAYLOG_SERVICE_PORT Graylog input port

Example:

docker run --detach  \
  --name gemnasium \
  --restart always \
  -v /host/path/to/ssl/:/etc/gemnasium/ssl \
  -p 80:80 -p 443:443 \
  -v gemnasium-data:/var/opt/gemnasium/ \
  -v gemnasium-logs:/var/log/ \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GRAYLOG_SERVICE_HOST=logs.example.log
  -e GRAYLOG_SERVICE_PORT=1515
  gemnasium/enterprise:latest

Both variables must be set to activate the GELF output.

Obtaining a shell

The docker image doesn’t have a SSH server, because docker provides everything needed to get a shell console inside the container:

docker exec -it gemnasium bash

will create a new bash session, with the root user.

Warning

With great power comes great responsibility: as root, you can damage files inside the container, including your persisted data.