Skip to main content

CodeTogether Live On-Premises Installation via Docker

Before You Begin​

  • CodeTogether Live requires secure HTTPS connections. Docker allows for two options regarding SSL – decide between running with SSL serviced directly from inside the container, or using Nginx or Apache outside of the container.
  • You need SSL certificates for each domain on which the CodeTogether services will be exposed.
  • If requesting a license for multi-server deployment, include the externally accessible HTTPS URL for the CodeTogether Locator (details below).

The instructions below cover both single and multi-server deployments with additional configuration instructions for multi-server roles.

Multi-Server Deployment Prerequisites

As of CodeTogether Live 2022.1, you can optionally deploy multiple CodeTogether servers on-premises. Benefits of a multi-server deployment include service redundancy, scalability through distributed workloads, and lower latency with regional deployments—see Multi-Server On-Premises Deployment for additional details.

A multi-server deployment comprises the following containers:

  • Locator – A single instance that manages load balancing or regional assignments to edge servers.
  • Edge Servers – One or more, based on your needs. These are the servers which manage CodeTogether Live sessions.
  • Database – Co-located with the Locator to persist metrics, audit logs, etc. Can be MySQL or PostgreSQL.

The same CodeTogether image is used for locators and edge servers – the container functions as a locator or an edge server based on configuration parameters.

Installation via Docker​

1. Download Docker​

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

2. Log In to CodeTogether's Docker Registry​

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

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

$ docker login -u "<username>" hub.edge.codetogether.com
Password:
Login Succeeded

3. Pull the CodeTogether Image​

After logging in, pull the latest version of the CodeTogether image.

$ docker pull hub.edge.codetogether.com/latest/codetogether
Using default tag: latest
latest: Pulling from latest/codetogether
(snip): Pull complete
Digest: sha256:(snip)
Status: Downloaded newer image for hub.edge.codetogether.com/latest/codetogether:latest
hub.edge.codetogether.com/latest/codetogether:latest

If you’d like to pull a specific version of CodeTogether, use the following command instead.

$ docker pull hub.edge.codetogether.com/releases/codetogether:<version>

To get a list of versions available, see the CodeTogether Edge Server Technical Notes.

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
hub.edge.codetogether.com/latest/codetogether  latest (snip)    2 minutes ago

5. Set up SSL Settings​

CodeTogether Live 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 yourcert.com.crt and yourcert.com.key files next to this configuration file.

# enable SSL
listen 1443 ssl;
# add your certificates
ssl_certificate /etc/nginx/ssl/yourcert.com.crt;
ssl_certificate_key /etc/nginx/ssl/yourcert.com.key;
# add your TLS and/or ciphering settings
ssl_protocols TLSv1.3 TLSv1.2;
caution

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.

When configuring your server, it is important for the SSL configuration that the backend is referenced by a hostname that matches the SSL certificate. Connecting to the backend simply by IP address will not work reliably from clients. In addition, connections by a simple http:// connection will not work as expected as the Browser client requires access to secure crypto-APIs which are not available in insecure web connections.

6. Create the Dockerfile with License Details and Additional Configuration​

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

Audio/Video Configuration (CodeTogether 5.0+)​

You must explicitly set the CT_AV_ENABLED variable to indicate if you would like to enable A/V support in your deployment. You can set it to either "true" or "false" based on your preference.

If ENV CT_AV_ENABLED "false", no additional settings need to be configured and A/V sessions will be disabled in your deployment. You are free to turn this setting on at any time.

If ENV CT_AV_ENABLED "true":

  • Ensure that A/V ports 10000/udp and 4443/tcp are mapped to and exposed outside the container.
  • Set the value for CT_AV_LAN_IP based on the following scenarios:
    • If the ports are exposed on the same IP address as CT_SERVER_URL’s host DNS resolution, you can omit CT_AV_LAN_IP or explicitly set it to "auto".
    • If the server provided by CT_SERVER_URL is not DNS resolvable – for instance, like being in your home network – you must set CT_AV_LAN_IP to that private IP.
    • If you are mapping ports 10000/udp and 4443/tcp to an IP that’s different from the server specified by CT_SERVER_URL, you must set CT_AV_LAN_IP to that IP.
