Run QOpenBB on Linux or in WSL with Docker Compose. Use the prebuilt Workspace and data API alpha images; no application build tools are needed on the installation host.
Development uses the moving latest tags below. Each published alpha also has a tagged GitHub prerelease with installation files and a manifest of exact image digests. Build and publication status are tracked in GitHub Actions.
- Linux or WSL on x86-64; the alpha images target
linux/amd64. - Docker with the Compose plugin.
- Port 23003 available.
- FMP and FRED API keys.
- The alpha's
compose.yaml, publicdefault.env.sampleasset and matching image references. Save the downloaded environment template locally as.env.samplebefore the commands below.
| Service | Environment variable | Alpha image |
|---|---|---|
| Workspace and application backend | WORKSPACE_IMAGE |
ghcr.io/norandom/qopenbb-workspace:latest |
| OpenBB data API | DATA_API_IMAGE |
ghcr.io/norandom/qopenbb-data-api:latest |
Pull both images together when updating development. Stable versions will use pinned references. For an exact alpha snapshot, use the digest pair in its release manifest.
Published manifest image pair for alpha-43604526965-1:
| Service | Exact published reference |
|---|---|
| workspace | ghcr.io/norandom/qopenbb-workspace@sha256:5e456b5f84383f49eb3e9cbda85ec20c9006e31d18619be715e4743c7cc8b570 |
| data-api | ghcr.io/norandom/qopenbb-data-api@sha256:fa113636cfb8a7df948053cfa39b8473e987ad68ab39ec54c0f079fa2909fac9 |
Both CI jobs, three public release-asset checks and six anonymous pulls by digest, release tag and latest pass. See the Company Research publication evidence.
This alpha retains native locked uv, readable Python, embedded Valkey and the eleven endpoint-backed financial definitions, and adds the native Peer Research declaration and curated Company Research App. Existing company selection, periodic-query provenance and statement-period evidence remain available. The local Company Research acceptance checks source-matched observations, template portability and retained-data recreation on the identified local candidate. Published CI image identities are verified separately; their browser behavior has not been rerun. The owner confirmed the earlier alpha-42188370167-1 on Linux on 2026-11-06; that report does not transfer to this release. Independent server inspection and recovery remain unverified.
The earlier Python-source/Valkey acceptance, login repair and historical chart gallery remain scoped historical evidence. Backup/restore and rollback remain unverified.
Download compose.yaml and the environment template from the alpha release. Save the template as .env.sample in the same directory as Compose. Run these commands there in Linux or WSL:
mkdir -p data/workspace
if [ ! -e .env ]; then
cp .env.sample .env
fi
chmod 600 .envEdit .env:
| Setting | Value |
|---|---|
WORKSPACE_IMAGE |
ghcr.io/norandom/qopenbb-workspace:latest |
DATA_API_IMAGE |
ghcr.io/norandom/qopenbb-data-api:latest |
PUBLIC_URL |
The browser-facing origin: http://127.0.0.1:23003 locally, or your HTTPS domain behind a proxy |
FMP_API_KEY |
Your FMP key |
FRED_API_KEY |
Your FRED key |
OPENBB_ADMIN_EMAIL |
Optional bootstrap administrator email |
OPENBB_ADMIN_PASSWORD |
Optional bootstrap password; choose a strong, unique value |
Keep .env private. AI, Excel and optional provider settings can stay blank. Provider subscriptions determine which datasets your keys can access.
Use your own password or leave the administrator fields blank to generate credentials on first start. Single-quote a password value in .env if it contains $, so Compose does not interpolate it. Avoid exporting the same variables in your shell: exported values take precedence over .env.
Login checks an existing nonempty password unchanged against the stored credential; it does not apply new-password strength rules. Password creation, reset and replacement retain the strength policy: at least eight characters with uppercase, lowercase, a digit and a special character such as !, with no whitespace.
The alpha images are public. No registry login is required.
docker compose config --quiet
docker compose pull
docker compose up -d --no-build
docker compose psOpen http://127.0.0.1:23003 and log in. If you left the administrator fields blank, display the generated credentials in your private terminal:
docker compose exec workspace credentialsDo not share that output. Blank administrator settings reuse persisted bootstrap credentials. Nonempty settings override them at container startup; the initializer creates the configured administrator or updates that account's password.
A fresh account starts without a connected data backend or populated dashboard. The images include the components, but this alpha does not automatically register the bundled backend or instantiate its app templates. Complete this setup once for each Workspace account. The connection and saved dashboards belong to that account and are stored in the bind-mounted Workspace data described under persistence and updates.
- Open Connections, for example http://127.0.0.1:23003/app/connections.
- Select Connect Backend.
- Enter a connection name such as
QOpenBB data API. Set URL to your current Workspace origin followed by/data, for examplehttp://127.0.0.1:23003/data. - Select Test, then add after the catalog test succeeds.
- Open Apps to see the connected backend's templates. The widget library also exposes its eleven native data definitions and the historical gallery widgets. Eligible FMP widgets support selection by company name or symbol.
Use the origin you actually opened in your browser. For a proxied deployment, append /data to that public origin rather than using the example's loopback address. The data API uses the provider keys already supplied through .env.
| App | What it opens |
|---|---|
| QOpenBB starter | Live AAPL company profile and annual income, plus FRED GDP observations |
| QOpenBB Historical Chart Gallery - January 2025 | The populated 36-chart showcase using fixed historical FMP observations |
Select an app card to open its dashboard. The starter demonstrates working components; it is not yet the curated investment-research dashboard planned in the analyst workstream.
The example parameters are defaults, not the scope of the providers:
| Widget | Parameter | Example values |
|---|---|---|
| Company Profile | Symbol | AAPL, MSFT, GOOGL, subject to FMP listing coverage and your entitlement |
| Income | Symbol, Period | AAPL or MSFT; annual or quarter |
| FRED Series | Symbol, date range and frequency controls | GDP or DGS10; enter the FRED series identifier in the field labelled Symbol |
For another component, use Add widgets, choose its definition and fill the required fields. Eight immediate FMP widgets offer Company name autocomplete alongside Symbol; selecting a listing keeps both fields linked. FRED still uses its own series identifier. Its observations retain the selected series' units and frequency conventions; they are not limited to GDP. The generic-widget empty-required-symbol guard remains a separately tracked gap.
Save the dashboard with Ctrl+Shift+S, then reopen it to confirm the selected parameters. The accepted Income journey covers AAPL/MSFT, annual/quarterly periods, visible values, error recovery and save/reopen in a fresh browser context. It does not certify every provider/widget or full research-context reopening after container recreation. Provider entitlement still determines which live data can load.
Return to your saved instance through My Dashboards or its saved URL. Selecting the template in Apps again can create another copy; packaged templates and your saved dashboard instances are separate.
For startup diagnostics:
docker compose logs --tail=100 workspace data-apiReview logs before sharing them for private information. The data API health check checks configuration and installed routes, not live provider access.
The supplied Compose file bind-mounts ./data/workspace on the host to /data in Workspace. It uses no Docker-managed data volume. Keep the same deployment directory and account when updating.
| Keep on the host | Purpose |
|---|---|
data/workspace/ |
Workspace database, account connections, saved dashboards/parameters and generated bootstrap credentials |
.env |
Private provider keys, public origin, administrator overrides and image settings |
compose.yaml |
Service configuration and the relative data bind mount |
Pulling images, restarting or recreating containers, and docker compose down retain that host directory. Deleting/replacing it or resolving the relative bind mount to a different directory gives Workspace fresh state. A different account also has its own connections and dashboards. If an update appears empty, check the account and resolved bind path before redoing onboarding.
The data API has no host data mount; transient provider caches are not a durable market-data store. The historical gallery's fixed data is packaged in the image. Keeping Workspace state does not freeze live provider responses.
The application listens on HTTP port 23003 on all host interfaces; the data API has no published host port.
To update, use the next alpha's matching Compose configuration and both image references, preserving your private settings. Review migration notes and protect existing state before updating.
docker compose pull
docker compose up -d --no-buildKeep OPENBB_ADMIN_EMAIL unchanged and set a nonempty OPENBB_ADMIN_PASSWORD in .env. Recreate only Workspace so it receives the updated environment:
docker compose up -d --no-deps --force-recreate workspaceWait for startup to finish, then log in with that email and the new password. A plain docker compose restart does not load changed .env values. Keep ./data/workspace; no database deletion or dashboard reset is needed.
Disposable Compose acceptance confirmed the same administrator UUID and synthetic dashboard database content survive this update: the new credential succeeds and the old one fails. This verifies retained database state; full analyst dashboard UI reopening after container recreation remains separate acceptance.
Alpha backup/restore and rollback compatibility are not yet verified. To stop containers while keeping the bind-mounted state:
docker compose downOptional remote access is covered in Tips and Tricks. See the roadmap for planned features.