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 certificategemnasium.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:
- The volumes will be readonly by default
- 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.
See also
More info: http://www.projectatomic.io/blog/2015/06/using-volumes-with-docker-can-cause-problems-with-selinux/
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.