A Django-based application for managing biological sample storage, tracking, and reporting. Krill provides a comprehensive solution for laboratories to track samples, manage storage locations, and generate audit reports.
Krill is designed for research laboratories and biobanks that need to:
- Track biological samples with detailed metadata
- Manage storage locations, boxes, and freezer capacity
- Control access with role-based permissions
- Generate reports and maintain audit trails
- Support multiple storage locations and organizational units
- Sample Management: Track biological samples with detailed metadata
- Storage Management: Manage storage locations, boxes, and capacity
- User Management: Role-based access control and permissions
- Reporting: Generate reports and audit logs
- Multi-Database Support: SQLite for development, PostgreSQL for production
- Python 3.15 (
mise installsets up Python and uv frommise.toml) - uv (dependencies are defined in
pyproject.toml/uv.lock)
git clone <repository-url>
cd krill
uv sync # creates .venv and installs dependencies
make migrate # SQLite by default
make createsuperuser
make server # http://localhost:8000 (admin at /admin)make targets run Python through uv run, so there is no need to activate the virtualenv. For ad-hoc commands use uv run python krill/manage.py <command> (or activate .venv yourself).
To start with anonymized sample data instead (creates admin / admin), run make setup-test.
See Testing and make help for all available commands.
-
Set environment variables:
export DATABASE_ENGINE=postgresql export DB_NAME=krill_production export DB_USER=krill_user export DB_PASSWORD=your_secure_password export DB_HOST=localhost export DB_PORT=5432
-
Run migrations:
python manage.py migrate python manage.py createsuperuser
-
Start the application:
python manage.py runserver
The project supports both SQLite and PostgreSQL databases:
- SQLite: Default for local development (easiest setup)
- PostgreSQL: Recommended for production (better performance, features)
# Start PostgreSQL service
docker-compose up -d postgres
# Set environment variables
export DATABASE_ENGINE=postgresql
export DB_NAME=krill
export DB_USER=krill_user
export DB_PASSWORD=krill_password
# Run migrations
python manage.py migrate# Install PostgreSQL
sudo apt-get install postgresql postgresql-contrib
# Create database and user
sudo -u postgres psql
CREATE USER krill_user WITH PASSWORD 'your_password';
CREATE DATABASE krill OWNER krill_user;
GRANT ALL PRIVILEGES ON DATABASE krill TO krill_user;
\q# Check database configuration
python manage.py setup_db --check
# Switch database engines
python manage.py setup_db --engine=postgresql
python manage.py setup_db --engine=sqlite
# Create PostgreSQL user
python manage.py setup_db --create-user# Migrate from SQLite to PostgreSQL
python scripts/migrate_to_postgresql.py
# Manual migration
export DATABASE_ENGINE=postgresql
python manage.py migratekrill/
├── krill/ # Django project root (manage.py lives here)
│ ├── krill/ # Settings, URLs, WSGI
│ ├── person/ sample/ storage/ reports/ transaction/ # Django apps
│ └── management/ # Custom management commands
├── templates/ # Admin template overrides
├── tests/ # Anonymized data, fixtures, test scripts
├── scripts/ # Build, deploy and utility scripts
├── docs/ # Guides (see Documentation below)
├── Dockerfile, docker-compose.yml, app.yaml # Container and DO App Platform config
├── env.example # Environment template
└── pyproject.toml, uv.lock
Create a .env file based on the provided templates:
env.example- Basic configuration for developmentdocs/deployment/env.production.example- Production configuration with PostgreSQL
| Variable | Description | Default |
|---|---|---|
DATABASE_ENGINE |
Database engine (sqlite or postgresql) |
sqlite |
DB_NAME |
Database name | krill |
DB_USER |
Database user | krill_user |
DB_PASSWORD |
Database password | - |
DJANGO_SECRET_KEY |
Django secret key | auto-generated |
DJANGO_DEBUG |
Debug mode | True |
# Run all tests
python manage.py test
# Run specific app tests
python manage.py test sample
python manage.py test storage
# Run with coverage
coverage run --source='.' manage.py test
coverage report# Security linting
bandit -r .
# Dependency vulnerability check
uv run pip-audit
# Code formatting
black .- Set
DJANGO_DEBUG=False - Use PostgreSQL database
- Configure environment variables
- Set up SSL/HTTPS
- Configure static file serving
- Set up logging and monitoring
- Configure backups
- Set up CI/CD pipeline
# Build and run with Docker
docker build -t krill .
docker run -p 8000:8000 --env-file .env krill
# Or use Docker Compose
docker-compose up -dContributions are welcome! Please see CONTRIBUTING.md for guidelines on how to contribute to this project.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Add tests for new functionality
- Ensure all tests pass (
make test-local) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Getting started and contributing
- CONTRIBUTING.md - Development workflow and guidelines
- Testing Guide - Running tests and using anonymized test data
- Test Data Anonymization - How the anonymized dataset is produced
- Utility Scripts - Helper scripts (whitespace cleanup, PostgreSQL migration)
- Security Notes - Security configuration and checks
Using Krill
- Reports and storage audits - Spot-check storage, resume and review audits, alerts
Data
- Data Import Guide - How to structure CSV files for importing sample data
- Database Setup Guide - SQLite and PostgreSQL configuration
Deployment
- Deployment Guide - Docker images, environment variables, security checklist, troubleshooting
- DigitalOcean App Platform - Platform-specific setup and
doctlcommands
See also the docs index.
For issues and questions:
- Check the documentation above
- Search existing issues
- Create a new issue with detailed information
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
- Django framework and community
- PostgreSQL database
- Open source contributors