Christian Krakau-Louis
121 lines
4.8 KiB
Markdown
121 lines
4.8 KiB
Markdown
# Setting up Dropbox Integration
|
|
|
|
This guide explains how to set up the Dropbox integration for DocuNova.
|
|
|
|
## Required Configuration Parameters
|
|
|
|
| **Variable** | **Description** |
|
|
|-------------------------|--------------------------------------------------|
|
|
| `DROPBOX_APP_KEY` | Dropbox API app key |
|
|
| `DROPBOX_APP_SECRET` | Dropbox API app secret |
|
|
| `DROPBOX_REFRESH_TOKEN` | OAuth2 refresh token for Dropbox |
|
|
| `DROPBOX_FOLDER` | Default folder path for Dropbox uploads |
|
|
|
|
For a complete list of configuration options, see the [Configuration Guide](ConfigurationGuide.md).
|
|
|
|
## Setup Methods
|
|
|
|
You can set up Dropbox integration in two ways:
|
|
|
|
1. **Using the Built-in Setup Wizard (Recommended)**: An interactive setup experience available at `/dropbox-setup` in the web interface
|
|
2. **Manual Setup**: Following the step-by-step instructions in this document
|
|
|
|
## Using the Setup Wizard
|
|
|
|
The easiest way to set up Dropbox integration is to use the built-in setup wizard:
|
|
|
|
1. Navigate to the `/dropbox-setup` page in your DocuNova instance
|
|
2. Follow the on-screen instructions to create a Dropbox app
|
|
3. Enter your App Key and App Secret in the wizard
|
|
4. Optionally specify a custom folder path for uploads
|
|
5. Click "Start Authentication Flow" to begin the authorization process
|
|
6. Complete the Dropbox authentication process
|
|
7. The system will automatically exchange the authorization code for a refresh token
|
|
8. Copy the generated environment variables for your worker nodes
|
|
|
|
The wizard handles all the token exchange steps and provides you with the exact configuration needed for your environment.
|
|
|
|
## Step-by-Step Manual Setup Instructions
|
|
|
|
### 1. Create a Dropbox App
|
|
|
|
1. Go to the [Dropbox Developer Apps Console](https://www.dropbox.com/developers/apps)
|
|
2. Click "Create app"
|
|
3. Select "Scoped access" for API
|
|
4. Choose "Full Dropbox" access (or "App folder" for more restricted access)
|
|
5. Give your app a name (e.g., "DocuNova")
|
|
6. Click "Create app"
|
|
|
|
### 2. Configure App Permissions
|
|
|
|
1. In your app's settings page, go to the "Permissions" tab
|
|
2. Enable the following permissions:
|
|
- `files.content.write` (to upload files)
|
|
- `files.content.read` (if you need to read file content)
|
|
3. Click "Submit" to save changes
|
|
|
|
### 3. Get App Key and Secret
|
|
|
|
1. On your app's settings page, find the "App key" and "App secret"
|
|
2. Set these as `DROPBOX_APP_KEY` and `DROPBOX_APP_SECRET` in your configuration
|
|
|
|
### 4. Generate a Refresh Token
|
|
|
|
1. Go to the "OAuth 2" tab in your app settings
|
|
2. Add a redirect URI: `http://localhost` (this is for the authorization flow)
|
|
3. Generate an authorization URL with these instructions:
|
|
|
|
```
|
|
https://www.dropbox.com/oauth2/authorize?client_id=YOUR_APP_KEY&response_type=code&token_access_type=offline
|
|
```
|
|
|
|
4. Replace `YOUR_APP_KEY` with your app key
|
|
5. Open this URL in your browser
|
|
6. Authorize the app when prompted
|
|
7. You'll be redirected to `localhost` with a code parameter in the URL
|
|
8. Copy this code parameter
|
|
|
|
### 5. Exchange the Code for a Refresh Token
|
|
|
|
1. Use this curl command to exchange the code for tokens:
|
|
|
|
```bash
|
|
curl -X POST https://api.dropboxapi.com/oauth2/token \
|
|
-d code=YOUR_AUTH_CODE \
|
|
-d grant_type=authorization_code \
|
|
-d client_id=YOUR_APP_KEY \
|
|
-d client_secret=YOUR_APP_SECRET \
|
|
-d redirect_uri=http://localhost
|
|
```
|
|
|
|
2. From the response, copy the `refresh_token` value
|
|
|
|
### 6. Configure DocuNova
|
|
|
|
1. Set `DROPBOX_APP_KEY`, `DROPBOX_APP_SECRET`, and `DROPBOX_REFRESH_TOKEN` with your values
|
|
2. Set `DROPBOX_FOLDER` to the path where files should be uploaded (e.g., `/Documents/Uploads`)
|
|
|
|
## Token Management
|
|
|
|
The system will use the refresh token to automatically generate short-lived access tokens when needed. Refresh tokens typically don't expire unless revoked.
|
|
|
|
### Testing Your Token
|
|
|
|
You can test if your token is working correctly:
|
|
|
|
1. Navigate to the `/dropbox-setup` page in your DocuNova instance
|
|
2. Click the "Test Token" button to verify your credentials
|
|
3. If the test fails, click "Refresh Token" to obtain a new refresh token
|
|
|
|
## Troubleshooting
|
|
|
|
If you encounter issues with Dropbox integration:
|
|
|
|
1. **Authentication Errors**: Make sure your App Key and App Secret are correct
|
|
2. **Token Expired**: Click "Refresh Token" button on the setup page to obtain a new token
|
|
3. **Folder Permissions**: Ensure your app has the correct permissions enabled for file operations
|
|
4. **Invalid Redirect URI**: Verify that the redirect URI in your app settings matches the one used in the authentication flow
|
|
5. **Rate Limiting**: Dropbox API has rate limits; if exceeded, wait and try again
|
|
|
|
For more general configuration issues, see the [Configuration Troubleshooting Guide](ConfigurationTroubleshooting.md).
|