Gondulf IndieAuth Server

A self-hosted IndieAuth server implementation following the W3C IndieAuth specification. IndieAuth enables users to use their own domain as their identity when signing into third-party applications.

Features

• Full W3C IndieAuth specification compliance
• Client self-registration capability
• Built on OAuth 2.0 with PKCE support
• Simple, maintainable codebase
• Single administrator model

Requirements

• Python 3.10 or higher
• SQLite 3.35 or higher
• uv (for environment management)

Installation

1. Install uv

Linux/macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Using pip:

pip install uv

Verify installation:

uv --version

2. Clone the Repository

git clone <repository-url> gondulf
cd gondulf

3. Set Up Development Environment

# Create virtual environment
uv venv

# Install the project in development mode with all dependencies
uv pip install -e ".[dev,test]"

Usage

Running the Development Server

uv run uvicorn src.gondulf.main:app --reload --host 127.0.0.1 --port 8000

The server will be available at http://127.0.0.1:8000

Running Tests

# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov=src/gondulf --cov-report=term-missing

# Run specific test categories
uv run pytest -m unit
uv run pytest -m integration
uv run pytest -m e2e

Code Quality Checks

# Linting
uv run ruff check .

# Type checking
uv run mypy src/gondulf

# Format code
uv run ruff format .

# Security scanning
uv run bandit -r src/gondulf

Development Workflow

All commands use uv run to execute within the project's virtual environment - no activation required.

Common commands:

• uv run python script.py - Run a Python script
• uv run pytest - Run tests
• uv run ruff check . - Lint code
• uv pip install package - Add a dependency
• uv pip list - List installed packages

See /docs/standards/development-environment.md for detailed development environment documentation.

Project Structure

gondulf/
├── src/
│   └── gondulf/          # Main application code
│       └── __init__.py
├── tests/                # Test suite
│   ├── unit/            # Unit tests
│   ├── integration/     # Integration tests
│   └── e2e/             # End-to-end tests
├── docs/                # Documentation
│   ├── architecture/    # System architecture
│   ├── designs/         # Feature designs
│   ├── decisions/       # Architecture Decision Records
│   ├── standards/       # Coding and process standards
│   └── roadmap/         # Version planning
└── pyproject.toml       # Project configuration

Documentation

• Architecture Overview: /docs/architecture/overview.md
• IndieAuth Protocol: /docs/architecture/indieauth-protocol.md
• Coding Standards: /docs/standards/coding.md
• Testing Standards: /docs/standards/testing.md
• Git Workflow: /docs/standards/git.md

Contributing

This project follows strict architectural and development standards. Please review:

1. /docs/standards/coding.md - Coding conventions
2. /docs/standards/testing.md - Testing requirements
3. /docs/standards/git.md - Git workflow and commit format

All code must:

• Include comprehensive tests (minimum 80% coverage)
• Pass linting and type checking
• Follow conventional commits format
• Be reviewed before merging to main

License

MIT License - see LICENSE file for details

References

• W3C IndieAuth Specification
• OAuth 2.0 Authorization Framework
• PKCE (RFC 7636)