chore: clean .gitignore cache
This commit is contained in:
GitHub Actions
@@ -1,198 +0,0 @@
|
||||
# DigitalOcean DNS Provider Setup
|
||||
|
||||
## Overview
|
||||
|
||||
DigitalOcean provides DNS hosting for free with any DigitalOcean account. This guide covers setting up DigitalOcean DNS as a provider in Charon for wildcard certificate management.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- DigitalOcean account (free tier is sufficient)
|
||||
- Domain added to DigitalOcean DNS
|
||||
- Domain nameservers pointing to DigitalOcean:
|
||||
- `ns1.digitalocean.com`
|
||||
- `ns2.digitalocean.com`
|
||||
- `ns3.digitalocean.com`
|
||||
|
||||
## Step 1: Generate Personal Access Token
|
||||
|
||||
1. Log in to [DigitalOcean Control Panel](https://cloud.digitalocean.com/)
|
||||
2. Click on **API** in the left sidebar (under Account)
|
||||
3. Navigate to the **Tokens/Keys** tab
|
||||
4. Click **Generate New Token** (in the Personal access tokens section)
|
||||
5. Configure the token:
|
||||
- **Token Name:** `charon-dns-challenge` (or any descriptive name)
|
||||
- **Expiration:** Choose expiration period (90 days, 1 year, or no expiry)
|
||||
- **Scopes:** Select **Write** (this includes Read access)
|
||||
6. Click **Generate Token**
|
||||
7. **Copy the token immediately** (shown only once)
|
||||
|
||||
> **Warning:** DigitalOcean shows the token only once. Store it securely in a password manager.
|
||||
|
||||
## Step 2: Verify DNS Configuration
|
||||
|
||||
Ensure your domain is properly configured in DigitalOcean DNS:
|
||||
|
||||
1. Navigate to **Networking** → **Domains** in the DigitalOcean control panel
|
||||
2. Verify your domain is listed
|
||||
3. Click on the domain to view DNS records
|
||||
4. Ensure at least one A or CNAME record exists (for the domain itself)
|
||||
|
||||
> **Note:** Charon will create and remove TXT records automatically; no manual DNS configuration is needed.
|
||||
|
||||
## Step 3: Configure in Charon
|
||||
|
||||
1. Navigate to **DNS Providers** in Charon
|
||||
2. Click **Add Provider**
|
||||
3. Fill in the form:
|
||||
- **Provider Type:** Select `DigitalOcean`
|
||||
- **Name:** Enter a descriptive name (e.g., "DigitalOcean DNS")
|
||||
- **API Token:** Paste the Personal Access Token from Step 1
|
||||
|
||||
### Advanced Settings (Optional)
|
||||
|
||||
Expand **Advanced Settings** to customize:
|
||||
|
||||
- **Propagation Timeout:** `90` seconds (DigitalOcean propagates quickly)
|
||||
- **Polling Interval:** `10` seconds (default)
|
||||
- **Set as Default:** Enable if this is your primary DNS provider
|
||||
|
||||
## Step 4: Test Connection
|
||||
|
||||
1. Click **Test Connection** button
|
||||
2. Wait for validation (usually 3-5 seconds)
|
||||
3. Verify you see: ✅ **Connection successful**
|
||||
|
||||
The test verifies:
|
||||
|
||||
- Token is valid and active
|
||||
- Account has DNS write permissions
|
||||
- DigitalOcean API is accessible
|
||||
|
||||
If the test fails, see [Troubleshooting](#troubleshooting) below.
|
||||
|
||||
## Step 5: Save Configuration
|
||||
|
||||
Click **Save** to store the DNS provider configuration. The token is encrypted at rest using AES-256-GCM.
|
||||
|
||||
## Step 6: Use with Wildcard Certificates
|
||||
|
||||
When creating a proxy host with a wildcard domain:
|
||||
|
||||
1. Navigate to **Proxy Hosts** → **Add Proxy Host**
|
||||
2. Enter a wildcard domain: `*.example.com`
|
||||
3. Select **DigitalOcean** from the DNS Provider dropdown
|
||||
4. Configure remaining settings
|
||||
5. Save
|
||||
|
||||
Charon will automatically obtain a wildcard certificate using DNS-01 challenge.
|
||||
|
||||
## Example Configuration
|
||||
|
||||
```yaml
|
||||
Provider Type: digitalocean
|
||||
Name: DigitalOcean - example.com
|
||||
API Token: dop_v1_********************************
|
||||
Propagation Timeout: 90 seconds
|
||||
Polling Interval: 10 seconds
|
||||
Default: Yes
|
||||
```
|
||||
|
||||
## Required Permissions
|
||||
|
||||
The Personal Access Token needs **Write** scope, which includes:
|
||||
|
||||
- Read access to domains and DNS records
|
||||
- Write access to create/update/delete DNS records
|
||||
|
||||
> **Note:** Token scope is account-wide. You cannot restrict to specific domains in DigitalOcean.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Test Fails
|
||||
|
||||
**Error:** `Invalid token` or `Unauthorized`
|
||||
|
||||
- Verify the token was copied correctly (should start with `dop_v1_`)
|
||||
- Ensure token has **Write** scope (not just Read)
|
||||
- Check token hasn't expired (if expiration was set)
|
||||
- Regenerate the token if necessary
|
||||
|
||||
**Error:** `Domain not found`
|
||||
|
||||
- Verify the domain is added to DigitalOcean DNS
|
||||
- Ensure domain nameservers point to DigitalOcean
|
||||
- Check domain status in the Networking section
|
||||
- Wait 24-48 hours if nameservers were recently changed
|
||||
|
||||
### Certificate Issuance Fails
|
||||
|
||||
**Error:** `DNS propagation timeout`
|
||||
|
||||
- DigitalOcean DNS typically propagates in <60 seconds
|
||||
- Verify nameservers are correctly configured:
|
||||
|
||||
```bash
|
||||
dig NS example.com +short
|
||||
```
|
||||
|
||||
- Check DigitalOcean Status page for service issues
|
||||
- Increase Propagation Timeout to 120 seconds as a workaround
|
||||
|
||||
**Error:** `Record creation failed`
|
||||
|
||||
- Check token permissions (must be Write scope)
|
||||
- Verify domain exists in DigitalOcean DNS
|
||||
- Review Charon logs for detailed API errors
|
||||
- Ensure no conflicting TXT records exist with name `_acme-challenge`
|
||||
|
||||
### Nameserver Propagation
|
||||
|
||||
**Issue:** DNS changes not visible globally
|
||||
|
||||
- Nameserver changes can take 24-48 hours to propagate
|
||||
- Use [DNS Checker](https://dnschecker.org/) to verify global propagation
|
||||
- Ensure your domain registrar shows DigitalOcean nameservers
|
||||
- Wait for full propagation before attempting certificate issuance
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
DigitalOcean API rate limits:
|
||||
|
||||
- 5,000 requests per hour (per account)
|
||||
- Certificate challenges typically use <20 requests
|
||||
|
||||
If you hit limits:
|
||||
|
||||
- Reduce frequency of certificate renewals
|
||||
- Avoid unnecessary test connection attempts
|
||||
- Contact DigitalOcean support if consistently hitting limits
|
||||
|
||||
## Security Recommendations
|
||||
|
||||
1. **Token Expiration:** Set 90-day expiration and rotate regularly
|
||||
2. **Dedicated Token:** Create a separate token for Charon (easier to revoke)
|
||||
3. **Monitor Usage:** Review API logs in DigitalOcean control panel
|
||||
4. **Least Privilege:** Use Write scope (don't grant Full Access)
|
||||
5. **Backup Access:** Keep a backup token in secure storage (offline)
|
||||
6. **Revoke Unused:** Delete tokens that are no longer needed
|
||||
|
||||
## DigitalOcean DNS Limitations
|
||||
|
||||
- **No per-domain token scoping:** Tokens grant access to all domains in the account
|
||||
- **No rate limit customization:** Fixed at 5,000 requests/hour
|
||||
- **Public zones only:** Private DNS not supported
|
||||
- **No DNSSEC:** DigitalOcean does not support DNSSEC at this time
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [DigitalOcean DNS Documentation](https://docs.digitalocean.com/products/networking/dns/)
|
||||
- [DigitalOcean API Documentation](https://docs.digitalocean.com/reference/api/)
|
||||
- [Personal Access Tokens Guide](https://docs.digitalocean.com/reference/api/create-personal-access-token/)
|
||||
- [Caddy DigitalOcean Module](https://caddyserver.com/docs/modules/dns.providers.digitalocean)
|
||||
- [DigitalOcean Status Page](https://status.digitalocean.com/)
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [DNS Providers Overview](../dns-providers.md)
|
||||
- [Wildcard Certificates Guide](../certificates.md#wildcard-certificates)
|
||||
- [DNS Challenges Troubleshooting](../../troubleshooting/dns-challenges.md)
|
||||
Reference in New Issue
Block a user