Skip to main content

CodeTogether On-Premises Installation via Kubernetes

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.

note

To deploy the latest version of CodeTogether, use the codetogether-intel and codetogether-collab Helm Charts and containers. For legacy versions, additional Helm charts are available.

Using Kubernetes (k8s) is the recommended approach for larger scale deployments in an enterprise as it is easier to provide seamless upgrades and high availability via replicas. During upgrades of the Intel container, Kubernetes will manage the upgrade by running a new instance while maintaining the old version until the transition is complete..

Install Prerequisites​

Step 1. Set Up Cassandra​

To start with Cassandra, you are first required to activate the Bitnami chart repository from which the core Cassandra configuration will come from:

helm repo add bitnami https://charts.bitnami.com/bitnami

Once the repository is added, you will then create the values file to start Cassandra. By default, this can be quite a simple file similar to the following. Adjust the password as desired.

cassandra-values.yaml​

global:
  storageClass: do-block-storage
dbUser:
  user: cassandra
  password: cassandra

Once the file is ready, start up Cassandra in k8s. 

helm install codetogether-cassandra bitnami/cassandra -f cassandra-values.yaml

To monitor the status of the pod coming up, you can check status using this command.

kubectl exec -it --namespace default $(kubectl get pods --namespace default -l app.kubernetes.io/name=cassandra,app.kubernetes.io/instance=codetogether-cassandra -o jsonpath='{.items[0].metadata.name}') -- nodetool status

Once the pod is up and running, you need to connect to Cassandra to enable the keyspace that CodeTogether Intel will be using on the server. To connect into Cassandra, you will use a one-time use Cassandra client that allows you to run the cli to create the keyspaces. The pod will be automatically removed after execution. 

kubectl run --namespace default codetogether-cassandra-client --rm --tty -i --restart='Never' --image docker.io/bitnami/cassandra:4.1.3-debian-11-r71 -- bash

Once you are in the Cassandra cli, you connect in using a command similar to the following and create the keyspace using a regular replication strategy. 

I have no name!@codetogether-cassandra-client:/$ cqlsh -u cassandra -p cassandra codetogether-cassandra.default.svc.cluster.local

Warning: Using a password on the command line interface can be insecure.
Recommendation: use the credentials file to securely provide the password.


Connected to cassandra at hq-cassandra.default.svc.cluster.local:9042
[cqlsh 6.1.0 | Cassandra 4.1.3 | CQL spec 3.4.6 | Native protocol v5]
Use HELP for help.
cassandra@cqlsh> CREATE KEYSPACE hq WITH replication = {'class':'SimpleStrategy', 'replication_factor' : 1};
cassandra@cqlsh> exit

Step 2. Set Up External DNS (Optional)​

Depending on your Kubernetes configuration, you may want to activate External DNS updating to your DNS service to facilitate automatic provisioning of DNS names. If you use a different system or prefer to map IP addresses manually, this step can be skipped.

provider: <provider>

digitalocean:
  apiToken: <api-token>

interval: "1m"

policy: sync

To start External DNS which is also included in the Bitnami repository, simply run the following command:

helm install external-dns bitnami/external-dns -f externaldns-values.yaml

To monitor the startup of the External DNS pod you can run this command:

kubectl --namespace=default get pods -l "app.kubernetes.io/name=external-dns,app.kubernetes.io/instance=external-dns"

Step 3. Enable Nginx Ingress (Optional)​

Depending on your Kubernetes configuration, you can decide what sort of Ingress controller you use. The example values file shared below assumes using the Nginx ingress, which if not active can be enabled via first adding the chart repository:

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx

Next, install the Nginx ingress in the Kubernetes pod.

helm install nginx-ingress ingress-nginx/ingress-nginx --set controller.publishService.enabled=true

Install the Intel Container via Kubernetes​

Step 1. Configure TLS for Secure Communication​

