-
Notifications
You must be signed in to change notification settings - Fork 23
Installation
This guide is for anyone who wants to start using and contributing to the OpenFinAL software repository.
- 🚀 Quick Install Instructions
- 📚 Detailed Install Instructions
- 🏍 Install the Sidecar Software Supports
- 🛠️ Developer Note: Testing the Software
If you are familiar with Git and Node.js, you can be up and running in minutes.
-
Install Git: Ensure you have a version of Git installed appropriate for your operating system. For example:
- Windows Installer Link: https://git-scm.com/downloads/win
- Mac and Linux: Mac and Linux often come preinstalled with git, which is accessed through the terminal
- Verify the installation: for example:
git --version
-
Install Node.js: Download and install the latest version, which includes npm (Node Package Manager).
-
Install and Prepare VSCode: Install VSCode from the official Microsoft distribution service or through Ninite. You may also optionally install plugins with plugins for nodeJS and Electron (not required). Most other IDEs (i.e. Webstorm) will also function without requiring custom configuration.
Use git or your favorite IDE to clone the repository. For example:
git clone https://github.com/jeffreywallphd/OpenFinAL.git
You can now Navigate to the Project Folder:
cd OpenFinAL/open-fin-al
- Within the Project Folder (i.e., OpenFinAL/open-fin-al/), run
npm install
The software does not currently use the graph database Neo4j, but it will in a future version. Neo4j will be bundled with the software using the sidecar pattern. If you are unfamiliar with the sidecar pattern, please see the 🏍 Install the Sidecar Software Supports section of this page. The sidecar currently supports Windows systems, but not Mac/Linux. If you are familiar with the sidecar pattern and downloading binaries, do the following:
- Download the 2025 Windows Community Neo4j binaries at: https://neo4j.com/deployment-center/?gdb-selfmanaged&community
- Download the JDK 25 compressed archive version of Java at: https://www.oracle.com/java/technologies/downloads/#jdk25-windows
- Unzip the binaries.
- Move the contents of the binaries (i.e., the bin folder and all other folders and files) into OpenFinAL/open-fin-al/resources/neo4j-win and OpenFinAL/open-fin-al/resources/jre-win
- With the binaries in place, you can move to the next step and start the application.
Within the Project Folder (i.e., OpenFinAL/open-fin-al/), run the following command to launch the software:
npm start
The application should open in an Electron window.
To configure the software, you will need to:
- Create a user login within the application.
- Go to the Settings section of the application and enter data provider information. If not configured, it should take you to the Settings page automatically.
| Data Provider | Key Type | Link to Get Key |
|---|---|---|
| AlphaVantage | Free (or premium via academic access) | https://www.alphavantage.co/support/#api-key |
| Financial Modeling Prep (FMP) | Free | https://site.financialmodelingprep.com/ |
| OpenAI | Free (or paid) | https://openai.com/api/ |
This section provides a step-by-step guide for users who are new to programming and the command line.
You will need three main software tools to start contributing to OpenFinAL: Git, Node.js, and an IDE (Integrated Development Environment) to view and edit code.
What it is: A system that tracks changes to files and allows you to copy and contribute code to this GitHub project.
- Windows Installer Link: https://git-scm.com/downloads/win
- Mac/Linux: Mac and Linux often come pre-installed with git, which can be accessed through the Terminal
- Verify Installation: After installation, open GitBash or command line (CMD) on Windows or the Terminal on Mac/Linux and type git --version.
What it is: An advanced text editor that helps you manage, view, and edit the project's code files. It also has built-in tools for Git and running terminal commands. You can either use GitBash/CMD/Terminal to run git commands, or use the IDE's graphical version control tools to manage the changes you make to the software.
- Recommendation: VS Code (Available for all major operating systems).
What it is: The runtime environment that allows this JavaScript application to run. Installing it also gives you npm (Node Package Manager), which is used to download required code libraries and start the software.
- The current build of OpenFinAL relies on version 22 LTS of Node.js Please ensure that you select this version upon installation.
- Link: https://nodejs.org/en/download
The repository URL you need is: https://github.com/jeffreywallphd/OpenFinAL.git
"Cloning" copies the project code from GitHub to your computer. It is crucial to know where this folder is saved on your computer. The folder will be named OpenFinAL.
Option 1: Using VS Code
- Open VS Code.
- Click the Source Control icon (three interconnected circles) on the left sidebar.
- Click the Clone Repository button.
- Paste the repository URL: https://github.com/jeffreywallphd/OpenFinAL.git
- Select a Location: Choose an empty folder or a location that is easy for you to find again (e.g., your Desktop or a dedicated Projects folder). The project files will be stored in this location.
Option 2: Using GitHub Desktop
- Open GitHub Desktop.
- Click File > Clone repository.
- Paste the repository URL.
- Select the Local Path (the folder where the repository will be stored). Write down or remember this path. The project will be cloned into a folder named OpenFinAL inside the path you select.
- Open the Terminal in VS Code (Go to View > Terminal from the top menu) or open the Windows Command Prompt (CMD) or GitBash or Mac/Linux Terminal.
-
Navigate to the OpenFinAL Folder: You must point the terminal/CMD to the project folder using the cd (change directory) command.
-
If you are using CMD: Use cd followed by the full path (e.g., cd C:\Users\YourName\Documents\OpenFinAL).
- You can obtain your file path by locating the file and right clicking and selecting “Copy as path”
- If you used VS Code to clone: Use File > Open Folder in VS Code to open the OpenFinAL folder directly. The terminal should automatically be in the correct location.
-
If you are using CMD: Use cd followed by the full path (e.g., cd C:\Users\YourName\Documents\OpenFinAL).
The current version of the software does not require a Neo4j database, but a future version will. You can follow the instructions in the 🏍 Install the Sidecar Software Supports section of this document to install Neo4j. However, it is not currently required for OpenFinAL to work correctly.
- Install the nodeJS Project Dependencies: Run the following command in the Terminal/CMD/Gitbash while you are in the OpenFinAL directory:
npm install
- Start the Software: Run the following command:
npm start
- The application will launch in a desktop window.
-
Configure Data Providers: After the application loads, you will configure data providers and create a user login:
- Click on Settings in the menu sidebar. If not configured, it should take you to the Settings page automatically.
- Select the data providers you want and enter API keys.
Watch The Sidecar Installation Video Instead
| Data Provider | Key Type | Link to Get Key |
|---|---|---|
| AlphaVantage | Free (or premium via academic access) | https://www.alphavantage.co/support/#api-key |
| Financial Modeling Prep (FMP) | Free | https://site.financialmodelingprep.com/ |
| OpenAI | Free (or paid) | https://openai.com/api/ |
- Use the Software: Once you create a user and set up the data providers, you should be able to see and use the different features of the software.
This is not currently a required step, but will be in later updates. Although following these instructions will not break the application, these steps are currently unnecessary.
The software uses a sidecar pattern to load and use non-nodeJS requirements that OpenFinAL relies on. The name sidecar comes from the motorcycle sidecar that rides alongside a motorcycle. The software sidecar represents tools that are peripheral, but connected to the main codebase. The software will come bundled with a version of the graph database Neo4j and a specific version of Java to support Neo4j. At the time of this writing, the sidecar is only compatible with Windows systems. Sidecar configurations for Mac/Linux need to be created.
To prepare the Windows sidecar in your development environment, you will need to do the following after cloning OpenFinAL:
- Download Neo4j Binaries: Visit https://neo4j.com/deployment-center/?gdb-selfmanaged&community and download the Neo4j Community Windows Executable. It should be a zip file.
- Download Java Binaries: Visit https://www.oracle.com/java/technologies/downloads/#jdk25-windows and download the JDK 25 for Windows (x64 Compressed Archive)
- Unzip the download files.
- Create the following folders in the OpenFinAL application within the OpenFinAL/open-fin-al/resources/ folder:
- neo4j-win
- jre-win
- When finished you should see these two folders inside of OpenFinAL/open-fin-al/resources/
- If the resources folder doesn't exist, just create that first
- Once the neo4j-win and jre-win folders exist, do the following for both Neo4j and Java:
- Navigate the unzipped folder structure until you enter the folder that contains the bin/ folder and a series of other folders and files.
- Copy the contents of the folder (i.e., the bin folder and all of the other folders and files)
- Paste the files into the respective OpenFinAL/open-fin-al/resources/ folder (i.e., the neo4j copied files into neo4j-win folder; and the java copied files into the jre-win folder.)
- If you copied all of the files to the specified file locations, the sidecar should function properly when you start the application.
If you are jumping back and forth between branches of the repository, it is good to clean your npm install and reinstall the nodeJS dependencies each time you move branches. Some branches may have different dependencies. To do this, run the following command within the Project Folder:
npm run clean
Then run the following again:
npm install
Although the "npm run clean" command clears important files and dependencies for a clean install, it does not capture every possible difference that may exist between your system and the repository. To properly test the software and ensure you have a clean environment that accurately reflects the public repository you can do the following after you make sure your changes are pushed to GitHub to the remote version of your branch:
- Delete your local OpenFinAL folder. Only do this if you have pushed your branch to GitHub. Otherwise, you will delete all of your unsaved work.
- Perform a fresh git clone of the repository.
- Switch to your branch (e.g., git checkout [your_branch_name]).
- Run npm install and npm start as normal.
- Ensure that you have Git properly installed.
- Completely shut down and re-launch VSCode
Run this command in PowerShell to give your Windows user account the ability to run scripts.
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
The npm packages utilized by OpenFinAL depends on version 22 LTS of Node.js. Previous installation instructions did not specify versioning.
- Completely uninstall Node.js to ensure a clean install.
- Navigate to the Node.js installation website.
- Click the version number box. It will open a drop-down. Select version 22 LTS and install.
- Attempt to re-run npm install.