CodeTogether On-Premises Installation Guide

An On-Premises version of CodeTogether is available for Enterprise customers. This guide provides the key steps required to pull down and configure the CodeTogether On-Premises container using either Docker or Kubernetes. The container provides a full set of collaboration services, including tailored client plugins for the host IDEs. Due to security requirements, all communication in CodeTogether is required to be done via SSL.

This guide includes instructions on installing the CodeTogether container image from the Genuitec Private Docker Registry. The image is also available in the Red Hat Software Catalog.

  • To fetch the image from the Red Hat Catalog, complete the following instructions using your Red Hat Registry Service account credentials and corresponding image path as directed on this page.
  • To install into OpenShift, follow the instructions on this page.

Note: If you are using a load balancer, you will need to configure it to use the ctstickiness value as described here.

Should you need assistance following this installation guide, contact your Genuitec Sales representative or email For more information about the On-Premises version of CodeTogether, refer to the FAQ page. After installation is complete, refer to the CodeTogether Edge Server Technical Notes for helpful information.

Which containerization ecosystem do you use?

Installing with Docker

Docker allows for two options regarding SSL communication. One involves running with SSL directly serviced from inside the container and the other is using Nginx or Apache outside of the container.

The following instructions use the Genuitec Docker Registry. If you prefer to use the Red Hat Software Catalog instead, please substitute credentials and container path as mentioned here.

1. Download Docker

If not already installed, install Docker on the destination system from here.

2. Log In to Genuitec’s Docker Registry

Using your credentials provided by the Genuitec Sales team, log in to the Genuitec Docker Registry which is where you will receive the Docker image. Replace <userid> with your own login for the registry.

# docker login -u <userid>
Login Succeeded

3. Pull the CodeTogether Image

After logging in, now it is required to pull the latest version of the CodeTogether image.

# docker pull
Using default tag: latest
latest: Pulling from latest/codetogether
(snip): Pull complete
Digest: sha256:(snip)
Status: Downloaded newer image for

4. Verify the Image is Available

Now that the image has been retrieved, verify that the image is available.

# docker image ls
REPOSITORY                                     TAG    IMAGE ID  CREATED  latest (snip)    2 minutes ago

5. Setup SSL Settings

As mentioned in the introduction, using CodeTogether requires secure HTTPS connections. This can be done either by configuring a reverse proxy outside of the container, or enabling SSL inside the container itself. Skip this step if you will be using an SSL reverse proxy configured on your Docker host. Instead, enable SSL on the reverse proxy server of your choice ensuring that it is configured to support WebSockets.

To enable SSL, first create a codetogether-ssl-settings.conf file containing the names of the certificate files you will be using. In addition, place the and files next to this configuration file.

Note: If you are using a self-signed certificate or an internal certificate authority that is not externally rooted, ensure to use CT_TRUST_ALL_CERTS in the section below.

# enable SSL
listen 1443 ssl;
# add your certificates
ssl_certificate /etc/nginx/ssl/;
ssl_certificate_key /etc/nginx/ssl/;

6. Create the Dockerfile with License Details and Optional SSO Configuration

Create the Dockerfile file that will be used for this CodeTogether On-Premises deployment. Note that the CT_SERVER_URL must contain the HTTPS version of this service as CodeTogether will not run over HTTP.

Skip the items in RED if you are not using SSL inside the container.

The items in BLUE will be given to you by your Genuitec Sales representative and must be entered exactly as they are supplied with the identical punctuation and spacing. Be sure to use straight quotes around the CT_LICENSEE value.

Note: If you are using a self-signed certificate, set CT_TRUST_ALL_CERTS to true, regardless of whether you’re using an external certificate, or one from inside the container.

SSO Integration: If you’d like to set up SSO integration, please see this doc for configuration steps and additional environment variables that must be configured in the container.


# Include this section if using SSL from the container
#COPY --chown=codetogether:0 /etc/nginx/ssl
#COPY --chown=codetogether:0 /etc/nginx/ssl
#COPY --chown=codetogether:0 codetogether-ssl-settings.conf /etc/nginx/includes
#RUN chmod -R g+r /etc/nginx/ssl

# Uncomment if using a self-signed certificate

ENV CT_SIGNATURE your-signature

# Provide the external HTTPS URL that will be exposed


Additional Security Note: For additional security, instead of adding the CT_* environment variables to the Dockerfile, you can provide them via a dedicated mount point inside the container. In a secure location, create a file codetogether.config file with the same variables exported, for example:

export CT_LICENSEE="Your name"
export CT_EXPIRATION=2020/12/30
export CT_LOCATOR=none
export CT_SIGNATURE=your-signature

