Skip to content

WebAPI Installation Guide

Jump to bottom Edit New page
Chris Knoll edited this page Sep 22, 2026 · 27 revisions

WebAPI Installation Guide

Overview

This guide describes how to set up a Windows development environment for OHDSI/WebAPI.

WebAPI is a Java-based Spring Boot application. This guide describes how to set up the software required to build, run, and debug WebAPI locally.

WebAPI can be run directly from Visual Studio Code during development or packaged as a WAR file and deployed to Apache Tomcat 11.

These instructions are intended to provide a basic development environment on a Windows operating system. Other deployment options and more enterprise-ready environments are available through projects such as:

Database provisioning, production deployment, and other advanced configuration topics are covered in separate guides.

Software

The following software is recommended for WebAPI development:

  • Java Development Kit (JDK) 21 - Eclipse Temurin from Adoptium
  • Git
  • TortoiseGit (optional)
  • Visual Studio Code
  • Visual Studio Code Extension Pack for Java
  • PostgreSQL 16
  • Apache Tomcat 11 - required when deploying WebAPI as a WAR

Install Java Development Kit 21

WebAPI requires JDK 21.

For development, we recommend the Eclipse Temurin JDK provided by the Eclipse Adoptium project.

Download the latest JDK 21 release from:

Download Eclipse Temurin JDK 21

For Windows development, select:

  • Operating System: Windows
  • Architecture: x64
  • Package Type: JDK
  • Version: 21 (LTS)

The Windows MSI installer may be used to install the JDK.

During installation, ensure that the option to set the JAVA_HOME environment variable is enabled.

After installation, open a new PowerShell window and verify the installation:

java -version
javac -version
$env:JAVA_HOME

Both java and javac should report Java 21.

JAVA_HOME should point to the root directory of the installed JDK and not its bin directory.

For example:

C:\Program Files\Eclipse Adoptium\jdk-21.x.x.x-hotspot

Note: If Visual Studio Code was running while the JDK was installed, completely exit and restart Visual Studio Code so that it receives the updated PATH and JAVA_HOME environment variables.

Install Git

Git is required to obtain and work with the WebAPI source code.

Download and install Git for Windows:

Download Git for Windows

After installation, open PowerShell and verify Git is available:

git --version

Install TortoiseGit (Optional)

Developers who prefer Windows Explorer integration for Git can optionally install TortoiseGit.

Download TortoiseGit from:

Download TortoiseGit

TortoiseGit provides Windows Explorer integration for common Git operations.

Git for Windows should be installed before installing TortoiseGit.

Install Visual Studio Code

Visual Studio Code is the recommended development environment for WebAPI.

Download Visual Studio Code from:

Download Visual Studio Code

Install Visual Studio Code using the options appropriate for your development environment.

Install the Visual Studio Code Java Extensions

Start Visual Studio Code and open the Extensions view using the Activity Bar or:

Ctrl+Shift+X

Search for and install:

Extension Pack for Java

published by Microsoft.

The Extension Pack for Java installs the extensions required for Java development, including:

  • Language Support for Java(TM) by Red Hat
  • Debugger for Java
  • Test Runner for Java
  • Maven for Java
  • Project Manager for Java

You do not need to install these extensions individually.

If Java is not detected after installing the extension pack, verify JAVA_HOME from the Visual Studio Code terminal:

$env:JAVA_HOME
java -version
javac -version

If Java works from a newly opened Windows PowerShell but is not available within Visual Studio Code, completely exit and restart Visual Studio Code.

You can also examine the JDK detected by Visual Studio Code using the Command Palette:

Ctrl+Shift+P

and selecting:

Java: Configure Java Runtime

JDK 21 should appear as an installed Java runtime.

Install PostgreSQL 16

WebAPI uses PostgreSQL for its configuration database.

PostgreSQL 16 is the recommended PostgreSQL version for WebAPI development.

Download and install the latest PostgreSQL 16.x release:

Download PostgreSQL for Windows

Select the latest available PostgreSQL 16.x release for Windows x86-64.

The standard PostgreSQL Windows installer includes the PostgreSQL database server and pgAdmin.

During installation, the default options are appropriate for most development environments.

