Detailed Instructions for Starting Backtester

Welcome! These instructions will guide you step-by-step through setting up and running this project on your Windows computer. Don’t worry if you’re not familiar with technical terms; we’ll explain everything as we go.

Important Prerequisite: This project currently only works on Windows 10 or Windows 11 (64-bit versions, which are standard for most modern PCs).

Step 1: Get Your Free FRED API Key

This project needs to fetch data from the St. Louis Federal Reserve (FRED). To do this securely, you need a special code called an “API Key”. Think of it like a password that lets this program talk to the FRED database. Getting one is free.

  1. Open Your Web Browser: Launch your preferred web browser (like Chrome, Edge, or Firefox).
  2. Go to the FRED API Key Website: Click on this link or copy and paste it into your browser’s address bar and press Enter: https://fredaccount.stlouisfed.org/apikeys
  3. Sign In or Register:
    • If you already have a FRED account, sign in.
    • If you don’t have an account, you’ll need to register for one. Follow their instructions – it’s usually straightforward and involves providing an email address and creating a password.
  4. Request an API Key: Once logged in, look for a section related to “API Keys”. There should be an option to “Request API Key” or “Generate New Key”. You might need to agree to their terms of service.
  5. Copy Your API Key: After requesting it, FRED will display your unique API Key. This will be a long string of letters and numbers (e.g., abcdef1234567890abcdef1234567890).
    • Very Important: Select this entire key with your mouse.
    • Right-click on the selected key.
    • Choose Copy from the menu that appears. This saves the key to your computer’s clipboard (a temporary holding place).
    • Keep this browser window open for a moment just in case you need to copy it again, but the key is now ready on your clipboard for the next steps.

Step 2: Download the Project Files

Now, you need to download the project software itself.

If you don’t have access to the project on github (most likely scenario):

  1. Download the ZIP file using the link that was provided to you

If you have access to the project on github:

  1. Go to the Project’s Download Page: You need the link to the “Releases” page of the project on GitHub.
  2. Find the Latest Release: Releases are usually listed by date or version number (e.g., v1.0, v1.1). Look for the one marked “Latest”.
  3. Download the ZIP File: In the “Assets” section of the latest release (you might need to click to expand it), find the file that ends with .zip. It might be named something like Backtester-v0.0.1-windows-x64.zip or similar. Click on this file name to download it.
  4. Save the File: Your browser will ask where to save the file, or it might automatically save it to your Downloads folder. Remember where it’s saved (the Downloads folder is common).

Step 3: Prepare the Project Folder (Unzipping)

The downloaded file is a “ZIP” file, which is like a compressed container holding all the project files. You need to extract these files into a dedicated folder.

  1. Choose a Location: Decide where you want to keep the project files. Good options are your Documents folder or your Desktop.
  2. Create a New Folder:
    • Navigate to the location you chose (e.g., open your Documents folder).
    • Right-click on an empty space within that folder.
    • Go to New -> Folder.
    • Give the new folder a simple name, for example: MyProject (avoid spaces or special characters if possible, it makes later steps easier). Press Enter.
  3. Find the Downloaded ZIP File: Go back to where you saved the downloaded .zip file (likely your Downloads folder).
  4. Extract the Files:
    • Right-click on the downloaded .zip file.
    • Select Extract All….
    • A window will pop up asking where to extract the files. Click the Browse… button.
    • Navigate to and select the new folder you created in step 3.2 (e.g., Documents\MyProject). Click Select Folder.
    • Make sure the path in the “Extract All” window now points to your new folder (e.g., C:\Users\YourUsername\Documents\MyProject).
    • Click the Extract button.
  5. Check the Files: Windows should open the MyProject folder automatically after extraction. Inside, you should now see the actual project files and folders, including one named manage.

Step 4: Run the Project Using the Shortcut

  1. Navigate to the folder where the files were extracted in step 3
  2. Go into the manage folder
  3. Find the shortcut file named Backtester and double-click on it
  4. Paste Your FRED API Key When Prompted:
    • The program will start running in the Command Prompt window. It will likely print some messages and then stop and ask you to enter your FRED API key. It might say something like Please enter your FRED API key:.
    • Remember the key you copied way back in Step 1? It should still be on your clipboard.
    • Position your cursor in the Command Prompt window after the prompt text.
    • Right-click in the Command Prompt window. This should paste your API key. (You might not see the key appear as you paste it, especially if it’s treated like a password input - this is normal).
    • Press Enter after pasting.
  5. Check for Success: If the key is correct, you should see more text appear in the Command Prompt window, indicating that a server has started. Look for lines mentioning:
    • Starting development server at http://127.0.0.1:8000/
    • Quit the server with CTRL-BREAK. (or CTRL-C)
    • Important: Do NOT close this Command Prompt window! The project only runs while this window is open and running the command.

Step 5: Access the Backtester in Your Web Browser

The backtester is now running locally on your computer. You can access it using your web browser.

  1. Open Your Web Browser: You can use the same one as before or a new tab/window.
  2. Go to the Local Address: In the address bar, type (or copy) the following exactly: http://127.0.0.1:8000/
  3. Press Enter.
  4. You should now see the project’s web interface load in your browser!

Troubleshooting: Entered the Wrong API Key?

Mistakes happen! If you pasted the wrong key, the program might give an error or just not work correctly. Here’s how to fix it:

  1. Stop the Program: Go back to the black Command Prompt window where the program is running (or where it stopped with an error). Press and hold the CTRL key on your keyboard, and while holding it, press the C key. Release both keys. You might have to do this once or twice. The program should stop, and you should see the normal command prompt path (like C:\Users\YourUsername\Documents\MyProject\manage>) reappear.
  2. Delete the Incorrect Key File: The program saved your incorrect key in a file. We need to delete it.
    • Open File Explorer (yellow folder icon).
    • Navigate back to your project folder, and then inside the manage subfolder (e.g., C:\Users\YourUsername\Documents\MyProject\manage).
    • Look for a file named exactly fred_api.key.
    • Right-click on the fred_api.key file and select Delete. Confirm if asked.
  3. Re-Copy the Correct Key (If Needed): If you don’t have the correct key on your clipboard anymore, go back to the FRED website (Step 1) and copy your valid API key again.
  4. Re-Run the Program: Go back to the file explorer window (which should still be in the manage folder)**:
    • Double-click on the Backtester shortcut.
    • When prompted, right-click to paste the correct API key.
    • Press Enter.
    • Check for the success messages.
  5. Try Accessing Again: Go back to your web browser and try loading http://127.0.0.1:8000/ again.

How to Stop the Project When You’re Done

When you want to stop the project from running:

  1. Go back to the black Command Prompt window where the server messages are appearing.
  2. Press and hold the CTRL key, and then press the C key.
  3. Release both keys.
  4. The server will stop, and you’ll get your command prompt back (e.g., C:\Users\YourUsername\Documents\MyProject\manage>).
  5. You can now safely close the Command Prompt window. The project will no longer be accessible in your browser until you run it again using Step 4.

That’s it! Hopefully, these detailed steps help you get the project running smoothly.