Configuring Dropbox Cloud Backup

This guide explains how to configure Fermentrack 2 to enable Dropbox cloud backup for users of your instance. Once configured, users will be able to link their Dropbox accounts and upload backups directly to their personal Dropbox storage.

note

Each Fermentrack 2 instance requires its own Dropbox app credentials. If you are running a self-hosted instance, you will need to create your own Dropbox app in the Dropbox Developer Portal.

Overview

The Dropbox integration uses OAuth 2.0 to securely connect user accounts. When a user initiates the connection:

1. They are redirected to Dropbox to authorize the connection
2. Dropbox redirects back to Fermentrack with an authorization code
3. Fermentrack exchanges the code for access and refresh tokens
4. Tokens are stored encrypted in the database
5. Users can then upload backups to their Dropbox account

All backup files are stored in the app's dedicated folder within Dropbox (/Apps/Fermentrack/ or your chosen app name).

Step 1: Create a Dropbox App

1. Go to the Dropbox Developer Portal

2. Sign in with your Dropbox account (or create one if needed)

3. Click Create app

4. Configure the app with these settings:

   Choose an API: Select Scoped access

   Choose the type of access you need: Select App folder

   note

   "App folder" access is recommended as it limits Fermentrack to only access files within its own dedicated folder (/Apps/YourAppName/). This is the most secure option and users will feel more comfortable granting access.

   Name your app: Enter a name for your app (e.g., Fermentrack Backups or MyBrewery Fermentrack). This name will be visible to users during the authorization process.

   warning

   App names must be unique across all Dropbox apps. If your preferred name is taken, try adding your brewery name or a unique identifier.

5. Click Create app

Step 2: Configure App Permissions

After creating the app, you need to configure its permissions:

1. On your app's settings page, click the Permissions tab

2. Under Files and folders, enable the following permissions:

   • files.metadata.read - View information about files and folders
   • files.content.write - Create, modify, and delete files
   • files.content.read - View content of files (needed for verification)

3. Click Submit to save the permission changes

   important

   After changing permissions, users who have already connected their accounts may need to re-authorize to grant the new permissions.

Step 3: Configure OAuth 2 Settings

1. Go to the Settings tab of your app

2. Under OAuth 2, configure the following:

   Allow public clients (Implicit Grant & PKCE): Leave this disabled (No)

   Redirect URIs: Add the OAuth callback URL for your Fermentrack instance:

   https://your-fermentrack-domain.com/api/cloud_storage/connections/oauth_callback/

   note

   • Replace your-fermentrack-domain.com with your actual domain
   • You must use HTTPS for production deployments
   • For local development, you can use:

     http://localhost:8000/api/cloud_storage/connections/oauth_callback/

   Access token expiration: Use the default setting (short-lived tokens with refresh tokens)

3. Note your App key and App secret from this page - you will need these for the next step

   warning

   Keep your App secret confidential. Never commit it to version control or share it publicly.

Step 4: Configure Fermentrack 2

Add the Dropbox credentials to your Fermentrack 2 environment configuration:

1. Open your .env file (or .envs/.local/.django for local development, or .envs/.production/.django for production)

2. Add the following environment variables:

   # Dropbox Cloud Storage Configuration
   DROPBOX_APP_KEY=your_app_key_here
   DROPBOX_APP_SECRET=your_app_secret_here

   Replace your_app_key_here and your_app_secret_here with the values from your Dropbox app settings.

3. Restart Fermentrack 2 for the changes to take effect:

   For Docker deployments:

   docker-compose -f production.yml down
   docker-compose -f production.yml up -d

   For local development:

   # Stop the running server and start it again
   uv run python manage.py runserver

Step 5: Verify the Configuration

To verify that Dropbox integration is properly configured:

1. Log in to your Fermentrack 2 instance

2. The cloud storage API should now show Dropbox as an available provider. You can verify this by accessing:

   https://your-fermentrack-domain.com/api/cloud_storage/providers/

   You should see a response like:

   [
      {
         "provider_id": "dropbox",
         "display_name": "Dropbox",
         "is_enabled": true
      }
   ]

3. If is_enabled is false or the list is empty, check that:

   • The environment variables are correctly set
   • The application has been restarted after adding the variables
   • There are no typos in the variable names or values

User Experience

Once configured, users can connect their Dropbox accounts through the Fermentrack UI (when the frontend integration is complete) or via the API:

1. Initiate Connection: User clicks "Connect Dropbox" which calls the initiate_auth endpoint

2. Dropbox Authorization: User is redirected to Dropbox to log in and authorize the connection

3. Return to Fermentrack: After authorization, user is redirected back to Fermentrack

4. Connection Complete: The connection is saved and user can now upload backups

Uploading Backups:

Once connected, users can upload any completed backup to their Dropbox. Backups are stored in the app folder (e.g., /Apps/Fermentrack/Fermentrack Backups/).

Troubleshooting

"Provider not enabled" error:

• Verify DROPBOX_APP_KEY and DROPBOX_APP_SECRET are set correctly
• Ensure the application was restarted after setting the variables
• Check for typos in the environment variable names

"Invalid redirect URI" error from Dropbox:

• Verify the redirect URI in your Dropbox app settings exactly matches your Fermentrack URL
• Ensure you're using HTTPS for production
• Check for trailing slashes - they must match exactly

"Invalid state parameter" error:

• The OAuth session may have expired (10 minute timeout)
• Try starting the connection process again
• Ensure cookies are enabled in the user's browser

Token refresh failures:

• The user may need to re-authorize the connection
• Check if the Dropbox app permissions were changed after initial connection
• Verify the app is still active in the Dropbox Developer Portal

Upload failures:

• Check that the user's Dropbox account has sufficient storage space
• Verify the backup file is under 150MB (larger files require chunked upload, not yet implemented)
• Check the Celery worker logs for detailed error messages

Security Considerations

• Token Storage: OAuth tokens are encrypted at rest using Fernet symmetric encryption (via django-fernet-encrypted-fields)

• Token Refresh: Access tokens are short-lived and automatically refreshed using refresh tokens when needed

• App Folder Access: Using "App folder" access type ensures Fermentrack can only access its own folder within users' Dropbox accounts

• CSRF Protection: OAuth state tokens are used to prevent cross-site request forgery attacks during the authorization flow

• Multi-tenant Isolation: Each brewhouse's connections are isolated; users can only access their own connections and backups

API Reference

For developers integrating with the cloud storage API:

List Providers:

GET /api/cloud_storage/providers/

List Connections:

GET /api/cloud_storage/connections/

Initiate OAuth:

POST /api/cloud_storage/connections/initiate_auth/

Request body:

{"provider": "dropbox"}

Complete OAuth:

POST /api/cloud_storage/connections/complete_auth/

Request body:

{
   "provider": "dropbox",
   "code": "authorization_code",
   "state": "state_token"
}

Trigger Upload:

POST /api/cloud_storage/uploads/upload/

Request body:

{
   "connection_id": "uuid",
   "backup_request_id": "uuid"
}

List Uploads:

GET /api/cloud_storage/uploads/