For a typical local development environment:

  • Port: Use the default PostgreSQL port, 5432.
  • Locale: Use the default locale.
  • PostgreSQL administrator: The standard administrative account is postgres.
  • Password: Select a password for the postgres administrative account and keep track of it.

You may use the default installation and data directories or select locations appropriate for your development environment.

Keep track of the following information because it will be required when configuring the WebAPI database and WebAPI application.yaml:

  • PostgreSQL installation directory
  • PostgreSQL data directory
  • PostgreSQL server/host name (typically localhost for a local installation)
  • PostgreSQL port (typically 5432)
  • postgres administrative account password

Creation of the WebAPI database, schemas, application accounts, and database permissions is covered in the PostgreSQL database setup guide.

Install Apache Tomcat 11

WebAPI can be run directly from Visual Studio Code during development. Developers who want to deploy and run WebAPI as a WAR should also install Apache Tomcat 11.

Download the latest Tomcat 11 release from:

Download Apache Tomcat 11

Download the appropriate distribution for your operating system. For Windows development, the ZIP distribution provides a simple installation: extract the archive to a directory of your choice and keep track of this location.

The remainder of this guide refers to the Tomcat installation directory as:

<TOMCAT_HOME>

For example, if Tomcat was extracted to:

C:\tomcat

then <TOMCAT_HOME> refers to C:\tomcat.

Clone the WebAPI Project

Create a directory where you keep your Git projects and clone the WebAPI repository.

For example:

git clone https://github.com/OHDSI/WebAPI.git

The WebAPI repository is available at:

OHDSI/WebAPI

Check Out a Released Version

For development against a particular WebAPI release, you can check out the corresponding Git tag.

Available WebAPI releases can be found at:

WebAPI Releases

For example:

git checkout refs/tags/<VERSION>

Replace <VERSION> with the release tag you want to use.

Developers actively contributing to WebAPI may instead work from the appropriate development branch.

Open WebAPI in Visual Studio Code

Open Visual Studio Code and open the WebAPI repository.

The Java Extension Pack will detect the Java and Maven project configuration and begin importing the project.

The initial project import may take some time while Maven dependencies are downloaded and the Java project is compiled.

Allow the Java project initialization to complete before attempting to run WebAPI.

Configure WebAPI

WebAPI configuration is supplied at runtime using an external Spring Boot configuration file.

Environment-specific configuration is not built into WebAPI using Maven profiles.

Building WebAPI and configuring a WebAPI environment are separate operations. The same WebAPI build or WAR can be run in different environments by supplying the appropriate external configuration file.

For development, create an application.yaml file outside of the WebAPI Git repository. This file contains the configuration for your local WebAPI environment.

Important: Configuration files may contain database passwords, authentication secrets, and other sensitive information. Do not commit local application.yaml files containing credentials to the WebAPI source repository.

In the examples below, values enclosed in angle brackets, such as <HOST> and <PASSWORD>, are placeholders. Replace these values with the appropriate settings for your environment.

Configure the WebAPI Database

The datasource section defines the PostgreSQL database used by WebAPI for its configuration data.

A typical PostgreSQL configuration looks like:

datasource:
  dialect: postgresql
  dialect.source: postgresql
  driverClassName: org.postgresql.Driver
  ohdsi.schema: <WEBAPI_SCHEMA>
  url: jdbc:postgresql://<HOST>:<PORT>/<WEBAPI_DATABASE>
  username: <WEBAPI_APP_USER>
  password: <WEBAPI_APP_PASSWORD>

For a local PostgreSQL installation using the standard PostgreSQL port, the JDBC URL will typically look similar to:

url: jdbc:postgresql://localhost:5432/ohdsi

The important settings are:

  • datasource.url - JDBC connection URL for the WebAPI configuration database.
  • datasource.username - Database account used by WebAPI during normal operation.
  • datasource.password - Password for the WebAPI application database account.
  • datasource.ohdsi.schema - Schema containing the WebAPI configuration tables.
  • datasource.driverClassName - PostgreSQL JDBC driver.
  • datasource.dialect and datasource.dialect.source - Database dialect used by WebAPI.

The WebAPI application database account should be separate from the administrative account used to perform database migrations.

Configure Flyway

WebAPI uses Flyway to create and upgrade its configuration database schema.

