Skip to content

Commit 6f1f2c6

Browse files
naterfutenaterfute
authored
Merge pull request #9 from declanhuggins/docs/subdomain-cloudflare-guide
docs: expand subdomain and Cloudflare setup guide
2 parents 171908e + c8de8b5 commit 6f1f2c6

2 files changed

Lines changed: 170 additions & 9 deletions

File tree

‎content/docs/pyrodactyl/subdomains/cloudflare.mdx‎

Lines changed: 139 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,150 @@
11
---
22
title: Cloudflare Subdomains
3-
description: Subdomains with Cloudflare
3+
description: Configure Cloudflare as a DNS provider for Pyrodactyl subdomains.
44
---
55

66
<Callout type="warn">
7-
You must get you api keys from the same spot as in the guide or it will **NOT** work
7+
Use a **Cloudflare API Token**, not a Global API Key. If the token is created
8+
from the wrong place or scoped to the wrong zone, subdomain creation will fail.
89
</Callout>
910

10-
## Creating a domain
11+
## What You Need
1112

13+
- A Cloudflare-managed zone such as `example.com`
14+
- A Pyrodactyl panel admin account
15+
- A node and allocation setup that can publish a public address
16+
- A supported egg feature such as `subdomain_minecraft`
17+
18+
## Create A Cloudflare Token
19+
20+
1. Open **Cloudflare Dashboard -> My Profile -> API Tokens**.
21+
1. Select **Create Token**.
22+
1. Start from **Edit zone DNS**, or create a custom token with the same scope.
23+
1. Set the permission to:
24+
25+
- `Zone` -> `DNS` -> `Edit`
26+
27+
1. Scope the token to the exact zone you want Pyrodactyl to manage:
28+
29+
- `Include` -> `Specific zone` -> `example.com`
30+
31+
1. Create the token and copy it immediately.
32+
33+
<Callout type="info">
34+
Pyrodactyl stores the zone ID directly, so `Zone Read` is not required for the
35+
normal Cloudflare subdomain flow.
36+
</Callout>
37+
38+
## Get The Zone ID
39+
40+
1. Open the zone in Cloudflare.
41+
1. On the overview page, copy the **Zone ID** from the right sidebar.
42+
43+
## Verify The Token
44+
45+
Before adding the domain to Pyrodactyl, verify the token from any machine that can
46+
reach the Cloudflare API:
47+
48+
```bash
49+
curl "https://api.cloudflare.com/client/v4/user/tokens/verify" \
50+
--header "Authorization: Bearer YOUR_TOKEN"
51+
```
52+
53+
The response should include `"success": true`.
54+
55+
If you receive an authentication error here, Pyrodactyl will fail too.
56+
57+
## Create The Domain In Pyrodactyl
58+
59+
1. Open **Admin -> Settings -> Domains**.
60+
1. Select **Create Domain**.
61+
1. Fill in:
62+
63+
- **Domain Name**: your zone name, for example `example.com`
64+
- **DNS Provider**: `Cloudflare`
65+
- **API Token**: the token created above
66+
- **Zone ID**: the Cloudflare zone ID for this domain
67+
68+
1. Click **Test Connection**.
69+
1. If the connection succeeds, save the domain.
70+
1. Mark the domain as **Active**.
71+
1. Mark it as **Default** if you want Pyrodactyl to generate subdomains for new
72+
supported servers automatically.
73+
74+
## Configure The Node And Allocations
75+
76+
Pyrodactyl builds subdomain DNS records from the server's **primary allocation**.
77+
That means the address behind the allocation must be valid for public DNS.
78+
79+
### Option 1: Publish The Allocation IP Directly
80+
81+
Use this if the allocation IP is already public.
82+
83+
- Leave **Domain by Allocation Alias** disabled on the node, or
84+
- Keep it enabled only if each allocation has a correct public alias
85+
86+
### Option 2: Publish The Allocation Alias
87+
88+
Use this if the node uses private addresses internally.
89+
90+
1. Open **Admin -> Nodes -> Your Node -> Settings**.
91+
1. Enable **Domain by Allocation Alias**.
92+
1. Open **Admin -> Nodes -> Your Node -> Allocation**.
93+
1. Set the allocation alias for the server's primary allocation to the public IP
94+
you want DNS to publish.
95+
96+
<Callout type="warn">
97+
If **Domain by Allocation Alias** is enabled and the allocation alias is blank,
98+
Pyrodactyl can create DNS records that point to the wrong address.
99+
</Callout>
100+
101+
## Record Behavior
102+
103+
Pyrodactyl creates different records depending on the egg feature and port:
104+
105+
- Minecraft on port `25565`: A record only
106+
- Minecraft on a non-default port: A record plus an SRV record
107+
- Other supported services: record sets vary by feature
108+
109+
See [Egg Features](/docs/pyrodactyl/config/egg-features) for the supported
110+
subdomain feature flags.
111+
112+
## Troubleshooting
113+
114+
### `Authentication error`
115+
116+
This usually means one of the following:
117+
118+
- You used a Global API Key instead of an API Token
119+
- The token is scoped to the wrong zone
120+
- The token does not include `Zone -> DNS -> Edit`
121+
- The token was copied incorrectly
122+
123+
Recreate the token and test it again with Cloudflare's token verify endpoint.
124+
125+
### Subdomain Points To A Private IP
126+
127+
Check the node and allocation configuration:
128+
129+
- If **Domain by Allocation Alias** is enabled, make sure the allocation has a
130+
public `ip_alias`
131+
- If the alias is blank, Pyrodactyl may publish the allocation's internal IP
132+
133+
### No Domain Appears In The Server UI
134+
135+
Check all of the following:
136+
137+
- The domain is marked **Active**
138+
- The server uses an egg with a supported `subdomain_*` feature
139+
- At least one domain exists in **Admin -> Settings -> Domains**
140+
141+
### Automatic Subdomain Creation Does Not Happen
142+
143+
Automatic generation only applies when:
144+
145+
- The server supports subdomains
146+
- A default domain exists
147+
- That default domain is active
12148

