Professional-grade open-source platform for animal shelter management
🚀 Quick Start • 📖 Documentation • 🛠️ Development • 🤝 Contributing
RefuPet is a comprehensive, open-source web platform designed specifically for animal shelter management. Built with modern technologies and professional development practices, it provides a secure, scalable, and user-friendly solution for shelter operations.
- 🌐 Frontend: React 19 + Vite + TypeScript
- ⚙️ Backend: Django 4+ + REST Framework + PostgreSQL
- 🐳 Infrastructure: Docker + Docker Compose
- 🚀 Deployment: Coolify-compatible with automated CI/CD
- Secure by design with environment-based configuration
- Docker containerization with multi-stage optimized builds
- PostgreSQL database with automated migrations
- Static file handling and optimized asset serving
- Health checks and proper logging
- One-command setup -
make setup && make dev - Hot reload development with instant feedback
- Automated code quality - pre-commit hooks, linting, formatting
- Comprehensive testing - frontend (Vitest) + backend (Django)
- VSCode integration - debugging, tasks, and extensions
- API documentation - Interactive Swagger UI
- AGPL v3 licensed ensuring open-source compliance
- No hardcoded secrets - secure development practices
- Automated vulnerability scanning with dependency updates
- Code quality enforcement with Black, Prettier, ESLint
- Type safety with TypeScript and strict linting
- Docker Desktop - Download here
- Node.js 18+ - Download here (for local frontend development)
- Make - Usually pre-installed on macOS/Linux
# 1. Clone the repository
git clone https://github.com/hackapet-project/refupet-web.git
cd refupet-web
# 2. Setup environment and dependencies
make setup
# 3. Start the development environment
make devOnce the environment is running:
| Service | URL | Description |
|---|---|---|
| 🌐 Frontend | http://localhost:5173 | React development server |
| ⚙️ Backend | http://localhost:8000 | Django API server |
| 👤 Admin Panel | http://localhost:8000/admin | Django administration |
| 📖 API Docs | http://localhost:8000/api/docs/ | Interactive Swagger UI |
# Create database and apply migrations
make migrate
# Create development users (generates random passwords)
make seed
# View logs
make logs# Development
make dev # Start full development environment
make dev-bg # Start in background
make stop # Stop all containers
make logs # View application logs
# Code Quality
make format # Format all code (Black + Prettier)
make lint # Run all linters
make test # Run all tests
# Database
make migrate # Apply database migrations
make seed # Create development users
make shell # Django shell
make superuser # Create admin user
# Utilities
make clean # Clean containers and volumes
make help # Show all available commandsrefupet-web/
├── 📁 backend/ # Django REST API
│ ├── 🐍 refupet_project/ # Django settings and configuration
│ ├── 🧪 tests/ # Backend test suite
│ ├── 📊 fixtures/ # Development data
│ └── 🔧 manage.py # Django management
├── 📁 frontend/ # React TypeScript frontend
│ ├── ⚛️ src/ # React components and logic
│ ├── 🧪 src/test/ # Frontend test utilities
│ └── ⚙️ vite.config.js # Vite configuration
├── 📁 docker/ # Docker configuration
├── 📁 docs/ # Documentation
├── 🔧 Makefile # Development automation
└── 📋 CONTRIBUTING.md # Development guidelines
- CONTRIBUTING.md - Complete development workflow and guidelines
- docs/DEVELOPMENT.md - Technical architecture and patterns
- docs/SECURITY.md - Security best practices and guidelines
- CLAUDE.md - AI assistant integration guide
- API Documentation - Available at
/api/docs/when running - Admin Interface - Django admin at
/admin/
# All tests
make test
# Frontend only
make test-frontend
# Backend only
make test-backend# Format code
make format
# Check linting
make lint
# Type checking
make type-checkThe project uses:
- Python: Black, isort, flake8 for formatting and linting
- JavaScript/TypeScript: Prettier, ESLint for code quality
- Pre-commit hooks to enforce quality standards
- Automated testing with Vitest and Django test framework
The application is Coolify-ready with optimized Docker configurations:
# Build production images
make build
# Production environment variables needed:
# - DJANGO_SECRET_KEY (generate new)
# - DATABASE_URL (PostgreSQL connection)
# - DJANGO_ALLOWED_HOSTS (your domain)
# - DJANGO_DEBUG=False
# - DJANGO_ENV=productionCopy .env.example to .env and configure:
# Production example
DJANGO_SECRET_KEY=your-super-secure-secret-key
DJANGO_DEBUG=False
DJANGO_ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com
DATABASE_URL=postgresql://user:password@host:port/database🏆 Lead Developer & Architect Diego Rejón - Project leadership, API development, database design
🔧 Infrastructure & DevOps Ignacio Delgado - Docker infrastructure, CI/CD, deployment
🎨 Frontend Development nadecc - React development, UI/UX, frontend architecture
📚 Documentation & Project Management Nacho Loyola - Documentation, contributor guidelines
🤖 Developer Experience Claude - Automation, tooling, security enhancements
We welcome contributions! Please see our Contributing Guidelines for details.
- Fork the repository
- Create a feature branch
- Run
make setupto get started - Make your changes following our code standards
- Test with
make testandmake lint - Submit a pull request
Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
This ensures that all modifications and usage in networks (e.g., as a web app) remain open-source. See LICENSE for full details.
- 🐛 Bug Reports: GitHub Issues
- 💡 Feature Requests: GitHub Discussions
- 📧 General Questions: dev@hackapet.org
- 📖 Documentation: Check docs/ directory
Docker not starting?
# Check if Docker is running
make check-docker
# Start Docker Desktop and try again
make devEnvironment issues?
# Reset everything
make clean
make setup
make devMade with ❤️ by the RefuPet Team
[⭐ Star us on GitHub](https://github.com/hackapet-project/refupet-web • 🌍 Visit hackapet.org