Skip to main content

CodeTogether HQ On-Premises Installation via Docker Compose

Docker Compose allows you to deploy both Cassandra and CodeTogether HQ’s 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 HQ docker image.

$ docker login hub.edge.codetogether.com
Username: <your-ct-registry-user>
Password: <your-ct-registry-password>
Login Succeeded

Step 2. Retrieve the Docker Compose Template​

Now that you are logged in, you need a few files that serve as a template for running via Docker Compose. You can access the full files from our GitHub repository at:

https://github.com/CodeTogether-Inc/CodeTogether-Deployment/tree/main/compose

Be sure to download all 6 files to get started. You can choose to clone the repository if it is simpler for your usage.

Step 3. Configure HQ Properties​

There are certain configuration settings for CodeTogether HQ that must be enabled at provisioning time. Review the template cthq.properties file you accessed earlier and apply changes as required for your deployment.

cthq.properties​

# Fill in values specific to your deployment
hq.base.url: https://<server-fqdn>
hq.sso.redirect.uri=https://<server-fqdn>/api/v1/auth/sso/success/insights
hq.sso.client.id=<clientid>
hq.sso.client.secret=<clientsecret>


# Generic single sign-on configuration
hq.sso.client.issuer.url=https://<sso-fqdn>/<path>/.well-known/openid-configuration
# 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


# 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 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. And finally, normally CodeTogether 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 4. Adjust Docker Compose File​

There are two key configuration files that you’ll need to adjust. The first to adjust is the Docker Compose configuration file. The following is an extract of the compose.yaml file that can be used for the deployment. You will find the full file in the directory you accessed in GitHub above.

compose.yaml​

services: 
  codetogether-hq:
    image: hub.edge.codetogether.com/releases/codetogether-hq:latest
    container_name: codetogether-hq
    environment:
      - CT_HQ_BASE_URL=https://<server-fqdn>
    networks:
      - hqnet
    volumes:
      - cthq.properties:/opt/codetogether/runtime/cthq.properties:ro
    ports:
      - "1080:1080"
    depends_on:
      cassandra:
        condition: service_healthy
    healthcheck:
      ... snip ...
  cassandra:
    image: cassandra:latest
    container_name: codetogether-cassandra
    networks:
      - hqnet
    environment:
      ... snip ...
    volumes:
      - ./cassandra-config.yaml:/etc/cassandra/cassandra.yaml
      - ./cassandra-init.cql:/scripts/init.sql
      - ./cassandra-startup.sh:/scripts/startup.sh
      - ./daata:/var/lib/cassandra
    entrypoint: /scripts/startup.sh
    healthcheck:
      ... snip ...
networks:
  hqnet:
    driver: bridge

The primary value that needs to change is https://<server-fqdn>. The first port number of 1080 is how the server will be exposed locally, from there, you will then use Nginx or another reverse proxy server to provide SSL services and expose CodeTogether HQ to your organization.

IMPORTANT

The data folder is where the primary persistent data is stored for CodeTogether HQ. It is highly recommended to have this folder in a directory that is backed up automatically. It is not required to stop the server to back up the data folder, though it is always recommended to schedule backups when server usage is lower or alternatively use a high availability storage service.

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 HQ.

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 HQ 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 HQ keyspace.

Step 6. Configure Nginx as a Reverse Proxy​

For performance reasons, it is recommended to use Nginx or another reverse proxy to handle the SSL encryption layer for requests to the server. This can be done via a Docker image though as many Docker hosts have multiple containers, this guide assumes that Nginx is running on the host level.

To start configuring Nginx, set up a new server configuration in the sites-enabled folder with content similar to the following. There is a full file available in the same compose folder of the CodeTogether Git repository.

codetogether.nginx​

server {
    server_name          <server-fqdn>;
    listen               443 ssl http2;


    # configure proxy buffer sizes
    proxy_buffer_size    128k;
    proxy_buffers        4 256k;


    # set up the SSL certificate
    ssl_certificate      <path-to-ssl-bundle.crt>;
    ssl_certificate_key  <path-to-ssl.key>;
    ssl_dhparam          <path-to-dhparam.pem>;
    ... snip ...


    # create the passthrough to the CodeTogether HQ container
    location / {


        # set passthru parameters for the CodeTogether HQ container
        ... snip ...
        proxy_set_header X-Real-IP $realIP;
        proxy_set_header X-Forwarded-For $forwardTo;
        proxy_set_header Host $reqHost;


        # set up the backend to service the HQ requests
        proxy_pass            http://127.0.0.1:1080;
        proxy_set_header      X-NginX-Proxy true;
        ... snip ...
    }
}

The four key values to set are the fully qualified domain name for the CodeTogether HQ and the path to the SSL configuration files.

IMPORTANT

Configuring the SSL certificate requires a trusted certificate that is fully rooted on the Internet including providing the intermediate certificates in the ssl-bundle.crt file. Given the variety of clients and IDEs used with CodeTogether HQ, this is important to simplify any client-side configuration required. Use of an internal certificate or a certificate that is not fully rooted will require additional complex configuration within IDE clients to trust the certificate.

Now that the Nginx configuration is ready, you can proceed to reload Nginx and activate the reverse proxy for the CodeTogether backend.

service nginx restart

Step 7. Start CodeTogether HQ​

Now that configuration files are ready and Nginx or your preferred reverse proxy is ready to service HTTPS requests, the server 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 server! 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.

docker-compose up --pull always --wait

When the compose file is running, you’ll get status reported indicating the state of the deployment provisioning.

[+] Running 2/2
 ✔ cassandra Pulled                                                      0.4s
 ✔ codetogether-hq Pulled                                                0.6s
[+] Running 3/3
 ✔ Network codetogether_hqnet        Created                             0.1s
 ✔ Container codetogether-cassandra  Started                             0.1s
 ✔ Container codetogether-hq         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 HQ.

 ✔ Container codetogether-cassandra  Healthy                             0.1s
 ✔ Container codetogether-hq         Started                             0.0s

Once Cassandra is ready, the HQ 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-hq Pulled                                                0.6s
[+] Running 3/3
 ✔ Network codetogether_hqnet        Created                             0.1s
 ✔ Container codetogether-cassandra  Healthy                             0.1s
 ✔ Container codetogether-hq         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.

Continue next with the Getting Started Guide which walks through setting up projects and the flow for end-users of CodeTogether HQ.

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 HQ.

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