# Caprover Integration Setup

This document explains how to set up the integration between the DZone API and Caprover for automatic domain configuration.

## Overview

When a user successfully verifies their domain, the system will automatically configure that domain in Caprover, enabling the domain to be properly routed to the frontend application.

## Configuration Steps

### 1. Set Environment Variables

Add the following environment variables to your `.env` file:

```
CAPROVER_API_URL=https://captain.dev.danakcorp.com/api/v2
CAPROVER_EMAIL=your_caprover_email@example.com
CAPROVER_PASSWORD=your_caprover_password
CAPROVER_APP_NAME=dzone-front
```

The system will automatically handle authentication with Caprover using these credentials and refresh tokens as needed.

### 2. Verify Configuration

1. Restart the API service to apply the new environment variables
2. Try verifying a domain through the API
3. Check the logs to ensure the Caprover API calls are successful

## How Token Refresh Works

The system automatically handles Caprover authentication:

1. When a domain configuration request is made, the system checks if it has a valid token
2. If no token exists or the token is about to expire (within 5 minutes), it requests a new one
3. The system uses the email and password to authenticate with Caprover
4. The new token is stored and used for subsequent requests
5. Tokens are typically valid for 24 hours, but the system refreshes them after 23 hours to be safe

This approach ensures that the integration continues to work even if tokens expire.

## Troubleshooting

### Authentication Issues

If you see authentication errors in the logs:

1. Verify that the `CAPROVER_EMAIL` and `CAPROVER_PASSWORD` are correct
2. Check that the user has sufficient permissions in Caprover
3. Ensure the Caprover instance is accessible at the URL specified in `CAPROVER_API_URL`

### API Connection Issues

If the API cannot connect to Caprover, check:

1. That the Caprover instance is running and accessible
2. That the `CAPROVER_API_URL` is correct
3. That there are no network issues between the API server and Caprover

### Domain Configuration Issues

If domains are not being properly configured in Caprover:

1. Check that the domain has proper DNS records pointing to your server
2. Verify that the app name specified in `CAPROVER_APP_NAME` exists in Caprover
3. Ensure the Caprover user associated with the credentials has sufficient permissions

## Manual Configuration

If automatic configuration fails, you can manually configure domains using the admin endpoint:

```
POST /business/domain/configure-caprover
```

This endpoint requires authentication and a business with a verified domain.