Phil Skentelbery
6d21442705
Set up Python project with uv environment management and FastAPI stack. Project structure: - src/gondulf/ - Main application package - tests/ - Test suite directory - pyproject.toml - Project configuration with dependencies - README.md - Project documentation - uv.lock - Dependency lock file Dependencies configured: - FastAPI + Uvicorn for web framework - SQLAlchemy for database ORM - pytest + coverage for testing - ruff, black, mypy, flake8 for code quality - Development environment using uv direct execution model All project standards reviewed and implemented per: - /docs/standards/coding.md - /docs/standards/testing.md - /docs/standards/git.md - /docs/standards/development-environment.md - /docs/standards/versioning.md
160 lines
3.8 KiB
Markdown
160 lines
3.8 KiB
Markdown
# 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:**
|
|
```bash
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
```
|
|
|
|
**Using pip:**
|
|
```bash
|
|
pip install uv
|
|
```
|
|
|
|
Verify installation:
|
|
```bash
|
|
uv --version
|
|
```
|
|
|
|
### 2. Clone the Repository
|
|
|
|
```bash
|
|
git clone <repository-url> gondulf
|
|
cd gondulf
|
|
```
|
|
|
|
### 3. Set Up Development Environment
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](https://www.w3.org/TR/indieauth/)
|
|
- [OAuth 2.0 Authorization Framework](https://datatracker.ietf.org/doc/html/rfc6749)
|
|
- [PKCE (RFC 7636)](https://datatracker.ietf.org/doc/html/rfc7636)
|