Skip to main content

CodeTogether On-Premises Installation via Docker Compose

To use the full CodeTogether suite, pull down and configure an Intel container for the Intelligence Suite and a Collab container for Live Collaboration.

Deployment Architecture​

CodeTogether is designed as a modular, containerized system to ensure scalability, flexibility, and security in an on-premises environment. It consists of three core containers: Cassandra, Intel, and Collab.

  • Apache Cassandra—A highly scalable database engine that supports backend operations of the Intelligence Suite.
  • CodeTogether Intel—The central backend, processing and managing data across the platform. It interfaces directly with Cassandra for efficient data storage and retrieval.
  • CodeTogether Collab—Enables real-time collaboration features and seamlessly connects to the Intel container.

To ensure secure communication between the Intel and Collab containers, a shared secret—defined by you—is used for authentication.

Beyond the backend servers, CodeTogether includes an IDE plugin that integrates seamlessly with Visual Studio, VS Code, Eclipse, IntelliJ, and other supported IDEs based on these. This plugin enables real-time collaboration and workflow intelligence by securely connecting to the Collab and Intel containers, ensuring a seamless developer experience.

For authentication and access control, the Intel container serves as the central hub for Single Sign-On (SSO) activities. All IDE clients and the Collab container route authentication requests through Intel, which validates credentials, enforces security policies, and manages session lifecycles. This ensures a unified, secure authentication flow across the platform while maintaining compliance with enterprise security standards.

Installing the Intel and Collab Containers via Docker Compose​

Docker Compose allows you to deploy Cassandra, the Intel backend and Collab backend from a simple configuration file. This is the recommended installation flow to follow for simple installations or deployments where high availability isn’t a requirement.

Step 1. Log In to Private Registry​

To get started, you’ll first need to log in to the private Docker Registry containing the CodeTogether Intel and Collab docker images.

 $ docker login -u <USER> -p <PASSWORD> hub.edge.codetogether.com

Step 2. Retrieve the Docker Compose Template​

Now that you are logged in, you need to download a set of files that serve as a template for running CodeTogether via Docker Compose.

info

You can find the full docker-compose template files in our GitHub repository: CodeTogether Deployment - Compose Folder

Be sure to download all 6 files to get started.

You have two options:

  1. Download the files manually from the GitHub link above.
  2. Or, clone the full repository for easier updates later.

Step 3. Configure Environment Variables​

Before starting the containers, you’ll need to configure your environment variables.

First, rename the existing .env-template file to .env and update the following values:

# CodeTogether – Environment Template
# -------------------------------------------------------------------------
# INSTRUCTIONS:
# 1. Copy this file to `.env` in the same directory as `compose.yaml`.
# 2. Replace the placeholder values on the right with your actual
#    deployment info.
# 3. Place all SSL certificates and Diffie-Hellman parameters in
#   `nginx/ssl/`
# 4. Configure your SSO provider in the `cthq.properties` file.
# 5. Run `docker-compose up -d` to start the containers.
# -------------------------------------------------------------------------
# Environment Variables (All required unless stated otherwise)
# -------------------------------------------------------------------------
# COLLAB_FQDN        → Public hostname for the Collab service
#                      (e.g., collab.example.com)
#
# INTEL_FQDN         → Public hostname for the Intel service
#                      (e.g., intel.example.com)
#
# INTEL_SECRET       → Shared secret for authentication between services.
#                      Use a strong, private value.
#
# SSL_COLLAB_CERT    → SSL certificate filename for the Collab virtual host
#                      (e.g., ssl-collab.crt)
#
# SSL_COLLAB_KEY     → Private key filename for the Collab certificate
#                      (e.g., ssl-collab.key)
#
# SSL_INTEL_CERT     → SSL certificate filename for the Intel virtual host
#                      (e.g., ssl-intel.crt)
#
# SSL_INTEL_KEY      → Private key filename for the Intel certificate
#                      (e.g., ssl-intel.key)
#
# DHPARAM_PEM        → Diffie-Hellman parameters file
#                      (e.g., dhparam.pem)
#-------------------------------------------------------------------------

COLLAB_FQDN=collab.example.com
INTEL_FQDN=intel.example.com
INTEL_SECRET=super-secret-string

SSL_COLLAB_CERT=ssl-collab.crt
SSL_COLLAB_KEY=ssl-collab.key

SSL_INTEL_CERT=ssl-intel.crt
SSL_INTEL_KEY=ssl-intel.key

DHPARAM_PEM=dhparam.pem

