# 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:
    ```javascript
    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:
    ```html
    <!-- 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:
    ```json
    "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:
```bash
./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:**
   ```bash
   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.
   ```bash
   ./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.