13149

14150

‎content/docs/pyrodactyl/subdomains/index.mdx‎

Lines changed: 31 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,45 @@
11
---
22
title: Subdomain Guides
3-
description: Comprehensive guides for using and creating subdomains in the pyrodactyl panel
3+
description: Configure Pyrodactyl subdomains, DNS providers, and allocation aliases.
44
---
55

6-
This section provides detailed guides for setting up and using the subdomain feature of pyrodactyl panel.
6+
This section covers the DNS and panel configuration required to use Pyrodactyl
7+
subdomains reliably.
78

89
<Callout type="info">
9-
For Pyrodactyl-specific issues, please use [Pyrodactyl Discord]() instead of
10+
For Pyrodactyl-specific issues, please use [Pyrodactyl Discord](https://discord.gg/FGWKZT5dxv) instead of
1011
Pterodactyl or Pelican support channels.
1112
</Callout>
1213

13-
## Available Migration Methods
14+
## Before You Start
15+
16+
Make sure all of the following are true before you debug a subdomain failure:
17+
18+
- Your server's egg includes a supported subdomain feature such as
19+
`subdomain_minecraft`, `subdomain_factorio`, `subdomain_rust`,
20+
`subdomain_scpsl`, or `subdomain_teamspeak`.
21+
- You have created at least one active domain in **Admin -> Settings -> Domains**.
22+
- If you want new supported servers to receive generated subdomains automatically,
23+
mark one domain as the **default** domain.
24+
- Your node and allocations are configured to publish a public address.
25+
26+
## Allocation Aliases And Public DNS
27+
28+
Pyrodactyl creates DNS records from the server's **primary allocation**.
29+
30+
- If your allocations already use public IP addresses, you can publish them directly.
31+
- If your node uses private allocation IPs, NAT, or another internal network layout,
32+
enable **Domain by Allocation Alias** on the node and set each allocation's
33+
`ip_alias` to the public IP you want DNS to publish.
34+
35+
If **Domain by Allocation Alias** is enabled but the allocation alias is blank, the
36+
created record can point at the wrong address. This is one of the most common
37+
subdomain setup mistakes.
38+
39+
## Provider Guides
1440

1541
<Cards>
1642
<Card title="Cloudflare Integration" href="/docs/pyrodactyl/subdomains/cloudflare">
17-
Configure and Start using Cloudflare DNS with pyrodactyl
43+
Configure Cloudflare DNS, create the correct API token, and verify domain setup.
1844
</Card>
1945
</Cards>
20-

0 commit comments

Comments
 (0)