The Flyway account requires sufficient database privileges to create and modify the database objects required by WebAPI.

Configure the Flyway connection under spring.flyway:

spring:
  flyway:
    url: ${datasource.url}
    user: <WEBAPI_ADMIN_USER>
    password: <WEBAPI_ADMIN_PASSWORD>
    out-of-order: true

The expression:

url: ${datasource.url}

instructs Spring to use the JDBC URL defined earlier under datasource.url.

The Flyway administrative credentials are intentionally separate from the credentials WebAPI uses during normal operation.

Configure Authentication

WebAPI supports multiple authentication mechanisms. Authentication methods can be enabled as appropriate for the development environment.

The following sections provide examples for database authentication and Google OAuth/OIDC authentication.

Database Authentication

Database authentication can be enabled using:

security:
  auth:
    db:
      enabled: true
      lockout-policy:
        max-failed-attempts: 5
        lockout-duration: 30m
      datasource:
        driver-class-name: org.postgresql.Driver
        url: jdbc:postgresql://<HOST>:<PORT>/<SECURITY_DATABASE>
        username: <SECURITY_DB_USER>
        password: <SECURITY_DB_PASSWORD>
        schema: <SECURITY_SCHEMA>

The database authentication datasource contains the user accounts used to authenticate to WebAPI.

For development environments, this database may reside on the same PostgreSQL server as the WebAPI configuration database.

The lockout policy in this example locks an account after five failed authentication attempts:

lockout-policy:
  max-failed-attempts: 5
  lockout-duration: 30m

Google Authentication

Google OAuth/OIDC authentication can be enabled under security.auth.oauth.google.

For example:

security:
  auth:
    oauth:
      callback:
        ui: http://localhost/Atlas3/#/oauth/callback
      google:
        enabled: true
        apiKey: <GOOGLE_CLIENT_ID>
        apiSecret: <GOOGLE_CLIENT_SECRET>

Replace <GOOGLE_CLIENT_ID> and <GOOGLE_CLIENT_SECRET> with the credentials for your Google OAuth application.

The UI callback identifies the Atlas location WebAPI should return the browser to after authentication. Adjust this URL to match the Atlas instance used by your development environment.

The Google OAuth application must also be configured with the WebAPI OAuth redirect/callback URI appropriate for the WebAPI server. The protocol (http or https), hostname, port, and callback path must match the URI configured with Google.

Important: OAuth client secrets should be treated as credentials and should not be committed to source control.

Configure CORS

When Atlas and WebAPI are running from different origins during development, those origins must be allowed by WebAPI's CORS configuration.

For example:

security:
  cors:
    enabled: true
    allowed-origins: http://localhost, http://localhost:8080, http://localhost:5173

The exact origins depend on how Atlas and WebAPI are being run.

For example, an Atlas development server running through Vite may use:

http://localhost:5173

Only add origins that are required by your development environment.

Configure Default Roles

Default WebAPI roles can be configured using:

security:
  defaultRoles: "public,Atlas users"

Adjust the roles as appropriate for your environment.

Configure Sessions

WebAPI session expiration and cleanup can be configured using:

security:
  sessions:
    expiration: 8h
    cleanup-interval: 1h

This example configures authenticated sessions to expire after eight hours and performs session cleanup hourly.

Management Endpoints

Spring Boot management endpoints can be exposed for development and monitoring.

For example:

management:
  endpoints:
    web:
      exposure:
        include: health,metrics,caches

This exposes the health, metrics, and caches management endpoints.

JPA Configuration

The following JPA configuration is recommended:

spring:
  jpa:
    open-in-view: false

Debug Logging

Additional logging can be enabled when troubleshooting WebAPI.

For example:

logging:
  level:
    org.ohdsi.webapi.security.authz: DEBUG

Additional Spring and Hibernate logging can be useful when diagnosing database problems:

logging:
  level:
    org.ohdsi.webapi.security.authz: DEBUG
    # org.springframework.jdbc: DEBUG
    # org.hibernate.SQL: DEBUG
    # org.hibernate.orm.jdbc.bind: TRACE
    # org.hibernate.stat: DEBUG

These settings can produce substantial logging and generally should only be enabled while troubleshooting.

Example Development Configuration

