# Connect a custom domain ## What is a custom domain? By default your workspace is reachable under a platform subdomain, for example `mueller-immo.reosa.de`. With a custom domain you can use your own address instead, such as `app.makler-mueller.de` or `kunden.makler-mueller.de`. Logins, the dashboard and all tools then run under your own domain. For clients and team members the platform looks like a fully integrated part of your web presence. --- ## Prerequisites - **Standard plan or higher:** the feature is not included in the Compact plan. You can upgrade at any time. - **Access to the domain's DNS management:** you need access to the DNS area of your domain provider (e.g. IONOS, Strato, Cloudflare, GoDaddy, united-domains). If your web designer manages the domain, arrange access beforehand. - **Subdomain instead of apex:** we recommend a real subdomain such as `app.your-domain.com`. Apex domains (`your-domain.com` without a subdomain) are technically limited and frequently collide with your existing website. --- ## Step 1: Add the domain in the dashboard 1. Go to **Settings > Domains**. 2. Click **Add domain**. 3. Enter the address you want, for example `app.makler-mueller.de`. 4. Confirm with **Create domain**. After creation the detail view shows the **CNAME target** you have to enter at your DNS provider. The format typically looks like this: ``` app.makler-mueller.de CNAME tenants.reosa.de ``` The concrete target value is shown in the dashboard. Copy it from there, not from this documentation. --- ## Step 2: Set the DNS records 1. Sign in at your DNS provider and open the DNS management of your domain. 2. Create a new **CNAME record**: - **Host / name:** the subdomain part only, i.e. `app` (not the full address) - **Target / value:** the CNAME target shown in the dashboard - **TTL:** the default (300 or 3600 seconds). Lower values speed up changes but are not required 3. Save. Important: if an A record or another CNAME already exists for `app.your-domain.com` (often left over from earlier setups), **it must be deleted**. Otherwise verification will fail later because the DNS answer is ambiguous. --- ## Step 3: Wait for verification The platform checks the DNS entry automatically in the background. As soon as DNS propagation completes, the status in the dashboard switches from **Pending** to **Verified**. The wait is typically between 5 minutes and 24 hours, depending on the DNS provider and the previous TTL. You can refresh the status manually in between with the **Re-check status** button. --- ## Step 4: SSL certificate After successful verification an SSL certificate is issued via Let's Encrypt and installed for the domain automatically. This usually takes less than 5 minutes. Renewal then runs fully automatically every 60 days. There is nothing for you to do, and the certificate costs nothing extra. --- ## Step 5: Activate as primary domain In the domain overview the verified entry offers the switch **Set as primary domain**. After activation three things happen: 1. Logins and newly generated email links point to the custom domain. 2. The default subdomain `mueller-immo.reosa.de` stays active and redirects (HTTP 301) to the custom domain. **Existing links and bookmarks keep working.** Nobody has to relearn anything. 3. Email templates (invitations, notifications) use the new domain in all links from now on. --- ## What if verification fails? The most common reason: an old A record shadows the new CNAME entry. Diagnose from the terminal: ``` dig CNAME app.your-domain.com ``` The answer should contain the target value shown in the dashboard. If `dig` returns an A record instead of a CNAME, delete the A record at your DNS provider and wait out the TTL again. Other common causes: - **Typo in the CNAME target:** dots and letters slip easily when typing it in. - **Misconfigured DNSSEC:** very rare, but broken at some providers. - **Cloudflare proxy enabled:** if Cloudflare is your DNS provider, the orange cloud proxy must be **disabled** for this record (grey cloud, "DNS only"). With the proxy active, SSL verification fails. If the status stays on Pending after 24 hours, contact support with the exact domain and the output of the `dig` command. --- ## Switch or remove the domain A custom domain can be removed at any time under **Settings > Domains**. After removal the default subdomain takes over immediately. Existing sessions stay active. Before removing, we recommend giving affected team members a short heads-up.