A wellmade/helpful readme made posible by Github Copilot
Pit Tracker is a Django-based tool management system designed for robotics teams and similar organizations to efficiently track, manage, and control the loaning of tools and equipment. The platform provides a secure, user-friendly interface for both regular users and administrators, allowing teams to:
- Record and monitor which tools are checked out and by whom
- Manage user accounts and permissions
- View real-time statistics on tool usage and active loans
- Ensure accountability and reduce tool loss or misplacement
With features like email-based authentication, admin controls, and a modern dark theme, Pit Tracker streamlines tool management in fast-paced environments such as robotics competitions, workshops, or school labs.
- User Authentication: Secure login system with email-based authentication
- Tool Tracking: Record, edit, and return tool loans
- User Management: Admin users can create and manage other users
- Dark Theme: Modern, responsive interface optimized for pit environments
- Real-time Statistics: Track active loans, returned tools, and usage metrics
- Admin Controls: Separate permissions for regular users and administrators
- Backend: Django 5.2.6
- Database: SQLite (development) / PostgreSQL (production)
- Frontend: HTML5, CSS3, JavaScript
- Authentication: Django's built-in auth system with custom user model
- Deployment: Gunicorn + Nginx
- Python 3.11+
- Git
- Virtual environment (recommended)
git clone https://github.com/yourusername/PitTraker.git
cd PitTraker- Ubuntu 20.04+ or similar Linux distribution
- Python 3.11+
- PostgreSQL
- Nginx
- Supervisor (for process management)
# Update system packages
sudo apt update &∓& sudo apt upgrade -y
# Install required packages
sudo apt install python3.11 python3.11-venv python3-pip postgresql postgresql-contrib nginx supervisor git -y
# Create application user
sudo adduser pittracker
sudo usermod -aG sudo pittrackerer# Switch to postgres user and create database
sudo -u postgres psql
CREATE DATABASE pittracker_dbdb;
CREATE USER pittracker_user WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE pittracker_db TO pittracker_userr;
\q# Switch to application user
sudo su - pittracker
# Clone repository
git clone https://github.com/yourusername/PitTraker.git
cd PitTraker
# Create virtual environment
python3.11 -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
pip install gunicorn psycopg2-binary
# Create production settings
cp .env.example .envvEdit the .env file with production values:
DEBUG=False
SECRET_KEY=your_very_secure_secret_key_here
DATABASE_URL=postgresql://pittracker_user:your_secure_password@localhost:5432/pittracker_db
ALLOWED_HOSTS=your-domain.com,www.your-domain.com,server-ip-addressess# Run migrations
python manage.py migrate
# Collect static files
python manage.py collectstatic --noinput
# Create superuser
python manage.py createsuperuserrCreate /home/pittracker/PitTraker/gunicorn.conf.py:
bind = "127.0.0.1:8000"
workers = 3
timeout = 120
keepalive = 5
max_requests = 1000
max_requests_jitter = 100Create /etc/supervisor/conf.d/pittracker.conf:
[program:pittracker]
command=/home/pittracker/PitTraker/venv/bin/gunicorn --config /home/pittracker/PitTraker/gunicorn.conf.py pit_tracker.wsgi:application
directory=/home/pittracker/PitTraker
user=pittracker
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile=/var/log/pittracker.logCreate /etc/nginx/sites-available/pittracker:
server {
listen 80;
server_name your-domain.com www.your-domain.com;
location /static/ {
alias /home/pittracker/PitTraker/staticfiles/;
expires 30d;
add_header Cache-Control "public, immutable";
}
location /media/ {
alias /home/pittracker/PitTraker/media/;
}
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}# Enable Nginx site
sudo ln -s /etc/nginx/sites-available/pittracker /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
x
# Start supervisor services
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start pittrackerker# Install Certbot
sudo apt install certbot python3-certbot-nginx -y
# Obtain SSL certificate
sudo certbot --nginx -d your-domain.com -d www.your-domain.commTo update the application:
# Switch to application user
sudo su - pittracker
cd PitTraker
# Pull latest changes
git pull origin main
# Activate virtual environment
source venv/bin/activate
# Install any new dependencies
pip install -r requirements.txt
# Run migrations
python manage.py migrate
# Collect static files
python manage.py collectstatic --noinput
# Restart application
sudo supervisorctl restart pittrackerr- Change default passwords and secret keys
- Configure firewall (UFW):
sudo ufw enable && sudo ufw allow ssh && sudo ufw allow 'Nginx Full'low 'Nginx Full' - Regularly update system packages
- Monitor application logs:
sudo tail -f /var/log/pittracker.log - Set up automated backups for PostgreSQL database
- macOS 10.15+ (Catalina or newer)
- Homebrew package manager
- Python 3.11+
# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install required packages
brew install [email protected] postgresql git
brew services start postgresqlql# Create database and user
createdb pittracker_db
psql pittracker_db -c c "CREATE USER pittracker_user WITH PASSWORD 'your_secure_password';"
psql pittracker_db -c "GRANT ALL PRIVILEGES ON DATABASE pittracker_db TO pittracker_user;"# Clone repository
git clone https://github.com/yourusername/PitTraker.git
cd PitTraker
# Create virtual environment
python3.11 -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
pip install gunicorn psycopg2-binary
# Create production settings
cp .env.example .envvEdit the .env file:
DEBUG=False
SECRET_KEY=your_very_secure_secret_key_here
DATABASE_URL=postgresql://pittracker_user:your_secure_password@localhost:5432/pittracker_db
ALLOWED_HOSTS=localhost,127.0.0.1,your-domain.comcom# Run migrations
python manage.py migrate
# Create superuser
python manage.py createsuperuser
# Collect static files
python manage.py collectstatic --noinputtgunicorn --bind 0.0.0.0:8000 PitTraker.wsgi:application
python manage.py runserver 0.0.0.0:8000
### 🔧 Troubleshooting
If you get `ModuleNotFoundError`, try these steps:
1. **Check project structure:**
```bash
# List all Python files to identify the main project directory
find . -name "*.py" | head -10
ead -10
-
Find settings.py location:
find . -name "settings.py" -type f
-
Use the directory name containing settings.py:
# If settings.py is in ./myproject/settings.py, use: gunicorn --bind 0.0.0.0:8000 myproject.wsgi:applicationn -
Alternative: Use Django development server:
python manage.py runserver 0.0.0.0:8000
The server will be available at http://localhost:8000
For development with auto-reload:
# Activate virtual environment
source venv/bin/activate
# Run development server
python manage.py runserver 0.0.0.0:80000cd PitTraker
source venv/bin/activate
# Pull latest changes
git pull origin main
# Install dependencies
pip install -r requirements.txt
# Run migrations
python manage.py migrate
# Collect static files
python manage.py collectstatic --noinput
# Restart server
gunicorn --bind 0.0.0.0:8000 pit_tracker.wsgi:applicationn- Change default passwords and secret keys
- Configure macOS firewall in System Preferences > Security & PrivacyPrivacy
- Regularly update Homebrew packages:
brew update && brew upgrade upgrade - Monitor application logs:
tail -f /usr/local/var/log/pittracker.log - Set up Time Machine backups for the database and application