This file will be used in step #8 when starting the container.

7. Build the Docker Container

Build the local Docker container using the above Docker file. The trailing dot configures the directory where the container should be placed. An additional path may be provided.

# docker build -t "codetogether:local" .
Sending build context to Docker daemon 14.85kB
Step 1/13 : FROM
Successfully built (snip)
Successfully tagged codetogether:local

8. Start the Docker Container

Now that the container is ready, it is time to start it up! This will expose the configured ports on your container host. You can optionally only expose port 80 and/or 443, depending on which services you will be using.

Note: If using a self-signed certificate, keep -p 80:1080 present, and use the http:// URL to install the Eclipse plugin from Update Site to avoid issues with Java not recognizing the certificate.

# docker run --name codetogether -p 80:1080 -p 443:1443 -d codetogether:local

If you used the codetogether.config file for the environment variables, start with this command instead:

# docker run --name codetogether -v /absolute/path/to/codetogether.config:/opt/codetogether/.bashrc -p 80:1080 -p 443:1443 -d codetogether:local

9. Confirm Services are Ready

Now that the container is started, confirm that everything is running as expected.

# docker ps | grep codetogether
27c82c04db5c codetogether "/opt/codetogether/s..." 5 seconds ago Up 3 seconds>1080/tcp,>1443/tcp codetogether

10. Download Clients for CodeTogether

To begin using CodeTogether for collaborative sessions, download the corresponding pre-configured client for your IDE from the container’s “clients” download page. This page is available at CT_SERVER_URL/clients

That’s it!

If you need help getting going with CodeTogether:

Installing with Kubernetes

To use Kubernetes with CodeTogether, only a single container can be used per edge server. The following example YAML file includes guidance on how to configure the Ingress, Secrets, Service and Container that are required to run CodeTogether in K8s.

In the example below, the Ingress configuration and accompanying SSL certificate configuration may be skipped if this is being separately managed by your organization. As each organization’s usage of K8s may vary, no assumption has been made on the type of Ingress.

The following instructions use the Genuitec Docker Registry. If you prefer to use the Red Hat Software Catalog instead, please substitute credentials and container path as mentioned here.

1. Download the codetogether.yaml File

To get started with Kubernetes, download the codetogether.yaml file. This includes the required services & containers needed for CodeTogether to run via Kubernetes. View full source

Note: This file has been tested with Kubernetes 1.18, which is the same version used by RedHat’s OpenShift Container version 4.5. Version 1.18 included changes that may not be compatible with older versions of Kubernetes.

2. Set Up Credentials to CodeTogether Docker Hub

Run the following command to register the required credentials for Kubernetes to be able to download the required Docker image for the CodeTogether Edge Server.

# kubectl create secret docker-registry ctcreds ∖ ∖
    --docker-username=<your-name> ∖

3. Prepare SSL Certificate for Ingress

In a Bash or similar compatible shell, execute the following instructions to convert your SSL key and certificate for configuration for the secure Ingress to your container.

This step can be skipped if configuring Ingress separately.

# cat ssl.crt | base64 -w 0
# cat ssl.key | base64 -w 0

4. Update codetogether.yaml with CodeTogether License

In the Secret section in the YAML file, update with the exact values for the CodeTogether license as provided by your Genuitec Sales Representative.

5. Update codetogether.yaml with SSO Configuration (Optional)

If you’d like to set up SSO integration, please see this doc for configuration steps and additional variables that must be configured in the secret section of your YAML file.

6. Update codetogether.yaml with SSL Configuration

Using the base64 encoded Cert and Key calculated above, paste in the values into the Secret section of the YAML file. If preferred, the Secret can be configured from command line and does not require maintenance in the YAML file.

7. Load the Configuration into Kubernetes

To start using CodeTogether, activate the configuration in the local Kubernetes deployment, or configure on the remote server using the now-customized YAML file.

# kubectl create -f ./codetogether.yaml


If later you need to reconfigure the services, the simplest (though least efficient) way to do so is via the following:

# kubectl replace --force -f codetogether.yaml

8. Check IP Address of Ingress

Once starting the container, you can now verify the IP Address that the Ingress is configured to listen on using the following command.

# kubectl get ingress

9. Download Preconfigured Client(s)

If DNS is fully configured, it is now possible to connect to https://SERVERFQDN/clients and download the preconfigured clients to be used on your systems.

Note: If needed for local testing, the IP address returned above can be added to /etc/hosts mapping to the name configured in the certificate to allow testing to proceed.

That’s it!

If you need help getting going with CodeTogether:

Appendix A: Troubleshooting

