# Domain Settings Guide

This guide explains how to configure custom domains and upgrade SSL certificates for the AGENTIC STAR marketplace edition.

## Default State

AGENTIC STAR ships with **HTTPS using self-signed certificates**.

### LoadBalancer Endpoint Configuration

Four LoadBalancer endpoints are assigned.

| Service Name           | Purpose                |
| ---------------------- | ---------------------- |
| `ingress-nginx-front`  | Main application       |
| `ingress-nginx-admin`  | Admin console          |
| `ingress-nginx-auth`   | Authentication service |
| `ingress-nginx-extapi` | External API           |

A single self-signed certificate covering all 4 endpoints as SANs is applied.

#### Endpoint Format Differs by Cloud

The value shown in the `EXTERNAL-IP` column of `kubectl get svc -n ingress-nginx` differs depending on the cloud you use.

| Cloud     | EXTERNAL-IP value | DNS record | Notes                                                                  |
| --------- | ----------------- | ---------- | ---------------------------------------------------------------------- |
| **Azure** | Static IP address | A record   | Standard Load Balancer Public IP (static by default)                   |
| **AWS**   | ELB DNS name      | CNAME      | Network Load Balancer DNS name (`xxxxxxxx.elb.<region>.amazonaws.com`) |
| **GCP**   | Static IP address | A record   | Direct IP for both global and regional load balancers                  |

> **Why AWS Does Not Show an IP**
>
> AWS Network Load Balancers use ENIs spanning multiple Availability Zones, so they do not have fixed IPs — AWS may change the underlying IPs over time. Always reference NLBs by their ELB DNS name. This guide uses terms like "IP1–IP4" and "IP address"; on AWS, read these as "ELB DNS name."

### Default Limitations

| Item                            | Status                                                          |
| ------------------------------- | --------------------------------------------------------------- |
| HTTPS communication             | Works (browser certificate warning shown)                       |
| OAuth / Keycloak authentication | Works                                                           |
| Secure Cookie                   | Works                                                           |
| WebAuthn (Passkey)              | **Not available** (available after proper domain configuration) |

> **danger**
>
> Running in production with self-signed certificates carries the following risks:
>
> - User confusion from browser certificate warnings
> - Inability to detect man-in-the-middle attacks (users develop a habit of ignoring warnings)
> - WebAuthn (Passkey) functionality unavailable
> - Some client SDKs may refuse connections
>
> **Always configure a proper domain and valid SSL certificate before making the service publicly available.**

## Choosing an SSL Configuration Method

After obtaining your domain, upgrade to a valid SSL certificate using one of the following methods.

| Method                          | SSL Termination | Certificate Management | Recommended For                                       |
| ------------------------------- | --------------- | ---------------------- | ----------------------------------------------------- |
| **CDN / Load Balancer**         | Cloud service   | Managed by cloud       | When WAF / DDoS protection or CDN features are needed |
| **External Certificate**        | Ingress         | Manual                 | When you already have a certificate                   |
| **Let's Encrypt Auto-Issuance** | Ingress         | cert-manager           | When you want free, auto-renewed certificates         |

## Common Upgrade Steps

The following common steps are required regardless of which method you choose.

### 1. Obtain a Domain and Configure DNS Records

Prepare domains for each service and configure DNS records to point to each LoadBalancer endpoint. The record type differs by cloud.

| Example Domain      | Target Service         | Purpose                |
| ------------------- | ---------------------- | ---------------------- |
| `chat.example.com`  | `ingress-nginx-front`  | Main application       |
| `admin.example.com` | `ingress-nginx-admin`  | Admin console          |
| `auth.example.com`  | `ingress-nginx-auth`   | Authentication service |
| `api.example.com`   | `ingress-nginx-extapi` | External API           |

#### DNS Configuration by Cloud

**Azure / GCP (A records pointing to IPs):**

```text
chat.example.com.   IN  A  <IP1>
admin.example.com.  IN  A  <IP2>
auth.example.com.   IN  A  <IP3>
api.example.com.    IN  A  <IP4>
```

**AWS (CNAME records pointing to ELB DNS names):**

```text
chat.example.com.   IN  CNAME  <ELB DNS name of ingress-nginx-front>
admin.example.com.  IN  CNAME  <ELB DNS name of ingress-nginx-admin>
auth.example.com.   IN  CNAME  <ELB DNS name of ingress-nginx-auth>
api.example.com.    IN  CNAME  <ELB DNS name of ingress-nginx-extapi>
```

