A complete reimplementation of OHDSI ATLAS for cohort definition and analysis, built with Vue 3 and TypeScript.
- Release: ATLAS v3.0.0 is out. See the release notes.
- User manual: ATLAS v3.0 user manual (PDF), also in this repository at
public/docs/atlas-manual.pdfand in the application under User manual in the navigation bar. - Live instance: atlas-preview.ohdsi.org/atlas
ATLAS v3.0 is a reimplementation of OHDSI ATLAS with a focus on:
- Modern web technologies (Vue 3, TypeScript, Vuetify 3)
- Improved user experience and performance
- Comprehensive test coverage
- Modular plugin architecture
- Multi-language support
- Cohort Builder: Define and manage patient cohorts with complex criteria
- Concept Search: Search and browse OMOP CDM concepts
- Concept Sets: Create and manage reusable concept sets
- Data Sources: Visualize CDM data with interactive reports and charts
- Authentication: Secure login with JWT-based authentication
- Internationalization: Multi-language support with dynamic translation loading
Extensible architecture allowing custom plugins to add new features and integrations.
- Frontend Framework: Vue 3.5+ (Composition API)
- UI Components: Vuetify 3.5+ (Material Design)
- Language: TypeScript 5.9+ (strict mode)
- State Management: Pinia 2.1+
- Routing: Vue Router 4.2+
ATLAS v3.0 uses hash-based client routing. Deep links and callback UI URLs should use the #/... form (for example https://localhost/atlas/#/cohorts or https://localhost/atlas/#/oauth/callback).
- Charting: ECharts 6.0+ with vue-echarts
- Validation: Zod (runtime validation)
- Build Tool: Vite 7.3+
- Backend: WebAPI 3.0 (Java 21, Spring Boot 3.5)
- Cache: TrexSQL (DuckDB-backed query cache, loaded as a WebAPI plugin)
A working ATLAS v3.0 deployment has three independent components:
- A relational database holding the WebAPI schema, the OMOP CDM schemas you want to analyse, and any results schemas. PostgreSQL is the simplest choice and the one the development
docker-compose.ymlships with; Microsoft SQL Server, Oracle, Amazon Redshift, and Snowflake are all supported by WebAPI. - The WebAPI service — a Java/Spring application that exposes the REST endpoints ATLAS talks to, executes cohort SQL against the configured CDM sources, and runs Flyway migrations against its own schema on first boot.
- The ATLAS v3.0 frontend — a Vue 3 single-page application, served either by the Vite development server or as a static bundle behind a reverse proxy.
ATLAS v3.0 requires WebAPI v3.0. The 2.x line of WebAPI that earlier ATLAS releases use — and that ships with OHDSI Broadsea — is not compatible. WebAPI v3.0 is developed on the
masterbranch; the olderwebapi-3.0branch is no longer updated.docker-compose.ymlruns the releasedohdsi/webapi:3.0.0image; the developmentdocker-compose.dev.ymlbuilds onghcr.io/ohdsi/webapi:dev.
- Docker and Docker Compose v2 (the fastest path), or for native installs: PostgreSQL 12+, JDK 21, Maven 3.9+, Node.js 20.19+ (or 22.12+) and
npm, plus Caddy to serve the prebuilt frontend. - Git.
- Roughly 4 GB of free disk for container images and the WebAPI Flyway baseline.
- A WebAPI build from the v3.0 line: the released image
ohdsi/webapi:3.0.0, the development imageghcr.io/ohdsi/webapi:dev, or a local build of themasterbranch.
The repository ships a docker-compose.yml that runs the released ATLAS v3.0.0 and WebAPI v3.0.0 images: Postgres with the Eunomia demo database, WebAPI, a database initialiser, and the frontend behind Caddy with a self-signed certificate. Nothing is built locally:
git clone https://github.com/OHDSI/Atlas3.git
cd Atlas3
docker compose upThe first boot takes a few minutes while WebAPI runs Flyway migrations and the atlasdb/ scripts seed the default users.
docker-compose.dev.yml builds the frontend from your checkout and runs the WebAPI development image ghcr.io/ohdsi/webapi:dev, pinned by digest, with a pinned TrexSQL release (docker/webapi/Dockerfile):
cp .env.example .env # optional; see "Using other host ports" below
docker compose -f docker-compose.dev.yml up --build.env.example also turns on the optional Pythia assistant, which needs a Bedrock key in AWS_BEARER_TOKEN_BEDROCK. Set VITE_BAO_AGENT_ENABLED=false in .env to leave it off.
The two stacks use the same container names and ports, so run one at a time (docker compose down first). They keep their data in separate volumes, because a database migrated by the WebAPI development image cannot be opened by the released WebAPI.
When the stack is healthy:
- ATLAS v3.0 — https://localhost (accept the self-signed certificate; sign in as
admin/admin) - WebAPI — http://localhost:8080/WebAPI/info
- PostgreSQL —
localhost:5433(in-container port 5432)
If ports 80 or 443 are already in use on your machine, set the host ports in .env (both stacks read it) and add the matching origins to WebAPI's CORS allow-list. Without the CORS change, sign-in and other POST requests fail:
ATLAS3_HTTP_PORT=8081
ATLAS3_HTTPS_PORT=4431
SECURITY_CORS_ALLOWED_ORIGINS=http://localhost:8081,https://localhost:4431Then open https://localhost:4431. Caddy's automatic HTTP→HTTPS redirect assumes port 443, so use the HTTPS URL directly.
The default
POSTGRES_PASSWORDin the compose file ismypass— a placeholder for local development. SetPOSTGRES_PASSWORDin a.envfile (or your secrets manager) before running anywhere a hostile network can reach. The default user credentials are seeded byatlasdb/; change them before any non-local use.
The compose file already enables the TrexSQL query cache (TREXSQL_ENABLED=true, TREXSQL_CACHE_PATH=/data/cache, HOME=/data) and persists it on the atlas3-webapi-data named volume. Live patient counts in the cohort builder and the inclusion-rule rail only appear once TrexSQL is enabled and a per-source patient cache has been built — trigger the first build from Configuration → Cache management after login.
If you already have a WebAPI running on http://localhost:8080 (the compose stack works, as does a native install), you can run the Vue dev server directly:
npm install
npm run dev # Vite on http://localhost:5173, proxies /WebAPI to :8080
npm run build # Production bundle in dist/
npm run preview # Serve the production bundle locallyThe dev server proxies /WebAPI to http://localhost:8080. To use a different backend, set WEBAPI_URL, for example WEBAPI_URL=https://example.org npm run dev. A deployed bundle reads the WebAPI address at runtime from config-local.json next to index.html (api.url); see public/config-local.example.json.
Release tags publish the built frontend to npmjs as atlas3. To try it against a running WebAPI with nothing but Node.js:
npx atlas3 --webapi http://localhost:8080This serves ATLAS at http://localhost:4180/atlas/ and forwards /WebAPI to the given address, which can be a remote WebAPI (https://example.org/WebAPI). Because the browser only talks to this one address, WebAPI's CORS settings don't matter. --port and --host change where it listens. It is meant for local use and evaluation: it has no HTTPS or caching.
For a real deployment, serve the package with the bundled Caddyfile, the same one the Docker image uses. With a WebAPI on localhost:8080 and Caddy installed:
npm install atlas3
ATLAS_DIST=node_modules/atlas3/dist WEBAPI_HOST=localhost caddy run --config node_modules/atlas3/CaddyfileThen open https://localhost/atlas/. Caddy serves the bundle and proxies /WebAPI to WEBAPI_HOST:WEBAPI_PORT (port 8080 by default), so the browser needs no CORS setup. The certificate comes from Caddy's local CA; run caddy trust once to stop the browser warning. To listen elsewhere, set CADDY_HOSTNAME, for example CADDY_HOSTNAME=localhost:8443, which also avoids needing root for port 443. The package ships the same dist/config-local.json as the Docker image, with database sign-in enabled. To change auth providers or other settings, edit that file, using dist/config-local.example.json for reference, and reapply your changes after upgrading the package.
The default DB-auth path expects a row in the webapi.auth_user table whose password column is a bcrypt hash of the chosen plaintext. The compose seed scripts in atlasdb/ create two users, admin / admin and ohdsi / ohdsi. To add more users, either insert rows into webapi.auth_user directly or, if your deployment exposes LDAP/OAuth/SAML/OIDC, configure the corresponding SECURITY_AUTH_* properties on the WebAPI side.
After signing in, an administrator should:
- Visit Configuration → Permissions and set up the role bundles your organisation needs.
- Confirm the Data Sources page lists each connected CDM and that its dashboard renders without errors.
- Run a small smoke-test cohort against each source to validate end-to-end execution.
ATLAS v3.0 has comprehensive test coverage across multiple test types:
# Run unit tests (Vitest, watch mode by default)
npm run test:unit
# Unit tests with coverage report
npm run test:coverage
# Run E2E tests (headless)
npm run test:e2e
# Run E2E tests with visible browser
npm run test:e2e:headed
# Run E2E tests in interactive UI mode
npm run test:e2e:ui
# View last E2E test report
npm run test:e2e:report
# Run the visual-comparison subset only
npm run test:visual
# Type-check, lint, i18n key check, unit tests, and production build
npm run check-all-
E2E Tests (
tests/e2e/): End-to-end tests using Playwright- Auth flow tests
- Concept search and management
- Data source reports
- Visual comparison tests
-
Unit Tests (
tests/unit/): Unit tests using Vitest- Store tests (Pinia)
- Service tests
- Utility function tests
- Composable tests
-
Component Tests (
tests/component/): Component tests using Vitest + Vue Test Utils- Chart components
- UI components
- Form components
ATLAS v3.0 supports a plugin architecture based on single-spa and SystemJS. Reference plugins live in plugins-dev/.
- WebAPI — Backend API service; ATLAS v3.0 requires WebAPI v3.0 from the
masterbranch - trex — TrexSQL query cache; loaded into WebAPI as a runtime plugin
For issues and questions, please use the GitHub issue tracker.