Skip to content

Commit 0e5a338

Browse files
Pol-LanskiPol-Lanski
committed
docs: add custom domain guide with Cloudflare Worker and CNAME options
1 parent 0c2629b commit 0e5a338

1 file changed

Lines changed: 142 additions & 0 deletions

File tree

‎docs/custom-domain.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Accessing SplitPro with a Custom Domain
2+
3+
SplitPro on DAppNode supports three access methods:
4+
5+
| Method | URL example | Requires |
6+
|---|---|---|
7+
| Local network | `http://split-pro.public.dappnode:3000` | DAppNode VPN or LAN access |
8+
| DynDNS (default) | `https://splitpro.<hash>.dyndns.dappnode.io` | HTTPS package |
9+
| Custom domain | `https://splitpro.yourdomain.com` | Domain + Cloudflare |
10+
11+
---
12+
13+
## Why NEXTAUTH_URL matters
14+
15+
SplitPro uses NextAuth for authentication. NextAuth embeds the app URL into magic-link emails and session cookies. If you access SplitPro from a URL that doesn't match `NEXTAUTH_URL`, logins will fail and you may end up with separate user accounts depending on which URL was used to sign up.
16+
17+
`NEXTAUTH_URL` must match the URL you browse to.
18+
19+
By default, SplitPro auto-detects the DynDNS URL from the `_DAPPNODE_GLOBAL_DOMAIN` environment variable that DAppNode injects into all packages. You only need to configure `NEXTAUTH_URL` manually if you want to use a custom domain.
20+
21+
---
22+
23+
## Option 1: DynDNS (default, no configuration needed)
24+
25+
Install the [HTTPS package](https://docs.dappnode.io/user/packages/https) and SplitPro will automatically be reachable at:
26+
27+
```
28+
https://splitpro.<your-hash>.dyndns.dappnode.io
29+
```
30+
31+
`NEXTAUTH_URL` is set automatically. Nothing else to configure.
32+
33+
---
34+
35+
## Option 2: Custom domain via Cloudflare
36+
37+
Use this if you want a stable, readable URL like `https://splitpro.yourdomain.com`.
38+
39+
### Why Cloudflare
40+
41+
DAppNodes typically run on residential internet connections with dynamic IP addresses. DAppNode's DynDNS service (`<hash>.dyndns.dappnode.io`) tracks the current IP automatically. The HTTPS package can issue TLS certificates for DynDNS subdomains because DAppNode controls that DNS zone — but it cannot issue certificates for external domains you own.
42+
43+
Cloudflare solves both problems: it proxies traffic through its own network (providing TLS for your custom domain), and resolves your CNAME to the DynDNS name so the dynamic IP is not a problem.
44+
45+
### Prerequisites
46+
47+
- A domain managed by [Cloudflare](https://cloudflare.com) (free plan works)
48+
- The HTTPS package installed on your DAppNode (so DynDNS is active)
49+
- Your DynDNS subdomain (visible in the HTTPS package UI, format: `<hash>.dyndns.dappnode.io`)
50+
51+
### Approach A — Cloudflare Worker (recommended)
52+
53+
Cloudflare's proxied CNAME only forwards traffic on [specific ports](https://developers.cloudflare.com/fundamentals/reference/network-ports/). Port 3000 is not in that list. A Cloudflare Worker bypasses this constraint entirely and is simpler to set up than port forwarding.
54+
55+
**1. Create the Worker**
56+
57+
In the Cloudflare dashboard, go to **Workers & Pages → Create** and deploy this script:
58+
59+
```js
60+
export default {
61+
async fetch(request) {
62+
const url = new URL(request.url);
63+
url.hostname = "splitpro.<hash>.dyndns.dappnode.io";
64+
url.port = "3000";
65+
url.protocol = "http:";
66+
return fetch(url, request);
67+
}
68+
}
69+
```
70+
71+
Replace `splitpro.<hash>.dyndns.dappnode.io` with your actual DynDNS subdomain.
72+
73+
**2. Add a custom route**
74+
75+
In the Worker's **Triggers** tab, add a custom domain or route:
76+
77+
```
78+
splitpro.yourdomain.com/*
79+
```
80+
81+
Cloudflare will handle TLS for `splitpro.yourdomain.com` automatically. No SSL/TLS mode change needed. No router port forwarding needed.
82+
83+
**3. Set NEXTAUTH_URL**
84+
85+
In the DAppNode UI, go to **SplitPro → Config** and set:
86+
87+
**App URL:** `https://splitpro.yourdomain.com`
88+
89+
Include `https://` and no trailing slash. Save and restart the package.
90+
91+
---
92+
93+
### Approach B — Cloudflare proxied CNAME with port forwarding
94+
95+
Use this if you prefer not to use Workers.
96+
97+
**1. Forward port 3000 on your router**
98+
99+
In your router's port forwarding settings, forward external TCP port 3000 to your DAppNode's local IP address on port 3000.
100+
101+
**2. Create a CNAME record in Cloudflare**
102+
103+
In the Cloudflare DNS dashboard for your domain, add:
104+
105+
| Type | Name | Target | Proxy |
106+
|---|---|---|---|
107+
| CNAME | `splitpro` | `splitpro.<hash>.dyndns.dappnode.io` | Proxied (orange cloud) |
108+
109+
The **Proxied** toggle is essential — it provides TLS for your domain and hides your IP.
110+
111+
**3. Set Cloudflare SSL/TLS mode**
112+
113+
In Cloudflare, go to **SSL/TLS → Overview** and set the mode to **Full**.
114+
115+
- **Flexible** causes redirect loops
116+
- **Full (strict)** requires a valid cert on the origin (DAppNode won't have one for your domain)
117+
- **Full** is correct
118+
119+
Note: Cloudflare proxied connections only reach the origin on [specific ports](https://developers.cloudflare.com/fundamentals/reference/network-ports/). Port 3000 is not supported. You would need to change SplitPro's exposed port to one that Cloudflare supports (e.g. 8080) and update your router forwarding accordingly. This is why Approach A (Worker) is simpler.
120+
121+
**4. Set NEXTAUTH_URL**
122+
123+
Same as Approach A: set **App URL** to `https://splitpro.yourdomain.com` in **SplitPro → Config**, save, and restart.
124+
125+
---
126+
127+
## Troubleshooting
128+
129+
**Magic-link emails link to the wrong URL**
130+
`NEXTAUTH_URL` in Config does not match your actual URL. Check for a trailing slash or wrong protocol.
131+
132+
**I get a redirect loop**
133+
Cloudflare SSL/TLS mode is set to Flexible. Change it to Full (Approach B only).
134+
135+
**Worker returns a 522 or connection error**
136+
The DynDNS hostname in the Worker script is wrong, or the HTTPS package is not running. Verify the DynDNS URL is reachable directly in a browser first.
137+
138+
**Port forwarding doesn't work (Approach B)**
139+
Port 3000 is not in Cloudflare's supported origin port list. Switch to Approach A (Worker), or change SplitPro's exposed port to 8080 in docker-compose.yml and update the router rule.
140+
141+
**I signed up via DynDNS and now use a custom domain — my account seems missing**
142+
Your account exists but the session cookie doesn't carry across origins. Sign in again with the same email on the new URL. Both sessions share the same database — no data is lost.

0 commit comments

Comments
 (0)