info

CodeTogether's audio, video and screen sharing capabilities use the WebRTC framework, requiring both TCP and UDP communication to function. If your firewall does not allow incoming UDP traffic, you may need to set up a TURN server on your intranet. See A/V with a TURN Server for details.

SSO Integration​

If you'd like to set up SSO integration, see Single Sign-On (SSO) Support for configuration steps and additional environment variables that must be configured in the container.

StatsD/Prometheus Integration (CodeTogether 4.2+)​

If you’d like CodeTogether Live metrics to be exposed to an external monitoring platform, see CodeTogether Edge Server Technical Notes for additional environment variables that must be configured in the container.

License details will be given to you by your CodeTogether 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.

caution

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.

FROM hub.edge.codetogether.com/latest/codetogether

COPY --chown=codetogether:0 yourcert.com.crt /etc/nginx/ssl
COPY --chown=codetogether:0 yourcert.com.key /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_TRUST_ALL_CERTS true

ENV CT_LICENSEE "Your name"
ENV CT_MAXCONNECTIONS 250
ENV CT_EXPIRATION 2020/12/30
ENV CT_LOCATOR none
ENV CT_SIGNATURE your-signature

# Provide the externally accessible HTTPS URL for this server
ENV CT_SERVER_URL https://yourcodetogetherserver.company.com

# A/V configuration
ENV CT_AV_ENABLED "true"
ENV CT_AV_LAN_IP "auto"
note

If you’re working with a specific version of CodeTogether Live, use the following FROM instruction instead:

FROM hub.edge.codetogether.com/releases/codetogether:<version>

Multi-server: Additional Configuration​

info
  • A dedicated Dockerfile for the locator server and each individual edge server is required – you will build and run each of these.
  • Unlike single server deployments, StatsD/Prometheus integration should be configured in the Dashboard, not in the Dockerfile.

Setting CT_LOCATOR:​

When requesting a license for multi-server deployment, you must send CodeTogether the externally accessible HTTPS URL for the CodeTogether Locator. Your license block will use this URL as the value for the CT_LOCATOR variable, and as part of license enforcement, this variable must be set for the locator server and each edge server. In the locator’s Dockerfile, CT_LOCATOR should have the same value as CT_SERVER_URL, and not none as you can see in the sample above.

Setting CT_REGION:​

If you wish to assign different edge servers based on IP ranges (regional deployment), add a region name variable to each edge server’s Dockerfile. In the Dashboard, you can then use CIDRs to map IPs to specific edge servers. For example:

ENV CT_REGION North

Creating locator-config.json:​

See Setting up a Database for Multi-Server Deployments to set up a database and create a locator-config.json file which you will use in the subsequent steps.

7. Build the Docker Image​

Updating?

If you are updating your CodeTogether installation, ensure you stop and remove the existing CodeTogether container using the following command, before building the new version of the image.

$ docker container rm -f codetogether

Build the local Docker image using the Dockerfile. The trailing dot (.) is a path to the build context, which is the location of the Dockerfile and any other files required for building the image. The dot (.) represents the current directory, meaning that the Dockerfile is located in the current directory.

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

Multi-Server: Building Edge and Locator Containers​

You need to build the images for the locator and each edge server. If you happen to be testing this on the same machine, use appropriate tags to differentiate between the containers and the the -f argument to point to the correct Dockerfile. For example:

$ docker build -t "codetogether:local" -f Dockerfile .
$ docker build -t "edge1:local" -f Dockerfile.edge1 .

8. Start the Docker Container​

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

Map A/V Ports

If using A/V support, ensure you map ports 4443 and 10000 to the container, omit from the run command otherwise.

note

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

We recommend mounting the area in which CodeTogether stores its logs on a stable volume. This ensures that historic information including usage data, session audits and server logs are not lost across CodeTogether updates or restarts.

