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
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:
- Agree on a hostname with the deployment owner (for example,
ctai.yourcompany.com). The hostname must be DNS-routable from developer workstations. - Point that DNS name at the load balancer that fronts the cluster — your ingress controller's, or your Gateway's.
- 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.
- 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
HTTPRouteresource; the install fails outright if it does not.
What to send back:
| Value | Description |
|---|---|
| Service hostname | The agreed hostname (without https://), such as ctai.yourcompany.com |
| Route | Which of the two the platform should use: an Ingress, or an HTTPRoute on an existing Gateway |
| TLS Secret name | Ingress 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 name | Ingress route only, and only if the cluster has no default ingress class |
| Gateway name, namespace, and listener name | Gateway 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:
- Register CodeTogether AI as a confidential OAuth/OIDC application in your identity provider.
- Set the redirect/callback URI to that URL, using the hostname from section 1.
- Set the authorization grant type to authorization code flow.
- 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.
- Note the client ID and client secret the provider issues.
What to send back:
| Value | Description |
|---|---|
| Provider type | One of: keycloak, google, azure, okta, github, custom |
| Client ID | Issued by the identity provider |
| Client secret | Issued by the identity provider |
| Issuer URL | The OIDC discovery root URL for your realm or tenant (OIDC providers only) |
| Display label | Optional. 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:
- Identify an SMTP relay the cluster can reach (typically on port 587 with STARTTLS).
- Arrange an approved sender address, for example
noreply@yourcompany.com. - If the relay requires authentication, prepare or identify the account credentials.
What to send back:
| Value | Description |
|---|---|
| SMTP hostname | The relay host reachable from the cluster |
| SMTP port | Typically 587 |
| Requires auth | true or false |
| SMTP username | Required when auth is enabled |
| SMTP password | Required when auth is enabled |
| Sender address | The From: address for outbound mail |
| Sender display name | The 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:
-
Provision a dedicated PostgreSQL 16 or later database. The database must be reachable from the Kubernetes cluster on port 5432 (or your configured port).
-
Create an application user. It needs
LOGINand 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 grantedBYPASSRLS. 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. -
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.
-
Confirm from the cluster that the database host, port, and credentials are reachable.
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:
| Value | Description |
|---|---|
| Database URL | JDBC URL: jdbc:postgresql://<host:port>/<database> |
| Database username | The application user |
| Database password | The password for that user |
| Telemetry schema | The schema created in step 3 (default name: telemetry) |
| Platform schema | The schema created in step 3 (default name: platform) |
| Datamart schema | The schema created in step 3 (default name: datamart) |
Related
- Install with Helm — what the deployment team does with these values.
- Deploy CodeTogether AI on-premises — the deployment overview.