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, ingress class), 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 Kubernetes ingress, and the TLS certificate before anything else can be configured.

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 your cluster's ingress load balancer.
3. Arrange TLS termination at the ingress — either by providing a pre-created TLS Secret from an existing certificate, or by configuring cert-manager to issue one. No certificate is passed to the CodeTogether server; TLS terminates at the cluster boundary.
4. If the cluster has no default ingress class, identify the class name to use.

What to send back:

Value	Description
Service hostname	The agreed hostname (without https://), such as ctai.yourcompany.com
TLS Secret name	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	Required only if the cluster has no default ingress class

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:

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:

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:

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:

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:

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.