Software Maintenance Guide¶

This document outlines how to configure and setup a development environment to work on Pi Dashboard.

Backend (Python)¶

Installing Dependencies¶

This repository is managed using the uv Python project manager: https://docs.astral.sh/uv/

Install the required dependencies:

uv sync

To include extra dependencies:

uv sync --extra dev
uv sync --extra docs
uv sync --all-extras

Setting Up Authentication¶

Before running the server, you need to generate an API authentication token.

cp .env.example .env       # Set HOST and PORT to override defaults
uv run generate-new-token  # Set API_TOKEN_HASH variable

This command:

Creates a cryptographically secure token using Python’s secrets module
Hashes the token with SHA-256 for safe storage
Stores the hash in .env file
Displays the plain token (save it securely - it won’t be shown again)

Running the Backend¶

Start the server with:

uv run pi-dashboard

The backend will be available at https://localhost:443/api by default.

Available Endpoints:

Health Check: https://localhost:443/api/health
Login: https://localhost:443/api/login (requires authentication)

Testing the API:

curl -k https://localhost:443/api/health
curl -k -H "X-API-Key: your-token-here" https://localhost:443/api/login

Testing, Linting, and Type Checking¶

# Lint code
uv run ruff check .

# Format code
uv run ruff format .

# Type check
uv run mypy .

# Run tests
uv run pytest

# Security scan
uv run bandit -r pi_dashboard/

# Audit dependencies
uv run pip-audit

Building Documentation¶

This project uses Sphinx for documentation. To build the documentation:

uv run sphinx-build -M clean docs/source/ docs/build/
uv run sphinx-build -M html docs/source/ docs/build/

The built documentation will be available at docs/build/html/index.html.

Frontend (Next.js)¶

Ensure you run the following commands in the frontend directory:

cd pi-dashboard-frontend

Installing Dependencies¶

Install the required dependencies using npm:

npm install

Running the Frontend¶

Ensure the backend server is running and then start the frontend development server:

npm run dev

The frontend will be available at http://localhost:3000.

Testing, Linting, and Type Checking¶

# Run all quality checks
npm run quality
npm run quality:fix

# Lint code
npm run lint
npm run lint:fix

# Format code
npm run format
npm run format:fix

# Type check
npm run type-check

# Run tests
npm run test