Skip to main content

Prepare your environment

Four dependencies must be in place before CodeTogether AI is deployed. Each is usually owned by a different team, so this page is written to be handed out: assign each section to the right team, and collect the values they return for whoever runs the deployment.

  • Deployment: On-premises

The four dependency teams and the values each returns to the deployment team: Networking (hostname, TLS, and either an ingress class or a Gateway), Identity (provider type, client ID and secret, issuer URL), Mail (SMTP host, credentials, sender address), and DBA (database URL, credentials, schema names).

1 — Service hostname and TLS (Networking team)​

CodeTogether AI is reached by developers over HTTPS at a single agreed hostname. Your networking or platform team arranges the DNS record, the route into the cluster, and the TLS certificate before anything else can be configured.

There are two supported routes, and the choice belongs to this team. The chart can create an Ingress, or it can attach an HTTPRoute to a Gateway you already run — for a cluster that routes with Gateway API, such as one running NGINX Gateway Fabric. Pick whichever your cluster already uses; the values to send back differ, so decide this before filling in the table below.

What your team needs to do:

  1. Agree on a hostname with the deployment owner (for example, ctai.yourcompany.com). The hostname must be DNS-routable from developer workstations.
  2. Point that DNS name at the load balancer that fronts the cluster — your ingress controller's, or your Gateway's.
  3. Arrange TLS termination at that boundary. No certificate is passed to the CodeTogether server; TLS terminates before it. On the Ingress route, provide a pre-created TLS Secret from an existing certificate or configure cert-manager to issue one. On the Gateway route, the certificate belongs to the Gateway's own HTTPS listener — the chart does not create the Gateway, its listeners, or its certificate, so that listener must already serve this hostname.
  4. Identify the route itself:
    • Ingress — if the cluster has no default ingress class, identify the class name to use.
    • Gateway — identify the Gateway's name and namespace, and the name of the listener the HTTPRoute should attach to, which is the HTTPS listener holding the certificate. Confirm the cluster serves the Gateway API HTTPRoute resource; the install fails outright if it does not.

What to send back:

ValueDescription
Service hostnameThe agreed hostname (without https://), such as ctai.yourcompany.com
RouteWhich of the two the platform should use: an Ingress, or an HTTPRoute on an existing Gateway
TLS Secret nameIngress route only. The name of the TLS Secret to use at the ingress. For a pre-created certificate, this is the existing Secret name. For cert-manager, choose a name for the Secret cert-manager will create and write the issued certificate into (for example, ctai-tls).
Ingress class nameIngress route only, and only if the cluster has no default ingress class
Gateway name, namespace, and listener nameGateway route only. The Gateway the HTTPRoute attaches to, and which of its listeners.

On the Gateway route, confirm with the deployment team that the request body limit for this route allows uploads of at least 16 MB. Developer workstations upload telemetry in batches that exceed a gateway's typical 1 MB default, and a limit left at the default rejects them before they reach the server. The chart renders that limit for NGINX Gateway Fabric; on any other Gateway implementation, your team sets the equivalent itself.

2 — Single sign-on (Identity / IAM team)​

SSO is the only portal login method on-premises — no local password accounts are created. More than one SSO provider can be configured; supported types are keycloak, google, azure, okta, github, and custom.

The callback URL is built from the agreed service hostname. The path /api/v1/auth/sso/provider/callback is fixed — the word provider is a literal path segment, not a substitution. The URL is the same for every provider type and every provider number:

https://<your-hostname>/api/v1/auth/sso/provider/callback

What your team needs to do:

  1. Register CodeTogether AI as a confidential OAuth/OIDC application in your identity provider.
  2. Set the redirect/callback URI to that URL, using the hostname from section 1.
  3. Set the authorization grant type to authorization code flow.
  4. For OIDC providers (Keycloak, Azure, Okta, Google): note the issuer URL for your realm or tenant. For GitHub: note the standard GitHub OAuth endpoints listed in the properties template.
  5. Note the client ID and client secret the provider issues.

What to send back:

ValueDescription
Provider typeOne of: keycloak, google, azure, okta, github, custom
Client IDIssued by the identity provider
Client secretIssued by the identity provider
Issuer URLThe OIDC discovery root URL for your realm or tenant (OIDC providers only)
Display labelOptional. The label shown on the sign-in button; defaults to the provider name

Repeat for each provider if more than one is configured.

3 — Outbound email (Mail / IT team)​

CodeTogether AI sends transactional email for invitations and notifications. An SMTP relay and an approved sender address are required; the server validates that the relay is reachable on startup.

What your team needs to do:

  1. Identify an SMTP relay the cluster can reach (typically on port 587 with STARTTLS).
  2. Arrange an approved sender address, for example noreply@yourcompany.com.
  3. If the relay requires authentication, prepare or identify the account credentials.

What to send back:

ValueDescription
SMTP hostnameThe relay host reachable from the cluster
SMTP portTypically 587
Requires authtrue or false
SMTP usernameRequired when auth is enabled
SMTP passwordRequired when auth is enabled
Sender addressThe From: address for outbound mail
Sender display nameThe name shown alongside the sender address

4 — PostgreSQL database (DBA / Data Platform team)​

CodeTogether AI stores all its data in a PostgreSQL database that your team provisions. PostgreSQL 16 and later are supported, and any major in that range is equally supported — pick the one your team already operates. CodeTogether creates its own tables on first startup; the schemas are handed over empty.

Amazon Aurora PostgreSQL-Compatible works as the database — point the server at the cluster writer endpoint and use the same jdbc:postgresql:// URL shape. Aurora MySQL is not supported.

This database is the system of record for everything the platform captures and configures. As described in What does not leave your network, CodeTogether keeps no standing copy outside your perimeter — include this database in the same backup and recovery regime as your other production PostgreSQL databases before developer data starts flowing.

Database reachability from the cluster is the most common deployment blocker. Confirm connectivity before the Helm install begins.

What your team needs to do:

  1. Provision a dedicated PostgreSQL 16 or later database. The database must be reachable from the Kubernetes cluster on port 5432 (or your configured port).

  2. Create an application user. It needs LOGIN and no role attributes beyond it:

    CREATE ROLE ctai LOGIN PASSWORD '<password>';

    For the DBA weighing this: the role does not need SUPERUSER, and it must not be granted BYPASSRLS. CodeTogether relies on PostgreSQL row-level security to keep tenants apart, and the server binds the tenant it is serving to each transaction so that those policies return the right rows. A role that bypasses row-level security would turn that control off. Its access comes from owning the three schemas in step 3 and nothing wider.

  3. Create three schemas inside the database and grant the application user ownership:

    CREATE SCHEMA telemetry AUTHORIZATION ctai;
    CREATE SCHEMA platform AUTHORIZATION ctai;
    CREATE SCHEMA datamart AUTHORIZATION ctai;

    Leave the schemas empty — CodeTogether applies migrations on first boot and creates its own tables.

  4. Confirm from the cluster that the database host, port, and credentials are reachable.

Database connectivity is the most common deployment blocker

If the CodeTogether AI pod cannot reach the database on startup, the portal sign-in page loads but sign-in fails immediately with an error. Confirm reachability before the Helm install begins.

What to send back:

ValueDescription
Database URLJDBC URL: jdbc:postgresql://<host:port>/<database>
Database usernameThe application user
Database passwordThe password for that user
Telemetry schemaThe schema created in step 3 (default name: telemetry)
Platform schemaThe schema created in step 3 (default name: platform)
Datamart schemaThe schema created in step 3 (default name: datamart)