cloudron-box/PLAN.md

Plan: Adding PowerDNS as a DNS Provider to Cloudron

This document outlines the detailed steps required to add support for PowerDNS via the PowerDNS Authoritative Server REST API to Cloudron. It covers frontend UI updates, backend DNS provider implementation, unit testing, and live testing instructions.

1. Frontend Modifications

The Cloudron dashboard is a Vue application that needs to know about the new provider and how to prompt the user for credentials.

dashboard/src/models/DomainsModel.js

• Add Provider: Append { name: 'PowerDNS', value: 'powerdns' } to the providers array.
• Define Required Properties: In the getProviderConfigProps(provider) switch statement, add a case for PowerDNS to define the fields it needs:

  case 'powerdns':
    props = ['apiUrl', 'apiKey'];
    break;
  

dashboard/src/components/DomainProviderForm.vue

• Reset Logic: In the dnsConfig reset block (around line 57), add dnsConfig.value.apiUrl = ''; to ensure the form clears properly.
• UI Template: Add the HTML form groups for PowerDNS within the template section:

  <!-- powerdns -->
  <FormGroup v-if="provider === 'powerdns'">
    <label for="powerdnsApiUrlInput">{{ $t('domains.domainDialog.powerdnsApiUrl') }}</label>
    <TextInput id="powerdnsApiUrlInput" type="url" v-model="dnsConfig.apiUrl" placeholder="https://ns1.example.com:8081" required />
  </FormGroup>
  <FormGroup v-if="provider === 'powerdns'">
    <label for="powerdnsApiKeyInput">{{ $t('domains.domainDialog.powerdnsApiKey') }}</label>
    <MaskedInput id="powerdnsApiKeyInput" v-model="dnsConfig.apiKey" required />
  </FormGroup>
  

dashboard/public/translation/en.json

• Add Translations: Add the English translation strings for the new fields under the domains.domainDialog object:

  "powerdnsApiUrl": "PowerDNS API URL (e.g., https://ns1.example.com:8081)",
  "powerdnsApiKey": "API Key",
  

2. Backend Modifications

The backend needs a new driver file that implements the standard Cloudron DNS provider interface.

src/dns.js

• Import the Driver: Add import dnsPowerdns from './dns/powerdns.js'; at the top with the other imports.
• Register the Provider: Add powerdns: dnsPowerdns to the DNS_PROVIDERS mapping object.

src/dns/powerdns.js (New File)

Create a new file that implements the standard DNS interface (src/dns/interface.js).

• Required Methods: Export removePrivateFields, injectPrivateFields, upsert, get, del, wait, and verifyDomainConfig.
• API Interactions:
  • Construct the base URL: const baseUrl = domainConfig.apiUrl.replace(/\/$/, '');
  • Ensure queries and zone names have a trailing dot, as PowerDNS strictly requires absolute FQDNs (e.g., example.com.).
  • Set the X-API-Key header using domainConfig.apiKey for all requests.
• Operations:
  • get: Use GET ${baseUrl}/api/v1/servers/localhost/zones/${zoneName}. and extract records from the rrsets array matching the exact fqdn and type.
  • upsert: Use PATCH ${baseUrl}/api/v1/servers/localhost/zones/${zoneName}.. Send an rrsets payload with changetype: 'REPLACE'. Ensure TXT values are quoted.
  • del: Use PATCH with changetype: 'DELETE'.
• verifyDomainConfig: Perform a test upsert and del of an A record on the subdomain cloudrontestdns to ensure the API is reachable and the key has edit permissions.

3. Automated Testing (Local)

The new provider needs to be verified against the existing test suite using mock HTTP requests.

src/test/dns-providers-test.js

• Add a new describe('powerdns', ...) block.
• Setup mock domain configuration with a dummy apiUrl and apiKey.
• Use nock to intercept requests to the dummy apiUrl.
• Write tests for:
  • upsert non-existing and existing records.
  • get records.
  • del records.
• Ensure the nock endpoints expect the exact JSON structure and rrsets payload required by PowerDNS.

Running the Tests

Run the specific test suite for DNS providers locally:

./run-tests src/test/dns-providers-test.js

(This uses the fast-path to run mocha directly, skipping the full Cloudron test environment setup).

4. Live Testing (Remote Cloudron Server)

To test the integration end-to-end, deploy the changes to a temporary Cloudron instance using the provided hotfix script.

Important Considerations for Hotfixing: The scripts/hotfix tool builds a release tarball by executing git archive HEAD. You must commit your changes locally before running the hotfix, otherwise the script will fail or push the old codebase.

1. Commit Changes:

   git add .
   git commit -m "Implement PowerDNS provider"
   

2. Run Hotfix Script: Execute the hotfix script from the repository root, pointing it to your test server.

   ./scripts/hotfix --cloudron <IP_OR_DOMAIN_OF_TEST_SERVER> --ssh-user root --ssh-key ~/.ssh/id_rsa --release 1.0.0-test
   

3. Verify Deployment:

   • The script will install dependencies, compile the Vue dashboard, bundle the backend code, push it to the server, and restart the box service.
   • Log into the Cloudron dashboard via your browser.
   • Navigate to Domains -> Add Domain, select "PowerDNS".
   • Enter a test domain, a valid PowerDNS API URL, and an API Key.
   • Verify that Cloudron successfully configures the domain and creates the necessary initial DNS records.