To secure CodeTogether, you can add a secret that contains your TLS (Transport Layer Security) private key and certificate:

kubectl create secret tls codetogether-intel-tls --key <your-private-key-filename> --cert <your-certificate-filename>
IMPORTANT

When adding a TLS secret, ensure the SSL certificate is fully rooted and includes intermediate certificates in the ssl-bundle.crt file. Given the variety of clients and IDEs used with CodeTogether, a trusted certificate simplifies client-side configuration. Using an internal or non-rooted certificate will require additional, complex configuration within IDE clients to trust the certificate.

Step 2. Configure the Values for CodeTogether Intel​

To access the full values.yaml template file, download the latest version from GitHub. The following section will highlight section by section the values that should be configured as part of running via Kubernetes.

Download the latest version of the file from:

https://github.com/CodeTogether-Inc/CodeTogether-Deployment/blob/main/charts/intel/values.yaml

Set Up Registry Access​

Provide your credentials to the CodeTogether Intel docker registry:

imageCredentials:
  enabled: true
  registry: hub.edge.codetogether.com
  username: "my-customer-username"
  password: "my-customer-password"
  email: unused

Configure Server URL​

Set the URL that will be used to connect to the server:

codetogether:
  url: https://<server-fqdn>

Configure Intel Services​

Provide the CodeTogether Intel container configuration properties. The following are the initial values that typically need to be configured with the exception of single sign-on values covered below.

cthq.properties​
hqproperties:
  hq.sso... (see below)
  hq.db.type: CASSANDRA
  hq.secret: SECRET1
  hq.encryption.secret: SECRET2
  hq.base.url: https://<server-fqdn>
  hq.cassandra.db.name: insights
  hq.cassandra.db.port: 9042
  hq.cassandra.db.host: codetogether-cassandra.default.svc.cluster.local
  hq.sso.redirect.uri: https://<server-fqdn>/api/v1/auth/sso/success/insights
  hq.cassandra.db.password: cassandra
  hq.cassandra.db.username: cassandra
  # Default value is datacenter1, uncomment if using a custom name
  # hq.cassandra.db.localdatacenter: datacenter1

If you followed the instructions above, the Cassandra database will be under the codetogether-cassandra name in the k8s Pod. If the name was changed, make sure to update it above.

Regarding the SSO configuration (hq.sso…), the following are the different keys that should be present to connect to your sign-on service.

hqproperties: (continues from above)
  # Values that must be present for configuring SSO
  hq.sso.client.id: <clientid>
  hq.sso.client.secret: <clientsecret>
  hq.sso.redirect.uri: https://<server-fqdn>/api/v1/auth/sso/success/insights
  # Generic single sign-on configuration --
  hq.sso.client.issuer.url: https://<sso-fqdn>/<path>/
  # hq.sso.name.attr: [preferred_username|name]
  # Example for connecting with Keycloak --
  # hq.sso.client.issuer.url: https://<keycloak-fqdn>/realms/<realm>
  # Example for connecting to GitHub --
  # hq.sso.provider: github
  # hq.sso.auth.uri: https://github.com/login/oauth/authorize
  # hq.sso.token.uri: https://github.com/login/oauth/access_token
  # hq.sso.info.uri: https://api.github.com/user
  # hq.sso.jwt.set.uri: https://token.actions.githubusercontent.com/.well-known/jwks
  # hq.sso.logout.uri: https://github.com/logout
  # hq.sso.name.attr: name
  hq.collab.url: ${pointing to collab url}
  hq.collab.secret: must match CT_INTEL_SECRET

The majority of SSO providers require only a few settings to get connected. The issuer URL tells CodeTogether how to talk to the server, the client ID and secret are configured within the single sign-on service and authorize our backend to talk to the server. CodeTogether normally 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.

Configure Ingress​

Configure the desired Ingress configuration. There are three key options, using className to determine which to use. In a default configuration, the already available ingress is likely the right option to choose and would look like the following. Note that you need to register the SSL certificate earlier.