CodeTogether should primarily be a black box, with automatic restart if you get a process failure; however, should diagnostics need to be performed, the core CodeTogether backend log file can be found at /var/log/codetogether/server.log and the Node process is provisioned at /opt/codetogether. Refer to the CodeTogether Edge Server Technical Notes for more information.

Accessing Log Files via HTTPS

To enable access to log files via HTTPS, please add the following variables to your Docker or Kubernetes configuration:

CT_LOGS_USER 'yourusername'
CT_LOGS_PASSWORD 'changethis'

Important: Be sure to use straight quotes around the username and password values.

The logs will then be accessible at CT_SERVER_URL/logs

Appendix B: Using a Load Balancer

All HTTP requests include a ctstickiness value. For IDE Clients, it is an HTTP Header; and for the Browser client, it is sent as a cookie. If using a load balancer to multiple edge servers (multiple active Docker instances), it is mandatory that the load balancer is configured to use this stickiness value to route connections from the same session to the same backend. Failure to use the stickiness value with multiple edge servers will result in errors, such as random users getting messages about sessions being unavailable.

Appendix C: codetogether.yaml

# Secret: CodeTogether License Values
# ========================================================================
apiVersion: v1
kind: Secret
  name: codetogether-license
  namespace: default
type: Opaque
  # Configure as needed for your deployment, should match your SSL certificate
  # Provided by your Genuitec Sales Representative
  # *values must match exactly
  CT_LICENSEE: "Your Company"
  CT_EXPIRATION: "2020/01/01"
  CT_SIGNATURE: "xXM3awzG...619bef4"
#======================================================================== # Secret: SSO Values (mandatory ONLY if you are using an SSO Provider) # ======================================================================== apiVersion: v1 kind: Secret metadata: name: codetogether-sso namespace: default type: Opaque stringData: # Configure as needed for your deployment, should match your SSO provider. Okta example below CT_SSO_PROVIDER: "OKTA" CT_SSO_AUTHORIZATION_ENDPT: "https://OKTA_DOMAIN/oauth2/default" CT_SSO_TOKEN_ENDPT: "https://OKTA_DOMAIN/oauth2/default/v1/token" CT_SSO_CLIENT_ID: "0oa..............5d6" CT_SSO_CLIENT_SECRET: "tsatRI..............................hTNw" --- # ======================================================================== # Secret: SSL Key and Certificate for SSL used by Ingress # ======================================================================== apiVersion: v1 kind: Secret metadata: name: codetogether-sslsecret namespace: default type: data: # value from "cat ssl.crt | base64 -w 0" tls.crt: "LS0tLS1CRUdJTi...UZJQ0FURS0tLS0tDQo=" # value from "cat ssl.key | base64 -w 0" tls.key: "LS0tLS1CRUdJTi...EUgS0VZLS0tLS0NCg==" --- # ======================================================================== # Ingress: Expose the HTTPS service to the network # ======================================================================== apiVersion: kind: Ingress metadata: name: codetogether spec: tls: - hosts: - SERVERFQDN secretName: codetogether-sslsecret rules: - host: SERVERFQDN http: paths: - path: / backend: serviceName: codetogether servicePort: 80 --- # ======================================================================== # Service: Map the HTTP port from the container # ======================================================================== apiVersion: v1 kind: Service metadata: name: codetogether labels: run: codetogether spec: ports: - port: 80 name: http targetPort: 1080 protocol: TCP selector: run: codetogether --- # ======================================================================== # Deployment: Configure the Container Deployment # ======================================================================== apiVersion: apps/v1 kind: Deployment metadata: name: codetogether namespace: default spec: selector: matchLabels: run: codetogether replicas: 1 template: metadata: labels: run: codetogether spec: containers: - name: codetogether image: imagePullPolicy: Always ports: - containerPort: 1080 env: - name: CT_LOCATOR value: "none" - name: CT_SERVER_URL valueFrom: secretKeyRef: name: codetogether-license key: CT_SERVER_URL - name: CT_TRUST_ALL_CERTS valueFrom: secretKeyRef: name: codetogether-license key: CT_TRUST_ALL_CERTS - name: CT_LICENSEE valueFrom: secretKeyRef: name: codetogether-license key: CT_LICENSEE - name: CT_MAXCONNECTIONS valueFrom: secretKeyRef: name: codetogether-license key: CT_MAXCONNECTIONS - name: CT_EXPIRATION valueFrom: secretKeyRef: name: codetogether-license key: CT_EXPIRATION - name: CT_SIGNATURE valueFrom: secretKeyRef: name: codetogether-license key: CT_SIGNATURE imagePullSecrets: - name: ctcreds