Christian Krakau-Louis
4b46c4baf8
* feat(storage): add Evernote destination * style: apply ruff auto-fix - Auto-formatted code with ruff format - Applied ruff linting fixes with --fix Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> --------- Co-authored-by: Christian Krakau-Louis <christian@Christians-Mac-mini-7.local> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
141 lines
6.5 KiB
Markdown
141 lines
6.5 KiB
Markdown
# 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](#when-the-wizard-appears)
|
||
- [Wizard Steps](#wizard-steps)
|
||
- [Step 1 – Core Infrastructure](#step-1--core-infrastructure)
|
||
- [Step 2 – Security](#step-2--security)
|
||
- [Step 3 – AI Services](#step-3--ai-services)
|
||
- [Skipping and Resuming the Wizard](#skipping-and-resuming-the-wizard)
|
||
- [After the Wizard](#after-the-wizard)
|
||
- [Integration-Specific Setup Pages](#integration-specific-setup-pages)
|
||
- [Advanced: Settings Management](#advanced-settings-management)
|
||
|
||
---
|
||
|
||
## 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](SettingsManagement.md).
|
||
|
||
---
|
||
|
||
## 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:
|
||
- [Dropbox Setup](DropboxSetup.md)
|
||
- [Google Drive Setup](GoogleDriveSetup.md)
|
||
- [OneDrive Setup](OneDriveSetup.md)
|
||
- [Amazon S3 Setup](AmazonS3Setup.md)
|
||
|
||
2. **Configure notifications** — Set up Discord, Telegram, or email alerts:
|
||
- [Notifications Setup](NotificationsSetup.md)
|
||
|
||
3. **Harden for production** — Follow the production readiness checklist:
|
||
- [Production Readiness Guide](ProductionReadiness.md)
|
||
|
||
---
|
||
|
||
## 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](DropboxSetup.md) |
|
||
| Google Drive | `/google-drive-setup` | [GoogleDriveSetup.md](GoogleDriveSetup.md) |
|
||
| OneDrive / SharePoint | `/onedrive-setup` | [OneDriveSetup.md](OneDriveSetup.md) |
|
||
| Amazon S3 | Configured via settings | [AmazonS3Setup.md](AmazonS3Setup.md) |
|
||
| Evernote | Configured via settings | [EvernoteSetup.md](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](ConfigurationGuide.md).
|
||
|
||
> **Precedence order:** Database value → Environment variable → Default
|