ingress:
  enabled: true
  tls:
    secretName: codetogether-intel-tls

The other values in the file likely do not require modification but can be changed based on your specific use cases or tuning as required.

Step 3. Start the CodeTogether Intel Backend​

Before actually launching the CodeTogether backend, you first need to register the Helm chart repository for CodeTogether. Run the following command:

helm repo add codetogether https://helm.codetogether.io

Once the repository is set up, you can now start up the CodeTogether Intel pod by running the following command:

helm install codetogether-intel codetogether/codetogether-intel -f values.yaml

Finally, you can monitor the pod to confirm it is up and running by using the following command:

kubectl --namespace=default get pods -l "app.kubernetes.io/name=codetogether-intel,app.kubernetes.io/instance=codetogether-intel"

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.

Continue next with Setting Up Your Project.

Step 4. Applying Updates​

To apply updates to CodeTogether, you can use the following command. Kubernetes will take into account starting up the new instance before spinning down the old, minimizing any downtime for users.

helm repo update
helm upgrade codetogether-intel codetogether/codetogether-intel -f values.yaml

Install the Collab Container via Kubernetes​

Step 1. Configure TLS for Secure Communication​

To secure CodeTogether, you can add a secret that contains your TLS (Transport Layer Security) private key and certificate:

kubectl create secret tls codetogether-tls --key <your-private-key-filename> --cert <your-certificate-filename>
IMPORTANT

When adding a TLS secret, ensure the SSL certificate is fully rooted and includes intermediate certificates in the ssl-bundle.crt file. Given the variety of clients and IDEs used with CodeTogether, a trusted certificate simplifies client-side configuration. Using an internal or non-rooted certificate will require additional, complex configuration within IDE clients to trust the certificate.

Step 2. Configure the Values for CodeTogether Collab​

To access the full values.yaml template file, download the latest version from GitHub.

Download the latest version of the file from: https://github.com/CodeTogether-Inc/CodeTogether-Deployment/blob/main/charts/collab/values.yaml

The following sections highlight the values that should be configured as part of running via Kubernetes.

Set Up Registry Access​​

Provide your credentials to the CodeTogether Collab docker registry:

imageCredentials:
  enabled: false
  registry: hub.edge.codetogether.com
  username: "my-customer-username"
  password: "my-customer-password"
  email: unused

Connect to Intel​

Configure the Collab service to connect to the Intel container for authentication and licensing.

intel:
  url: "https://your-intel-server"
 # Same secret value as the hq.collab.secret property in the cthq.properties file
 # configured for the Intel server.
 secret: "SECRET"

Configure Server URL​​

Set the URL that will be used to connect to the server:

codetogether:
 url: https://<server-fqdn>

Configure Ingress​

Configure the desired Ingress configuration. There are three key options, using className to determine which to use. In a default configuration, the already available ingress is likely the right option to choose and would look like the following. Note that you need to register the SSL certificate earlier.

ingress:
  enabled: true
  tls:
    secretName: codetogether-tls

The other values in the file likely do not require modification but can be changed based on your specific use cases or tuning as required.

Step 3. Start the CodeTogether Collab Backend​​

You should have registered the Help chart repository when you set up the Intel container. Now you can now start up the CodeTogether Collab pod by running the following command:

helm install codetogether-collab -f codetogether-values.yaml ./codetogether-collab

Finally, you can monitor the pod to confirm it is up and running by using the following command:

kubectl --namespace=default get pods -l "app.kubernetes.io/name=codetogether-collab,app.kubernetes.io/instance=codetogether-collab"

Step 4. Applying Updates​

To apply updates to the CodeTogether Collab container, you can use the following command. Kubernetes will take into account starting up the new instance before spinning down the old, minimizing any downtime for users.

helm upgrade codetogether-collab -f codetogether-values.yaml ./codetogether-collab