> **note**
>
> The endpoints for each Service (IPs on Azure/GCP, ELB DNS names on AWS) remain unchanged after domain configuration. The DNS records simply point to the corresponding endpoints; routing does not change.
>
> On the AWS Marketplace edition, NLB IPs may change on AWS's side, so you must always use CNAME records pointing to the ELB DNS names. Registering the NLB IPs directly in A records will cause connectivity issues when the IPs change. If you use Route 53, you can also use Alias records (A record alias) to target the NLB.

### 2. Check the Current Helm Chart Version

```bash
HELM_DRIVER=configmap helm list -A
```

Check each service's chart name and version (e.g., `librechat-1.1.3`, `agenticai-admin-1.1.3`, etc.). The following steps use the same chart version.

### 3. Add the Helm Repository

```bash
helm repo add agenticai-prod https://agtstrmarketplacecharts.blob.core.windows.net/charts
helm repo update
```

### 4. Update Domain / URL Settings

Change the IP-based URLs in each service's ConfigMap to domain-based URLs using `helm upgrade --reuse-values --set`. The `--reuse-values` flag preserves all existing settings, and only the values specified with `--set` are overwritten.

> **caution**
>
> Specify the same chart version that is currently deployed, as confirmed in step 2.

**Main Application (librechat):**

```bash
HELM_DRIVER=configmap helm upgrade librechat agenticai-prod/librechat \
  --version 1.1.3 \
  --reuse-values \
  --set appConfig.domainClient="https://chat.example.com" \
  --set appConfig.domainServer="https://chat.example.com" \
  --set appConfig.authBaseUrl="https://auth.example.com" \
  -n agentic-star-front
```

**Admin Console (agenticai-admin):**

```bash
HELM_DRIVER=configmap helm upgrade agenticai-admin agenticai-prod/agenticai-admin \
  --version 1.1.3 \
  --reuse-values \
  --set env.AFD_CHATBOARD_ADMIN_DOMAIN="admin.example.com" \
  --set env.AFD_CHATBOARD_FRONT_AUTH_DOMAIN="auth.example.com\,chat.example.com" \
  --set env.ALLOWED_ORIGINS="https://auth.example.com\,https://admin.example.com" \
  --set env.CHATBOARD_FRONT_DOMAIN="chat.example.com" \
  -n agentic-star-admin
```

**Authentication Service (librechat-auth):**

```bash
HELM_DRIVER=configmap helm upgrade librechat-auth agenticai-prod/librechat-auth \
  --version 1.1.3 \
  --reuse-values \
  --set env.ADMIN_CONSOLE_URL="https://admin.example.com" \
  --set env.ALLOWED_ORIGINS="https://chat.example.com\,https://auth.example.com" \
  --set env.ALLOWED_REDIRECT_URIS="https://chat.example.com/oauth/librechat/callback" \
  --set env.APP_URL="https://auth.example.com" \
  --set env.LIBRECHAT_URL="https://chat.example.com" \
  --set env.NEXT_PUBLIC_APP_URL="https://auth.example.com" \
  --set env.WEBAUTHN_ORIGIN="https://auth.example.com" \
  --set env.WEBAUTHN_RP_ID="auth.example.com" \
  -n librechat-auth
```

> **note**
>
> - `agenticai-extapi` (agenticai-extapi-service) uses only cluster-internal URLs, so changes are typically not required
> - When specifying values containing commas with `--set`, escape them with `\,`

### 5. Configure SSL Certificates

Proceed to one of the methods below.

## Method 1: CDN / Load Balancer

Perform SSL termination at the cloud service and disable TLS on the Ingress side.

```text
User → HTTPS (443) → CDN / Load Balancer (SSL termination) → HTTP (80) → Ingress Controller → Pod
```

### Deploy with Helm

Run the following commands for each service.

```bash
# Main application
HELM_DRIVER=configmap helm upgrade librechat agenticai-prod/librechat \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=false \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/ssl-redirect"="false" \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/force-ssl-redirect"="false" \
  -n agentic-star-front

# Admin console
HELM_DRIVER=configmap helm upgrade agenticai-admin agenticai-prod/agenticai-admin \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=false \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/ssl-redirect"="false" \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/force-ssl-redirect"="false" \
  -n agentic-star-admin

# Authentication service
HELM_DRIVER=configmap helm upgrade librechat-auth agenticai-prod/librechat-auth \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=false \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/ssl-redirect"="false" \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/force-ssl-redirect"="false" \
  -n librechat-auth

# External API
HELM_DRIVER=configmap helm upgrade agenticai-extapi agenticai-prod/agenticai-extapi \
  --version 1.0.0 --reuse-values \
  --set global.ingress.tls.enabled=false \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/ssl-redirect"="false" \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/force-ssl-redirect"="false" \
  -n agenticai-extapi-service
```

