Skip to main content

New Page

Prerequisites

If you have activated the firewall on your service, ensure port 80 is open, or else certificate creation/renewal will fail.

Accessing the Configuration

Access the "Manage SSL Domains" option within the "Custom Domain Names" row located in the overview tab of the service dashboard.

image.png


This opens the `ModalConfigureSSL`  modal (for services) or `ModalConfigureDomain` modal (for CI/CD pipelines), which provides two methods for configuring custom domains:

---

## Method 1: Manual DNS Setup

From the modal, you can manage allowed domains for SSL. Type your domain and press Enter to add it to the list of authorized domains.

You will also need to create a DNS entry (from your registrar control panel) to point your domain to your service. The modal displays the required DNS records:

- **A record**: `@` → `<service IPv4>` (points your root domain to the service IP)
- **CNAME record**: `www` → `<service CNAME>` (preferred — won't change if your IP changes, e.g. after cloning/migrating to another provider)

Once added, verify your DNS entry is propagated with a tool like https://dnschecker.org/

Once propagated, SSL should work instantly on your service. The certificate will be automatically generated and renewed.

---

## Method 2: One-Click DNS Setup via Cloudflare (Domain Connect)

> This option is visible only to Elestio admin users (`user.isAdmin`).

Below the manual domain list, a **"One-click DNS Setup"** section is available (powered by the `DomainConnectButton` component). This uses the Domain Connect protocol to automatically configure DNS records.

### How it works

1. Enter your domain (e.g. `example.com`) in the Domain Connect input field.
2. Click **"Connect Domain"**.
3. The system calls the `getDomainConnectUrl` API with the server ID, domain, and host (`@`).
4. Based on the response:
   - **`status: "OK"`** — The user is redirected to the DNS provider (e.g. Cloudflare) to authorize and apply DNS records automatically. Before redirecting, the current page path and context (source, pipelineID, projectID) are saved to `localStorage` for return navigation.
   - **`status: "NOT_SUPPORTED"`** — Domain Connect is not supported for this domain's DNS provider. The user is shown a message to configure DNS manually instead.
   - **Error** — An error message is displayed.

### Domain validation

The domain input validates against the pattern: `^([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}$`

### localStorage keys used

- `domainConnectReturnUrl` — Stores the current page path to redirect back after DNS provider authorization.
- `domainConnectContext` — Stores JSON with `source` ("pipeline" or "service"), `pipelineID`, and `projectID` for context restoration.

---

## PTR Record Configuration

When the action type is `managePTRrecord`, the modal switches to PTR record mode:

1. Enter your domain in the input field (pre-filled with existing PTR record or CNAME).
2. Create both DNS records:
   - **A record** pointing to the service IPv4
   - **AAAA record** pointing to the service IPv6
3. Verify propagation via dnschecker.org links provided in the modal.
4. Click **Update** to apply.

### Provider-specific notes

- **DigitalOcean**: This action will reboot the system. Due to DNS cache, PTR adjusts automatically within a few hours.
- **Scaleway**: For SMTP servers, you may need to disable IPv6 on the VM.

---

## Cloudflare Reverse Proxy Users

If you are using Cloudflare reverse proxy (orange cloud icon), please check detailed instructions about Cloudflare & Elestio here:

https://docs.elest.io/books/security/page/using-cloudflare

---

## Environment Variable Update

For some software, you must also update an env var to indicate the domain to be used. To do that in the overview screen of your service, click on the UPDATE CONFIG button > Env tab > update the domain env var with your domain.

---

## Troubleshooting SSL Not Generated

You can display the nginx log with this command in a terminal:

Press Ctrl+C to stop displaying the live logs.

### Reset SSL_DATA folder

In some cases, the `/opt/elestio/nginx/ssl_data` folder can become corrupt. If this happens, connect to a terminal and try this:

Once executed, just open your custom website URL again, and your certificate should be generated and your site served over SSL/TLS.

---

## Component Architecture

| Component | File | Purpose |
|---|---|---|
| `ModalConfigureSSL` | `src/components/common/modal/ModalConfigureSSL.jsx` | SSL/domain management for services (includes PTR record mode) |
| `ModalConfigureDomain` | `src/components/common/modal/ModalConfigureDomain.jsx` | Domain management for CI/CD pipelines |
| `DomainConnectButton` | `src/components/serviceDetail/DomainConnectButton.jsx` | One-click DNS setup via Domain Connect protocol |

### API Actions (via `doActionOnServer` / `doActionOnPipeline`)

- `SSLDomainsList` — List current SSL domains
- `SSLDomainsAdd` — Add a domain to the SSL list
- `SSLDomainsRemove` — Remove a domain from the SSL list
- `getDomainConnectUrl` — Get the Domain Connect redirect URL for automatic DNS configuration

Back to top