Putting the major settings together, a development application.yaml might look similar to the following:

datasource:
  dialect: postgresql
  dialect.source: postgresql
  driverClassName: org.postgresql.Driver
  ohdsi.schema: <WEBAPI_SCHEMA>
  url: jdbc:postgresql://<HOST>:<PORT>/<WEBAPI_DATABASE>
  username: <WEBAPI_APP_USER>
  password: <WEBAPI_APP_PASSWORD>

security:
  auth:
    db:
      enabled: true
      lockout-policy:
        max-failed-attempts: 5
        lockout-duration: 30m
      datasource:
        driver-class-name: org.postgresql.Driver
        url: jdbc:postgresql://<HOST>:<PORT>/<SECURITY_DATABASE>
        username: <SECURITY_DB_USER>
        password: <SECURITY_DB_PASSWORD>
        schema: <SECURITY_SCHEMA>

    oauth:
      callback:
        ui: http://localhost/Atlas3/#/oauth/callback
      google:
        enabled: true
        apiKey: <GOOGLE_CLIENT_ID>
        apiSecret: <GOOGLE_CLIENT_SECRET>

  cors:
    enabled: true
    allowed-origins: http://localhost, http://localhost:8080, http://localhost:5173

  defaultRoles: "public,Atlas users"

  sessions:
    expiration: 8h
    cleanup-interval: 1h

spring:
  jpa:
    open-in-view: false

  flyway:
    url: ${datasource.url}
    user: <WEBAPI_ADMIN_USER>
    password: <WEBAPI_ADMIN_PASSWORD>
    out-of-order: true

management:
  endpoints:
    web:
      exposure:
        include: health,metrics,caches

logging:
  level:
    org.ohdsi.webapi.security.authz: DEBUG
    # org.springframework.jdbc: DEBUG
    # org.hibernate.SQL: DEBUG
    # org.hibernate.orm.jdbc.bind: TRACE
    # org.hibernate.stat: DEBUG

This is an example development configuration rather than a complete production configuration. Enable only the authentication mechanisms and diagnostic settings required for your environment.

Run and Debug WebAPI Using Visual Studio Code

Visual Studio Code can run and debug WebAPI directly using the Java debugger.

WebAPI's main class is:

org.ohdsi.webapi.WebApi

Configure a Visual Studio Code Workspace

When using a Visual Studio Code workspace file, a launch configuration can be added directly to the workspace.

For example:

{
    "folders": [
        {
            "path": "C:/git/WebAPI"
        }
    ],
    "launch": {
        "version": "0.2.0",
        "configurations": [
            {
                "type": "java",
                "name": "WebAPI",
                "request": "launch",
                "mainClass": "org.ohdsi.webapi.WebApi",
                "projectName": "WebAPI",
                "vmArgs": "-Dspring.config.additional-location=file:C:/dev/webapi/application.yaml"
            }
        ]
    }
}

Replace:

C:/git/WebAPI

with the location of your WebAPI repository.

Replace:

C:/dev/webapi/application.yaml

with the location of your external WebAPI configuration file.

The JVM argument:

-Dspring.config.additional-location=file:C:/dev/webapi/application.yaml

instructs Spring Boot to load the specified external configuration when WebAPI starts.

Using launch.json Instead

If you open the WebAPI directory directly instead of using a Visual Studio Code workspace, launch configurations can be stored in:

.vscode/launch.json

For example:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "java",
            "name": "WebAPI",
            "request": "launch",
            "mainClass": "org.ohdsi.webapi.WebApi",
            "projectName": "WebAPI",
            "vmArgs": "-Dspring.config.additional-location=file:C:/dev/webapi/application.yaml"
        }
    ]
}

Start WebAPI from Visual Studio Code

Once PostgreSQL and the WebAPI configuration database have been configured and an appropriate application.yaml has been created, WebAPI can be started directly from Visual Studio Code.

Open the Run and Debug view:

Ctrl+Shift+D

Select:

WebAPI

and start the application.

WebAPI will run as a Spring Boot application using the external configuration specified by the launch configuration.

Running WebAPI through Visual Studio Code allows developers to:

  • Set Java breakpoints
  • Step through WebAPI code
  • Inspect variables
  • View application logs in the Visual Studio Code console
  • Stop and restart WebAPI during development