### Cloud-Specific Configuration

#### Azure: Front Door

Azure Front Door provides security through WAF and SSL/TLS via Azure-managed certificates.

Key steps:

1. Create a DNS zone and configure NS delegation
2. Create an AFD profile and WAF policy
3. Register custom domains and issue certificates
4. Register AKS Ingress IPs in origin groups
5. Configure routing rules to associate domains with origins
6. Update NSG rules (allow access only from AFD)
7. Update Ingress / Helm settings

#### AWS: CloudFront + NLB

On the AWS Marketplace edition, LoadBalancers are provisioned as NLBs, so we recommend configuring CloudFront origins to **point directly at the NLB DNS names**. NLB IPs may change on AWS's side, which makes the conventional pattern of registering NLB IPs in an ALB target group unstable.

1. Issue a certificate with ACM (AWS Certificate Manager) — certificates for CloudFront must be issued in **us-east-1**
2. Create a CloudFront distribution and set each Service's **NLB DNS name** as an origin (4 origins, one per service)
3. Use behaviors to route requests to the appropriate origin by host or path
4. In Route 53, point each custom domain at the CloudFront distribution domain via **CNAME** (or Alias record)
5. Restrict NLB security groups so they only accept traffic from the CloudFront managed Prefix List (`com.amazonaws.global.cloudfront.origin-facing`)

> **tip**
>
> If you prefer to avoid additional components, you can also place Route 53 directly in front of the NLBs without CloudFront. In that case, terminate SSL at the Ingress or via a TLS listener on the NLB (see "Method 2: External Certificate" or "Method 3: Let's Encrypt Auto-Issuance" below).

> **caution**
>
> A configuration with an ALB in between (using AWS Load Balancer Controller with IP target type) is technically possible, but stacking an NLB and ALB increases operational complexity. The CloudFront → NLB direct configuration above is recommended.

#### GCP: Cloud Load Balancing

1. Create a Google-managed SSL certificate
2. Create an external HTTPS load balancer
3. Register Ingress IPs in backend services
4. Configure DNS in Cloud DNS

## Method 2: External Certificate

Use an externally issued certificate with Ingress.

```text
User → HTTPS (443) → Ingress Controller (SSL termination / valid certificate) → HTTP → Pod
```

### Steps

#### 1. Register the Certificate as a Kubernetes Secret

Delete the existing self-signed certificate Secrets and replace them with valid certificate Secrets.

```bash
# Delete existing self-signed certificate Secrets (from all 5 Namespaces)
kubectl delete secret selfsigned-tls-cert -n agentic-star-front
kubectl delete secret selfsigned-tls-cert -n agentic-star-admin
kubectl delete secret selfsigned-tls-cert -n librechat-auth
kubectl delete secret selfsigned-tls-cert -n agenticai-extapi-service
kubectl delete secret selfsigned-tls-cert -n ingress-nginx

# Create valid certificate Secrets (in all 5 Namespaces)
for ns in agentic-star-front agentic-star-admin librechat-auth agenticai-extapi-service ingress-nginx; do
  kubectl create secret tls app-tls-cert \
    --cert=tls.crt --key=tls.key \
    -n $ns
done
```

> **note**
>
> The Secret in the `ingress-nginx` Namespace is used by the Ingress Controller's `default-ssl-certificate`. Update `controller.extraArgs.default-ssl-certificate` in `ingress-nginx-values.yaml` to `"ingress-nginx/app-tls-cert"` and redeploy the Ingress Controller.

#### 2. Deploy with Helm

Switch the TLS Secret name to the valid certificate for each service.

```bash
# Main application
HELM_DRIVER=configmap helm upgrade librechat agenticai-prod/librechat \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=true \
  --set global.ingress.tls.secretName="app-tls-cert" \
  --set global.ingress.tls.useCertManager=false \
  -n agentic-star-front

# Admin console
HELM_DRIVER=configmap helm upgrade agenticai-admin agenticai-prod/agenticai-admin \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=true \
  --set global.ingress.tls.secretName="app-tls-cert" \
  --set global.ingress.tls.useCertManager=false \
  -n agentic-star-admin

# Authentication service
HELM_DRIVER=configmap helm upgrade librechat-auth agenticai-prod/librechat-auth \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=true \
  --set global.ingress.tls.secretName="app-tls-cert" \
  --set global.ingress.tls.useCertManager=false \
  -n librechat-auth

# External API
HELM_DRIVER=configmap helm upgrade agenticai-extapi agenticai-prod/agenticai-extapi \
  --version 1.0.0 --reuse-values \
  --set global.ingress.tls.enabled=true \
  --set global.ingress.tls.secretName="app-tls-cert" \
  --set global.ingress.tls.useCertManager=false \
  -n agenticai-extapi-service
```

