Skip to content

Setup Wizard Guide

DocuElevate includes a first-run Setup Wizard that guides you through configuring the essential settings needed for the system to operate. The wizard is the recommended starting point for any new installation.

Table of Contents

When the Wizard Appears

The wizard is shown automatically when DocuElevate detects that critical settings are still at their insecure defaults. Specifically, it triggers when either of the following is true:

  • SESSION_SECRET is still the built-in insecure placeholder
  • ADMIN_PASSWORD is absent or set to a common placeholder value (changeme, admin, etc.)

Once both values have been configured — whether through the wizard or through environment variables — the wizard will no longer be shown on the home page.

Tip: If you pre-populate all settings via environment variables before the first launch, the wizard will be skipped automatically.

Wizard Steps

The wizard is divided into three focused steps, accessible at /setup?step=<N>.

Step 1 – Core Infrastructure

Configure the services that DocuElevate depends on at the infrastructure level.

Setting Description Default
DATABASE_URL Database connection string. SQLite is fine for development; PostgreSQL is recommended for production. sqlite:///./app/database.db
REDIS_URL Redis connection URL used by the Celery task queue. redis://localhost:6379/0
WORKDIR Filesystem path where documents are staged during processing. Must be writable by the API and Worker containers. /workdir
GOTENBERG_URL URL of the Gotenberg service used for document-to-PDF conversion. http://gotenberg:3000

For Docker Compose deployments the defaults work out of the box. You only need to change these if you are using external services or a custom topology.

Step 2 – Security

Configure authentication and session security.

Setting Description Notes
SESSION_SECRET Secret key used to sign and encrypt session cookies. Minimum 32 characters. Click Auto-generate to let the wizard create a cryptographically secure value for you.
ADMIN_USERNAME Username for the built-in admin account. Defaults to admin.
ADMIN_PASSWORD Password for the built-in admin account. Required. Must not be a placeholder value.

Security note: The auto-generated session secret is a 64-character hex string (32 bytes of entropy). Store it somewhere safe — it cannot be recovered if lost. If you rotate the secret, all existing sessions will be invalidated.

Step 3 – AI Services

Configure the AI provider used for metadata extraction and document understanding.

Setting Description Notes
AI_PROVIDER The AI backend to use. Options: openai, azure, anthropic, gemini, ollama, openrouter, portkey, litellm
OPENAI_API_KEY API key for OpenAI, Azure OpenAI, or LiteLLM-compatible endpoints. Not required when using Ollama.
OPENAI_MODEL Default model name (e.g. gpt-4o-mini, claude-3-5-sonnet-20241022, llama3.2). Used when AI_MODEL is not explicitly set.

DocuElevate can operate without an AI provider — metadata extraction tasks will be skipped. You can always add AI credentials later through the Settings page.

Skipping and Resuming the Wizard

Skipping

If you are an advanced user who has already configured settings via environment variables, you can skip the wizard by clicking Skip for now or by visiting:

GET /setup/skip

This writes a _setup_wizard_skipped marker to the database so the wizard is not re-shown automatically.

Resuming

To re-run the wizard after skipping it:

  1. Navigate to Settings → System and click Re-run Setup Wizard, or
  2. Visit /setup/undo-skip directly.

This removes the skip marker and redirects you to Step 1.

After the Wizard

Once all three steps are complete you are redirected to the home page with a ?setup=complete confirmation banner. At that point DocuElevate is operational with the core settings in place.

Recommended next steps:

  1. Configure a storage destination — Set up at least one output destination where processed documents will be sent:
  2. Dropbox Setup
  3. Google Drive Setup
  4. OneDrive Setup

  5. Amazon S3 Setup

  6. Configure notifications — Set up Discord, Telegram, or email alerts:

  7. Notifications Setup

  8. Harden for production — Follow the production readiness checklist:

  9. Production Readiness Guide

Integration-Specific Setup Pages

Several cloud storage integrations include their own guided configuration pages that walk you through the OAuth app registration and token exchange process:

Integration Setup URL Guide
Dropbox /dropbox-setup DropboxSetup.md
Google Drive /google-drive-setup GoogleDriveSetup.md
OneDrive / SharePoint /onedrive-setup OneDriveSetup.md
Amazon S3 Configured via settings AmazonS3Setup.md
Evernote Configured via settings EvernoteSetup.md

These pages are accessed after the main Setup Wizard is complete and are independent wizard flows specific to each integration.

Advanced: Settings Management

All settings — including those configured through the wizard — can be updated at any time through the Settings page (/settings). Settings saved via the wizard are stored in the database and take precedence over the corresponding environment variables.

For the full list of every available configuration parameter, see the Configuration Guide.

Precedence order: Database value → Environment variable → Default