Skip to main content
After bootstrapping your development environment, you can run the application locally.

​
Starting the Application

1

Ensure dependencies are installed

If you haven’t already run bootstrap:
make bootstrap
2

Start the Flask development server

make run-flask
This will start the application on http://localhost:7001 with debug mode enabled.The command sets the following environment variables:
  • FLASK_APP=application.py - Specifies the Flask application entry point
  • FLASK_DEBUG=1 - Enables debug mode with auto-reloading and detailed error pages
3

Access the application

Open your browser and navigate to:
http://localhost:7001

​
Development Workflow

​
Auto-rebuilding Frontend Assets

During development, you’ll likely make changes to JavaScript, SCSS, or other frontend assets. To automatically recompile these on changes:
1

Open a new terminal window

Keep your Flask server running in one terminal.
2

Start the asset watcher

In the new terminal, run:
npm run watch
This will monitor your frontend files and rebuild them automatically when changes are detected.
3

Restart the app after asset changes

After frontend assets are recompiled, restart the Flask server so they are served with the correct Content-Length header.Press Ctrl+C in the Flask server terminal, then run:
make run-flask
If you’re using notifications-local Docker setup, restart the container instead:
docker compose restart document-download-frontend

​
Running with Docker

You can also run the application using Docker:
1

Bootstrap with Docker

make bootstrap-with-docker
This builds a Docker image with all dependencies installed.
2

Run Flask with Docker

make run-flask-with-docker
This uses the scripts/run_locally_with_docker.sh script to run the Flask server in a container.

​
Testing

​
Running Tests Locally

1

Run the full test suite

make test
This command will:
  • Run linting checks with ruff (static analysis and formatting)
  • Execute all tests in the tests/ directory with pytest
  • Run tests in parallel using pytest-xdist (-n auto)
  • Stop after 10 failures (--maxfail=10)

​
Running Tests with Docker

make test-with-docker

​
Linting Only

To run just the linting checks without tests: 
make lint
This will:
  • Check code with ruff check .
  • Check formatting with ruff format --check .

​
Frontend Linting

To lint SCSS files: 
npm run lint:scss
To lint JavaScript files: 
npm run lint:js

​
Common Development Tasks

​
Building Frontend Assets Manually

If you need to rebuild frontend assets without watching: 
npm run build

​
Running npm Audit

To check for security vulnerabilities in Node.js dependencies: 
make npm-audit
Or directly: 
npm run audit
This uses better-npm-audit to check production dependencies for high-severity issues.

​
Viewing Available Make Commands

To see all available make commands: 
make help

​
Environment Variables

The application uses several environment variables that can be configured:
  • FLASK_APP - Flask application entry point (default: application.py)
  • FLASK_DEBUG - Enable debug mode (set to 1 for development)
  • Additional configuration may be required for AWS credentials, Sentry DSN, etc.
Never commit sensitive environment variables or credentials to version control. Use environment files or secret management tools.

​
Troubleshooting

​
Port 7001 already in use

If port 7001 is already occupied: 
# Find the process using port 7001
lsof -ti:7001

# Kill the process
kill -9 $(lsof -ti:7001)
Or run Flask on a different port: 
FLASK_APP=application.py FLASK_DEBUG=1 flask run -p 7002

​
Frontend assets not loading

If static assets aren’t loading correctly:
  1. Rebuild the frontend: 
    npm run build
  2. Clear browser cache and hard reload (Cmd+Shift+R or Ctrl+Shift+R)
  3. Check that files exist in the static directory: 
    ls -la app/static/

​
Changes not reflected in the browser

  1. Ensure Flask debug mode is enabled (it should auto-reload)
  2. Check the terminal for any errors
  3. For frontend changes, ensure npm run watch is running
  4. Restart the Flask server after frontend asset changes

​
Tests failing

If tests fail unexpectedly: 
# Run tests with verbose output
pytest -v tests/

# Run a specific test file
pytest tests/test_file.py

# Run tests without parallelization for clearer output
pytest tests/

​
Pre-commit hooks blocking commits

If pre-commit hooks are preventing you from committing: 
# Let pre-commit auto-fix issues
pre-commit run --all-files

# Review the changes it made
git diff

# Commit the fixes
git add .
git commit -m "Fix linting issues"

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us