## Method 3: Let's Encrypt Auto-Issuance

Use cert-manager to automatically issue and renew Let's Encrypt certificates.

```text
User → HTTPS (443) → Ingress Controller (SSL termination / Let's Encrypt certificate) → HTTP → Pod
```

### Prerequisites

- cert-manager is installed (included with AGENTIC STAR)

- DNS for your domains is pointing to the LoadBalancer endpoints

  <!-- -->

  - Azure / GCP: A records pointing to the Ingress IPs
  - AWS: CNAME records pointing to the Ingress ELB DNS names

- Port 80 access is allowed (for ACME HTTP-01 challenges)

### Steps

#### 1. Create a ClusterIssuer

Edit the included `cluster-issuer.yaml` to set your email address, then apply it.

```bash
kubectl apply -f cluster-issuer.yaml
```

#### 2. Deploy with Helm

Enable cert-manager integration for each service.

```bash
# Main application
HELM_DRIVER=configmap helm upgrade librechat agenticai-prod/librechat \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=true \
  --set global.ingress.tls.secretName="app-tls-cert" \
  --set global.ingress.tls.useCertManager=true \
  --set global.ingress.tls.clusterIssuer="letsencrypt-prod" \
  -n agentic-star-front

# Admin console
HELM_DRIVER=configmap helm upgrade agenticai-admin agenticai-prod/agenticai-admin \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=true \
  --set global.ingress.tls.secretName="app-tls-cert" \
  --set global.ingress.tls.useCertManager=true \
  --set global.ingress.tls.clusterIssuer="letsencrypt-prod" \
  -n agentic-star-admin

# Authentication service
HELM_DRIVER=configmap helm upgrade librechat-auth agenticai-prod/librechat-auth \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=true \
  --set global.ingress.tls.secretName="app-tls-cert" \
  --set global.ingress.tls.useCertManager=true \
  --set global.ingress.tls.clusterIssuer="letsencrypt-prod" \
  -n librechat-auth

# External API
HELM_DRIVER=configmap helm upgrade agenticai-extapi agenticai-prod/agenticai-extapi \
  --version 1.0.0 --reuse-values \
  --set global.ingress.tls.enabled=true \
  --set global.ingress.tls.secretName="app-tls-cert" \
  --set global.ingress.tls.useCertManager=true \
  --set global.ingress.tls.clusterIssuer="letsencrypt-prod" \
  -n agenticai-extapi-service
```

> **note**
>
> cert-manager will automatically create a new certificate using the Secret name (`app-tls-cert`). Manually delete the original self-signed certificate Secrets (`selfsigned-tls-cert`) from each Namespace. Also update the Ingress Controller's `default-ssl-certificate` to `"ingress-nginx/app-tls-cert"`.

#### 3. Verify Certificate Issuance

```bash
kubectl get certificate -n <namespace>
kubectl describe certificate <cert-name> -n <namespace>
```

## Troubleshooting

### Cannot Log In with the Default Self-Signed Certificate

```bash
# Check Ingress status
kubectl describe ingress <name> -n <namespace>

# Verify TLS Secret exists
kubectl get secret selfsigned-tls-cert -n <namespace>

# Check Ingress Controller logs
kubectl logs -n ingress-nginx deployment/ingress-nginx-controller
```

**Common causes:**

- Browser certificate exception has not been accepted
- TLS Secret does not exist in the correct Namespace
- Ingress Controller is restarting

### Check Currently Applied TLS Settings

```bash
HELM_DRIVER=configmap helm get values <release-name> -n <namespace>
```

### Certificate Not Issued (Let's Encrypt)

```bash
# Check Certificate resource status
kubectl describe certificate <name> -n <namespace>

# Check cert-manager logs
kubectl logs -n cert-manager deployment/cert-manager

# Check ACME verification status with Challenge resources
kubectl get challenge -n <namespace>
```

**Common causes:**

- DNS is not pointing to the Ingress endpoint (A record to the IP for Azure/GCP, CNAME to the ELB DNS name for AWS)
- Port 80 access is blocked
- ClusterIssuer email address is invalid

### Not Redirecting to HTTPS

```bash
HELM_DRIVER=configmap helm get values <release-name> -n <namespace>
```

Check that `nginx.ingress.kubernetes.io/ssl-redirect` is set to `"true"`.
