dzone-api/CAPROVER_SETUP.md

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.