Build and Deploy WebAPI Using Tomcat

In addition to running WebAPI directly from Visual Studio Code, WebAPI can be packaged as a WAR file and deployed to Apache Tomcat 11.

The WAR does not contain environment-specific WebAPI configuration. The external configuration is supplied to WebAPI at runtime.

Build the WebAPI WAR

From the root of the WebAPI repository, build WebAPI using Maven:

mvn clean package -DskipUnitTests -DskipITtests

The build creates:

target\WebAPI.war

The WAR does not need to be rebuilt when changing environment-specific database or authentication configuration. Those settings are supplied through the external configuration file when WebAPI starts.

Configure the Tomcat Manager

For development purposes, the Tomcat Manager application provides a convenient way to deploy the WebAPI WAR.

Navigate to:

<TOMCAT_HOME>\conf

and edit:

tomcat-users.xml

Add a user with the manager-gui role inside the <tomcat-users> element:

<role rolename="manager-gui"/>
<user username="tomcat"
      password="<TOMCAT_MANAGER_PASSWORD>"
      roles="manager-gui"/>

Replace <TOMCAT_MANAGER_PASSWORD> with a password appropriate for your local development environment.

Note: These instructions are intended for a local development environment. Production Tomcat installations should follow the appropriate Tomcat security and deployment practices rather than exposing the Manager application using a simple development account.

Configure the Tomcat Manager WAR Upload Size

The WebAPI WAR may exceed the default upload size accepted by the Tomcat Manager.

Edit:

<TOMCAT_HOME>\webapps\manager\WEB-INF\web.xml

Find the <multipart-config> section:

<multipart-config>
    <!-- 50MB max -->
    <max-file-size>52428800</max-file-size>
    <max-request-size>52428800</max-request-size>
    <file-size-threshold>0</file-size-threshold>
</multipart-config>

Increase the maximum file and request sizes. For example:

<multipart-config>
    <!-- 150MB max -->
    <max-file-size>154857600</max-file-size>
    <max-request-size>154857600</max-request-size>
    <file-size-threshold>0</file-size-threshold>
</multipart-config>

This allows the Tomcat Manager to accept a WebAPI WAR up to approximately 150 MB.

Configure External WebAPI Configuration for Tomcat

When deploying WebAPI to Tomcat, Tomcat must be configured with the location of the external WebAPI configuration file.

Tomcat supports per-application configuration using a Context XML file.

Create the following directory if it does not already exist:

<TOMCAT_HOME>\conf\Catalina\localhost

Create a file named:

WebAPI.xml

in that directory.

The complete path will therefore be:

<TOMCAT_HOME>\conf\Catalina\localhost\WebAPI.xml

Configure the Spring Boot spring.config.additional-location property using a Tomcat environment entry:

<Context>
    <Environment name="spring.config.additional-location"
                 value="file:/E:/webapi/config/webapi-local-config.yaml"
                 type="java.lang.String"
                 override="false"/>
</Context>

Replace:

E:/webapi/config/webapi-local-config.yaml

with the location of your external WebAPI configuration file.

The spring.config.additional-location environment entry performs the same basic function as the JVM argument used when launching WebAPI from Visual Studio Code:

-Dspring.config.additional-location=file:C:/dev/webapi/application.yaml

In both cases, the WebAPI configuration remains outside of the application itself. This allows the same WebAPI WAR to be deployed in different environments using different external configuration files.

Important: The external configuration file may contain database passwords, OAuth secrets, and other credentials. Protect this file appropriately and do not store environment-specific credentials inside the WebAPI WAR or source repository.

Context File Name

The Context XML filename determines the context path under which Tomcat deploys the application.

Using:

<TOMCAT_HOME>\conf\Catalina\localhost\WebAPI.xml

corresponds to the /WebAPI application context.

This matches the normal WebAPI URL:

http://localhost:8080/WebAPI

Start Tomcat

For development purposes, Tomcat can be started directly from the command line.

Open a command prompt or PowerShell window and navigate to:

<TOMCAT_HOME>\bin

Start Tomcat in the foreground using:

catalina.bat run

Running Tomcat in the foreground is useful during development because WebAPI startup messages are immediately visible in the console.

Alternatively, output can be redirected to a log file:

catalina.bat run > ..\logs\webapi.log 2>&1

The resulting log can be found at:

<TOMCAT_HOME>\logs\webapi.log

Deploy WebAPI Using the Tomcat Application Manager

After Tomcat has started, open:

http://localhost:8080/manager

Log in using the Tomcat Manager account configured earlier.

At the bottom of the Manager page, locate:

WAR file to deploy

Select:

<WebAPI repository>\target\WebAPI.war

and click Deploy.

Tomcat will deploy WebAPI under:

/WebAPI

During application startup, WebAPI will load its runtime configuration from the external configuration file specified by:

<TOMCAT_HOME>\conf\Catalina\localhost\WebAPI.xml

Verify WebAPI

Whether WebAPI was started directly from Visual Studio Code or deployed to Tomcat, monitor the application output while WebAPI starts.

A successful startup will include a Spring Boot message similar to:

Started WebApi in ... seconds

During the first startup against a newly configured WebAPI database, Flyway will create the required WebAPI database objects using the administrative credentials configured under:

spring:
  flyway:
    user: <WEBAPI_ADMIN_USER>
    password: <WEBAPI_ADMIN_PASSWORD>

Once startup completes, verify WebAPI by navigating to:

http://localhost:8080/WebAPI/info

The endpoint should return information about the running WebAPI instance, including its version.

You can also use pgAdmin or another PostgreSQL database tool to verify that the WebAPI tables were created in the configured WebAPI schema.

Once WebAPI is running, the next step is to configure connections to one or more OMOP Common Data Model databases.

See the CDM Configuration documentation for details.

Troubleshooting

Visual Studio Code Cannot Find Java

First verify Java from a new PowerShell window:

java -version
javac -version
$env:JAVA_HOME

If these commands work in PowerShell but not within Visual Studio Code, completely exit Visual Studio Code and restart it.

Visual Studio Code inherits environment variables when it starts. If the JDK was installed or JAVA_HOME was changed while Visual Studio Code was already running, the running Visual Studio Code process may still have the previous environment.

You can inspect the Java runtimes detected by Visual Studio Code using:

Ctrl+Shift+P

and selecting:

Java: Configure Java Runtime

Errors During WebAPI Startup

If WebAPI reports database connection errors during startup, verify the PostgreSQL connection information in the external application.yaml.

In particular, verify:

  • Database host
  • Database port
  • Database name
  • Application username and password
  • Flyway/admin username and password
  • WebAPI schema

It is recommended that database connectivity and permissions be verified independently before troubleshooting WebAPI itself.

Database Migration Errors

WebAPI uses the application database credentials during normal operation and the Flyway administrative credentials when applying database migrations.

If WebAPI connects to PostgreSQL but fails while creating or migrating tables, verify that the account configured under:

spring:
  flyway:
    user: <WEBAPI_ADMIN_USER>
    password: <WEBAPI_ADMIN_PASSWORD>

has the database and schema privileges required to perform the migration.

If WebAPI starts successfully but later reports permission errors when accessing tables, verify that the WebAPI application account has the required privileges on the WebAPI schema and its tables.

External Configuration Is Not Being Loaded

If WebAPI starts but appears to be ignoring the external configuration, verify the configuration mechanism being used.

When running from Visual Studio Code, verify:

"vmArgs": "-Dspring.config.additional-location=file:C:/dev/webapi/application.yaml"

When running under Tomcat, verify:

<TOMCAT_HOME>\conf\Catalina\localhost\WebAPI.xml

contains:

<Environment name="spring.config.additional-location"
             value="file:/E:/webapi/config/webapi-local-config.yaml"
             type="java.lang.String"
             override="false"/>

Verify that the referenced file exists and that the account running WebAPI or Tomcat has permission to read it.

WebAPI Does Not Respond

Verify that WebAPI completed its Spring Boot startup successfully by reviewing either:

  • The Visual Studio Code debug console when running directly from VS Code, or
  • The Tomcat console/logs when deploying the WAR.

Also verify that the configured WebAPI port is not already in use and that the URL being used matches the server configuration in your external configuration.

Want to contribute to this Wiki?

Fork it and send a pull request.

Documentation

Project Management

Contributing

Clone this wiki locally