# Uncomment the following lines to enable Gen AI bundled integration
#CT_HQ_OLLAMA_AI_URL=http://codetogether-llm:8000
#CT_HQ_OLLAMA_AI_MODEL_NAME=gemma3:1b
note
  • Docker Compose reads hostnames directly from the .env file.
  • Each service requires its own hostname and certificate.
  • Docker Compose mounts these certificates into Nginx based on the filenames in .env, so ensure each FQDN points to its corresponding files.

Step 4. Configure Intel Properties​

There are certain configuration settings for the CodeTogether Intelligence Suite that must be enabled at provisioning time. Review the template cthq.properties file you accessed earlier and apply changes as required for your deployment. Client Id and Client secret are the SSO settings are not managed via the .env file when using compose.

note

All of these secret values—whether INTEL_SECRET, SSL certificate paths or SSO credentials—are pulled from .env file, which takes priority over the cthq.properties.

cthq.properties​

# Variables below are injected from the `.env` file
hq.base.url=https://${INTEL_FQDN}
hq.collab.url=https://${COLLAB_FQDN}
hq.collab.secret=${INTEL_SECRET}

# Fill in values specific to your deployment

# If you want to run with multiple SSO providers, add their names separated with commas
hq.sso.tenants=github

# GitHub SSO
hq.sso.github.provider=github
hq.sso.github.label=GitHub
hq.sso.github.client.id=<github_client_id>
hq.sso.github.client.secret=<github_client_secret>
hq.sso.github.redirect.uri=https://${INTEL_FQDN}/api/v1/auth/sso/success/insights
hq.sso.github.auth.uri=https://github.com/login/oauth/authorize
hq.sso.github.token.uri=https://github.com/login/oauth/access_token
hq.sso.github.info.uri=https://api.github.com/user
hq.sso.github.jwt.set.uri=https://token.actions.githubusercontent.com/.well-known/jwks
hq.sso.github.logout.uri=https://github.com/logout

# These values do not need to be changed, though secrets can be updated
hq.db.type=CASSANDRA
hq.cassandra.db.host=codetogether-cassandra
hq.cassandra.db.name=hq
hq.cassandra.db.port=9042
hq.cassandra.db.password=cassandra
hq.cassandra.db.username=cassandra
hq.encryption.secret=SECRET1
hq.secret=SECRET2

The majority of SSO providers require only a few settings to get connected. The issuer URL specifies how CodeTogether communicates with the authentication server. The client ID and secret are configured within the single sign-on service and authorize our backend to talk to the server. And finally, CodeTogether typically works well out of the box, but you can also set the primary name attribute to use for names in the system.

For GitHub, it can be configured using a different integration which provides added value. Most importantly, it allows CodeTogether to get all committer IDs for the users that are logging in, which eliminates extra steps requiring each end user to register their additional emails after login.

When in doubt, please contact your CodeTogether technical support representative for guidance on configuration of your specific SSO connection.

Step 5. Review Cassandra Supporting Files​

To deploy Cassandra, you can use the included configuration file without modification or if an advanced deployment, make adjustments.

By default, Cassandra will run using internal routing in Docker, such that the only box that will have access to the database is CodeTogether Intel.

The files used during invocation of Cassandra include:

  • cassandra-config.yaml—Contains a standard deployment of Cassandra for use within a Docker internal network.
  • cassandra-init.cql—Used by the custom startup script to ensure that the needed Keyspace for CodeTogether Intel is set up as part of provisioning the container.
  • cassandra-startup.sh—Replaces the default startup script of the Cassandra container to support automatic provisioning of the CodeTogether Intel keyspace.

Step 6. Adding SSL Certificates for NGINX​

To enable HTTPS in your deployment, you must provide SSL certificates for NGINX.

6.1. Obtain Certificates​

  1. Trusted CA
    • Get a cert from a recognized Certificate Authority (e.g., DigiCert, Let’s Encrypt, etc.).
    • Ensure your certificate’s Common Name (CN) or Subject Alternative Names (SANs) match the domain(s) you’ll use.
  2. Internal CA
    • If your organization has an internal PKI, request a certificate for your domain.
  3. Self-Signed (Testing)
    • Generate one with OpenSSL (not for production):
      openssl req -x509 -newkey rsa:4096 -keyout mycert.key -out mycert.crt -days 365 -nodes

6.2. Folder Placement​

Place your .crt, .key, and (optionally) dhparam.pem files in the same directory you mount into the NGINX container (commonly ./nginx/ssl). Make sure that the name of the files matches with what you have in your .env file.

Step 7. Start Containers​

