Skip to content

Local Setup

Jump to bottom
max-zaremba-tcg edited this page Nov 7, 2025 · 11 revisions

This page provides instructions about how to run the app on your local machine.

Prerequisites

Frontend Software necessary to run the application locally:

  • node
  • npx

Backend Software necessary to run the application locally:

If you're a Windows user, please install WSL:

If you're not a developer, this is all you need! However, if you want to run this application for development purposes, you will also need:

Let this serve as a comprehensive checklist. This guide will explain how to set up everything listed here, so don't worry about having to do it all at once right away.

Running the Frontend locally

NPM

First, install npm. In the terminal, navigate to where you have the fecfile-web-app/front-end located on your machine and install packages with:

npm install

To start a local server that hosts the front end of the application, execute:

npx -p @angular/cli ng serve

If you're a developer and encounter an issue where your frontend code isn't compiling after you save your changes, run this to start the frontend instead:

npx -p @angular/cli ng serve --poll 2000

The frontend can then be accessed through your browser at port 4200.

However, before you can access the application, you will also need to start the backend.

Running the Backend locally

Docker

First, install Docker and Docker Compose

Django Secret Key

Before running the backend, You will need to define a DJANGO_SECRET_KEY. Locally you can just add something like this your .bashrc file: export DJANGO_SECRET_KEY="thisismykey" If you're a Windows user, open WSL to read and edit this file.

To generate a secret key, navigate to the django-backend folder in fecfile-web-api. You can run this command to generate one from the Python interpreter directly:

python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'

Alternatively, you can use a package like djecrety.

EFO

Next, you'll need to integrate with EFO.

By default EFO services (print/upload) will be mocked. To integrate with EFO, open docker-compose.yml in fecfile-web-api to set the following environment variables:

# Test EFO Services (for test filings):
export MOCK_EFO_FILING=False
export EFO_FILING_API_KEY="EFO_get_this_from_team_member"

Note - the default PRODUCTION_OPEN_FEC_API_KEY and STAGE_OPEN_FEC_API_KEY key has a very low rate limit - for a better key, reach out to a team member or get one at https://api.open.fec.gov/developers/

Additional Installation Instructions for Developers

Git Secrets

You'll need to set up git secrets to protect yourself from committing sensitive information such as passwords to the repository.

  • First install AWS git-secrets utility in your PATH so it can be run at the command line: https://github.com/awslabs/git-secrets#installing-git-secrets
  • Once you have git-secrets installed, run the fecfile-web-api/install-git-secrets-hook.sh shell script in the root directory of your cloned fecfile-web-api repo to install the pre-commit hooks. NOTE: The pre-commit hook is installed GLOBALLY by default so commits to all cloned repositories on your computer will be scanned for sensitive data. See the comments at the top of the script for local install options.
  • See the git-secrets README for more features.

Code formatting

API

On this project, we use Black as our Python code formatter.

  • Install using pip install black.
  • If using VS Code, install the Black extension from Microsoft and then add (or update) the following section of your settings.json to the following so that code is formatted on save:
"[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true
}
  • To format a specific file or directory manually, use black <file_or_directory>

Prettier js is the Typescript/HTML/SCSS formatter used on the project.

In VS Code install the Prettier - Code formatter. In your VS Code settings, set the following:

"[html]": {
  "editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[typescript]": {
  "editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[scss]": {
  "editor.defaultFormatter": "esbenp.prettier-vscode"
},

Make sure that there are not prettier settings in your settings file that will override the ones in prettierrc.js

VS Code allows you to format a file automatically when you save it. To enable this, open Settings and search for "format on save". Check the box of "Editor: Format on Save".

Commit local code changes to origin daily

As a best practice policy, please commit any feature code changes made during the day to origin each evening before signing off for the day.

Google-style inline documentation

The project is using the Google Python Style Guide as the baseline to keep code style consistent across project repositories. See here for comment style rules: https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings

Docker basic usage

When running docker compose your current directory will need to be fecfile-web-api. The reason for this is that docker compose looks for docker-compose.yml to be in the same directory where it's run. You will also need at least 3GB of memory allocated for docker during the build.

Spin up the containers

docker compose up

Shut down the containers

docker compose down

See all running containers

docker ps

Running commands in a running container

docker exec <container name> <command>

Rebuilding containers

docker compose build [<container name>] [--no-cache]
Clone this wiki locally