mirror of
https://github.com/quay/quay.git
synced 2026-01-26 06:21:37 +03:00
73 lines
2.7 KiB
Markdown
73 lines
2.7 KiB
Markdown
# AGENTS.md
|
|
|
|
AI-optimized guide for working with Project Quay container registry.
|
|
|
|
## Project Overview
|
|
|
|
Enterprise container registry supporting Docker Registry Protocol v2, OCI spec v1.1. Provides authentication, ACLs, team management, geo-replicated storage, and security scanning via Clair.
|
|
|
|
**Stack:** Python 3.12, Flask, SQLAlchemy, PostgreSQL, Redis, Alembic migrations
|
|
|
|
**Frontend:** Legacy Angular (`static/js/`) + New React/PatternFly (`web/`) - see `web/AGENTS.md` for React details
|
|
|
|
**Config:** YAML at `conf/stack/config.yaml` (local dev), validated via JSON Schema
|
|
|
|
## Quick Commands
|
|
|
|
```bash
|
|
# Local Dev
|
|
make local-dev-up # Start Quay + PostgreSQL + Redis
|
|
make local-dev-up-with-clair # Include Clair security scanner
|
|
make local-dev-down # Shutdown
|
|
podman restart quay-quay # Apply code changes
|
|
|
|
# Testing
|
|
TEST=true PYTHONPATH="." pytest path/to/test.py -v # Single test file
|
|
TEST=true PYTHONPATH="." pytest path/to/test.py::TestClass::test_fn -v # Single test
|
|
make unit-test # All unit tests
|
|
make registry-test # Registry protocol tests
|
|
|
|
# Code Quality
|
|
make types-test # Type checking (mypy)
|
|
```
|
|
|
|
## Key Directories
|
|
|
|
- `endpoints/api/` - REST API v1 (Flask)
|
|
- `endpoints/v2/` - OCI/Docker registry protocol
|
|
- `data/model/` - SQLAlchemy models
|
|
- `data/migrations/` - Alembic migrations
|
|
- `workers/` - Background job processors
|
|
- `auth/` - Authentication & authorization
|
|
- `storage/` - Storage backends (S3, Azure, Swift, local)
|
|
- `web/` - React frontend (see `web/AGENTS.md`)
|
|
|
|
## Documentation by Task
|
|
|
|
**Read the relevant doc before starting work:**
|
|
|
|
| If working on... | Read... |
|
|
|------------------|---------|
|
|
| API endpoints, authentication | `agent_docs/api.md` |
|
|
| Database models, migrations | `agent_docs/database.md` |
|
|
| Testing patterns, fixtures | `agent_docs/testing.md` |
|
|
| Architecture, key files | `agent_docs/architecture.md` |
|
|
| Global readonly superuser feature | `agent_docs/global_readonly_superuser.md` |
|
|
| Local development setup | `agent_docs/development.md` |
|
|
| React frontend | `web/AGENTS.md` |
|
|
|
|
## Universal Conventions
|
|
|
|
1. **Testing:** Always run relevant tests before committing
|
|
2. **Formatting:** Rely on pre-commit hook to format code on commit
|
|
3. **No secrets:** Never commit credentials, API keys, or sensitive config
|
|
4. **Imports:** Follow existing import ordering patterns in each file
|
|
5. **Error handling:** Use appropriate exception types from `endpoints/exception.py`
|
|
|
|
## Local Dev URLs
|
|
|
|
- Quay UI: http://localhost:8080
|
|
- PostgreSQL: localhost:5432
|
|
- Redis: localhost:6379
|
|
- Clair: localhost:6000 (from Quay container, when enabled)
|