Now that configuration files are ready and Nginx or your preferred reverse proxy is ready to service HTTPS requests, the servers can be started.

To begin, start by ensuring that the data directory is created and accessible. Adjust the path of the data directory to the folder you configured on step 4.

mkdir data

With that, the next step is to start the servers! The initial startup can take up to 2 to 3 minutes for the initial setup of the database and configuration. Once the first launch is completed, subsequent startups are significantly faster.

If you optionally want to also enable the bundled gen ai features, please review .env file and uncoment the CT_HQ_OLLAMA_AI_URL and CT_HQ_OLLAMA_AI_MODEL_NAME variables. This will enable the CodeTogether AI features in your deployment.

# not enaabled ai features
docker-compose up --pull always --wait
## Gen AI features enabled
docker-compose -f compose.yaml -f compose.ai.yaml up --pull always --wait

When the compose file is running, status updates will indicate the current state of deployment provisioning.

[+] Running 2/2
 ✔ cassandra Pulled                                                      0.4s
 ✔ codetogether-intel Pulled                                                0.6s
 ✔ codetogether-collab Pulled                                                0.8s
[+] Running 3/3
 ✔ Network codetogether_codetogethernet        Created                             0.1s
 ✔ Container codetogether-cassandra  Started                             0.1s
 ✔ Container codetogether-intel         Created                             0.0s
 ✔ Container codetogether-collab         Created                             0.0s

The first launch will stay in the Started state for Cassandra for about a minute as the initial database is set up and prepared for Intel.

 ✔ Container codetogether-cassandra  Healthy                             0.1s
 ✔ Container codetogether-intel         Started                             0.0s
 ✔ Container codetogether-collab        Started                             0.0s

Once Cassandra is ready, the Intel container will connect to Cassandra and set up the schema and initial database configuration. This step can take anywhere from a minute or two depending on the performance of the server box.

[+] Running 2/2
 ✔ cassandra Pulled                                                      0.4s
 ✔ codetogether-intel Pulled                                                0.6s
[+] Running 3/3
 ✔ Network codetogether_codetogethernet        Created                             0.1s
 ✔ Container codetogether-cassandra  Healthy                             0.1s
 ✔ Container codetogether-intel         Healthy                             0.0s

With that, you can now connect to your server!

Simply open your browser to https://<server-fqdn> and you’ll have an opportunity to log in via your single sign-on service and then proceed to provide your license file.

note

By default, each service listens on a fixed port inside the Compose network: Collab on 443 (HTTPS), Intel on 1080.

Continue next with Setting Up Your Project.

Step 8. Applying Updates​

When applying updates, use the up command with the following steps to pick up change to the cthq.properties files or pick up a new release of CodeTogether Intel.

docker-compose --no-deps --pull always --wait --force-recreate --build codetogether-intel

And, for Collab use the following:

docker-compose --no-deps --pull always --wait --force-recreate --build codetogether-collab

Using Docker Swarm Mode (Advanced)​

  1. If you are using Docker Swarm Mode (i.e., docker swarm init and docker stack deploy), you can create secrets similar to Kubernetes:
docker swarm init  # if not already done

docker secret create codetogether-tls.crt <your-certificate-filename>
docker secret create codetogether-tls.key <your-private-key-filename>
  1. Then reference them in your Swarm-compatible compose.yml (or stack.yml):
version: '3.7'
services:
  codetogether-nginx:
    image: nginx:latest
    ports:
      - "443:443"
    secrets:
      - codetogether-tls.crt
      - codetogether-tls.key
    # ...
secrets:
  codetogether-tls.crt:
    external: true
  codetogether-tls.key:
    external: true
  1. Within the container, Docker stores secrets under /run/secrets/, so your Nginx config would point to:
ssl_certificate     /run/secrets/codetogether-tls.crt;
ssl_certificate_key /run/secrets/codetogether-tls.key;
  1. Ensure your .crt file includes any intermediate certificates to prevent trust issues in CodeTogether’s IDE plugins.

Multi-Server Collaboration Deployment (Advanced)​

You can optionally deploy multiple CodeTogether Collab 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.

Contact our support team for assistance in setting up a multi-server deployment.

Audio/Video Configuration (Advanced)​

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

If your team already uses a platform like Slack, Teams, Google Meet, or Zoom for meetings and calls, we recommend leveraging those platforms for syncs.
If you do not have a preferred meeting tool, CodeTogether AV/Audio can be enabled, but note that this may require additional networking and firewall adjustments for UDP/TCP ports. 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 Configuring Audio/Video with a TURN Server for details.