$ docker run \
--name codetogether \
-v ctlogs:/var/log/codetogether \
-p 80:1080 -p 443:1443 -p 10000:10000/udp -p 4443:4443 \
-d codetogether:local

If you used a codetogether.config file for license details, start with this command instead:

$ docker run \
--name codetogether \
--mount type=bind,source=/absolute/path/to/codetogether.config,target=/opt/codetogether/.bashrc \
-v ctlogs:/var/log/codetogether \
-p 80:1080 -p 443:1443 -p 10000:10000/udp -p 4443:4443 \
-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
0.0.0.0:80->1080/tcp, 0.0.0.0:443->1443/tcp codetogether

Multi-Server: Confirming Edge Servers are Ready and Connected to Locator​

In a multi-server setup, execute the following command to check the edge server logs:

$ docker logs -f edge1
INFO CodeTogether 2022.1.1238 Edge Server ready; connected to Locator for assignments
[INFO] CodeTogether started successfully!

Optionally, execute the following command to check the locator server log where, you should see a similar entry for each edge server that connects.

$ docker logs -f codetogether

Checking Status and Further Configuration in the On-premises Dashboard​

If you open your Dashboard https://CT_LOCATOR/dashboard, you will notice a section displaying the health of each edge server. If you set up multiple servers for a regional deployment, go to the Regions page to set up the IP ranges that should map to each edge server. You can also use the Advanced page to configure metrics integration. See Using the On-Premises Dashboard for details.

10. Download Preconfigured Clients for CodeTogether​

caution

We do not recommend using the publicly available versions of the CodeTogether plugins/extension within your IDEs. The versions available on your on-premises server are preconfigured to connect to your server. This also ensures the plugins/extensions used are compatible with the version of CodeTogether you have deployed.

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.

This manual plugin/extension installation is only required the first time. When you update your on-premises distribution to a newer version of CodeTogether, the IDE plugins/extensions will be updated automatically. In Visual Studio Code, the extension will be updated when you start the IDE. For IntelliJ and Eclipse, you can use Help > Check for Updates and/or the plugin will be automatically updated based on your IDE’s update settings.

Appendix: Sample CodeTogether Nginx Configuration​

If you are configuring an Nginx Web server as a front-end layer or a load-balancing component, you may want to use this sample Nginx configuration as a template for your CodeTogether environment. Make the TLS changes that fit your web environment.

As a best practice, we strongly recommend you place this Nginx configuration in a separate file, at one of these locations (locations vary depending on your Nginx version and/or OS distro).

/etc/nginx/conf.d/codetogether.conf

/etc/nginx/sites-enabled/codetogether.conf

caution

Do not modify your master Nginx configuration at /etc/nginx/nginx.conf

Confirm that your Nginx configuration is validated as OK, and be sure to restart your Nginx web server to ensure these configuration changes are applied:

# nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
# service nginx restart
#
# The server that is running the CodeTogether container
# - Port 1080 is the HTTP default one in the container - unless it has been overridden in the running Dockerfile.
# - Make sure you have ports opened in your firewall between your Nginx servers and the running CodeTogether container.
#
upstream codetogether {
  server server2.mycompany.com:1080;
}
#
# The Nginx front end server that is proxying requests to the CodeTogether container (Docker)
#
server {
  listen 443 ssl http2;
  server_name server1.mycompany.com;
  ssl_protocols TLSv1.3 TLSv1.2;
  ssl_certificate /etc/nginx/ssl/server1-mycompany-com.crt;
  ssl_certificate_key /etc/nginx/ssl/server1-mycompany-com.key;
  # Setting Proxy headers at 'server' context so they can be used by this Nginx instance
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header Host $http_host;
  location / {
    proxy_redirect off;
    # Setting same Proxy headers at 'location' context so they can be properly 'forwarded' to the CodeTogether container
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $http_host;
    proxy_set_header X-NginX-Proxy true;
    proxy_http_version 1.1;
    # This is mandatory to support CodeTogether socket connections
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_pass http://codetogether;
  }