Snipe-IT Collaborative Development Environment

A Docker-based development environment for Snipe-IT that enables teams to collaborate by sharing inventory data through git version control.

Prerequisites

Before running the setup script, install these system-level tools:

1. 🐳 Docker

Windows/macOS:

Download and install Docker Desktop

Linux:

Install Docker Engine + Docker Compose:

# Ubuntu/Debian
sudo apt install docker.io docker-compose-plugin
sudo usermod -aG docker $USER

# Fedora/RHEL
sudo dnf install docker docker-compose
sudo systemctl start docker && sudo systemctl enable docker
sudo usermod -aG docker $USER

2. 📝 Git

macOS:

Pre-installed, or install via Homebrew:
```
brew install git
```

Windows:

Download Git for Windows or install via winget:
```
winget install Git.Git
```

Linux:

Usually pre-installed, or install via package manager:

# Ubuntu/Debian
sudo apt install git

# Fedora/RHEL
sudo dnf install git

3. 🔧 direnv (Environment Management)

macOS:

brew install direnv

Windows:

winget install direnv.direnv

Linux:

# Ubuntu/Debian
sudo apt install direnv

# Fedora/RHEL
sudo dnf install direnv

Shell Integration (required for all platforms):

# Add to ~/.bashrc or ~/.zshrc
eval "$(direnv hook bash)"  # For bash
eval "$(direnv hook zsh)"   # For zsh

4. ✅ Verification

After installation, verify all tools are available:

docker --version
git --version
direnv version

Note: The setup script will automatically install the uv package manager - no separate installation needed.

5. 🔐 Application Key Setup

Important: The SNIPE_APP_KEY must be the same for all team members to ensure database compatibility (session handling, password resets, etc.).

The setup script will guide you through configuring the APP_KEY automatically. It will:

Check if SNIPE_APP_KEY environment variable is set
If not, check if secrets/snipe_app_key.txt exists
If neither is properly configured, prompt you to either:
- Enter your team's existing APP_KEY, or
- Generate a new APP_KEY (for new teams)
Write the key to secrets/snipe_app_key.txt
Reload the environment so SNIPE_APP_KEY is available

Manual Setup (Optional)

If you prefer to set up the key manually:

For New Teams:

# Generate a new key
docker run --rm snipe/snipe-it:v7.0.13 php artisan key:generate --show

# Create the secrets file with your generated key
echo 'base64:your-generated-key-here' > secrets/snipe_app_key.txt

# Reload environment
direnv reload

For Existing Teams:

# Get the key from your team lead, then create the secrets file
echo 'base64:your-team-key-here' > secrets/snipe_app_key.txt

# Reload environment
direnv reload

Note: The setup script will automatically detect and handle APP_KEY configuration, so manual setup is usually not necessary.

🛠 Project Setup

Interactive Setup (Recommended):

Clone and setup:

git clone <your-repo-url>
cd snipe-it
uv run python scripts/setup_dev_environment.py

The setup script will guide you through each step:

📦 Install uv package manager (if needed)
🌍 Configure environment variables with direnv
🐍 Set up Python dependencies
🔗 Install git hooks for database backup
🔐 Configure SNIPE_APP_KEY for team collaboration
🐳 Verify Docker setup

Options:

# Skip all prompts (for automation)
uv run python scripts/setup_dev_environment.py --yes

# See what would be done without making changes
uv run python scripts/setup_dev_environment.py --dry-run

# Detailed logging
uv run python scripts/setup_dev_environment.py --verbose

# Skip Docker check
uv run python scripts/setup_dev_environment.py --skip-docker

# Combine options
uv run python scripts/setup_dev_environment.py --dry-run --verbose

Start the environment:
```
docker-compose up -d
```
Access Snipe-IT: Open http://localhost:8080 in your browser
First-time setup: Follow the Snipe-IT setup wizard (only needed once per team)

📚 Technology Roadmap

New to these technologies? Check out our comprehensive Technology Roadmap - a self-guided learning journey through Docker, MySQL, Python tooling, environment management, and more. Includes interactive diagrams, hands-on exercises, and learning resources for each technology in this stack.

🛠 What's Included

MySQL 8.0: Database server with health checks
Snipe-IT: Latest version with proper configuration
Pre-commit hooks: Automatic database backup on git commits
Database versioning: Shared inventory data through database.sql
Modern Python CLI: Cross-platform scripts using typer, requests, and loguru
Command-line tools: setup-snipe-it and backup-snipe-it commands

👥 Team Workflow

Making Changes

Start your environment: docker-compose up -d
Make changes via Snipe-IT web interface at http://localhost:8080

Commit your changes:

git add .
git commit -m "Added new assets and locations"

Push to share with team: git push

Getting Team Updates

Pull latest changes: git pull
Restart containers to load new data: docker-compose restart
Your Snipe-IT now has the latest team inventory data

Database Backup Process

Automatic: Database is backed up to database.sql on every git commit
Manual backup: Run uv run python scripts/backup_database.py main
Database restoration: Happens automatically when containers start

🛠 Management Commands

Container Management

# Start all services
docker-compose up -d

# Stop all services
docker-compose down

# View service status
docker-compose ps

# View logs
docker-compose logs snipe-it
docker-compose logs mysql

# Restart services
docker-compose restart

Database Management

# Manual database backup
uv run python scripts/backup_database.py main

# Reset database (⚠️ destroys all data)
docker-compose down -v
docker-compose up -d

# Access MySQL directly
docker-compose exec mysql mysql -u root -psnipe_root_password snipeit

Development Tools

Environment Variables (Automatic with direnv):

If you have direnv installed, environment variables are automatically loaded from .envrc. Otherwise, you can manually export them:

# View current environment (if direnv is working)
env | grep SNIPE_IT

# Manual export (if direnv not available)
export SNIPE_IT_BACKUP_MOUNT=/backup
export SNIPE_IT_MYSQL_TIMEOUT=30
export DB_ROOT_PASSWORD=snipe_root_password
export DB_NAME=snipeit
# ... etc

Available environment variables:

SNIPE_IT_BACKUP_MOUNT: Container path for database backups (default: /backup)
SNIPE_IT_MYSQL_TIMEOUT: MySQL connection timeout in seconds (default: 30)
DB_ROOT_PASSWORD, DB_NAME, DB_USER, DB_PASSWORD: Database configuration
APP_ENV, APP_DEBUG, APP_URL: Application configuration

Python Development Tools:

# Re-run interactive setup (safe to run multiple times)
uv run python scripts/setup_dev_environment.py

# Setup with options
uv run python scripts/setup_dev_environment.py --dry-run        # See what would be done
uv run python scripts/setup_dev_environment.py --verbose        # Detailed logging
uv run python scripts/setup_dev_environment.py --yes           # Skip all prompts
uv run python scripts/setup_dev_environment.py --skip-docker   # Skip Docker checks

# Manual database backup
uv run python scripts/backup_database.py main                   # Standard backup
uv run python scripts/backup_database.py main --verbose         # Detailed logging
uv run python scripts/backup_database.py main --output my-backup.sql # Custom output file
uv run python scripts/backup_database.py main --force           # Skip Docker checks

# Check if backup is possible
uv run python scripts/backup_database.py check

# Update pre-commit hooks
uv run pre-commit autoupdate

# Run pre-commit manually
uv run pre-commit run --all-files

# Python environment management with uv
uv sync --dev                    # Install/update dev dependencies
uv add --dev <package>           # Add new dev dependency
uv run <command>                 # Run command in virtual environment
uv python install 3.12          # Install specific Python version (Unix/macOS)

All commands work identically on Windows, macOS, and Linux!

🌐 Access Points

Service	URL	Credentials
Snipe-IT	http://localhost:8080	Set during first-time setup
MySQL	localhost:3306	root / snipe_root_password

📁 Project Structure

snipe-it/
├── docker-compose.yml          # Container definitions
├── pyproject.toml              # Python project config (modern dependencies)
├── uv.lock                     # Locked dependency versions
├── .venv/                      # Python virtual environment (auto-created)
├── .pre-commit-config.yaml     # Git hooks configuration
├── .gitignore                  # Git ignore rules (includes uv cache exclusions)
├── database.sql                # Shared database state (created after first use)
├── scripts/
│   ├── setup_dev_environment.py    # Modern setup CLI (typer + requests + loguru)
│   └── backup_database.py          # Modern backup CLI (typer + loguru)
└── README.md                   # This file

🔍 Troubleshooting

Services Won't Start

# Check Docker is running
docker info

# Check container health
docker-compose ps

# Reset everything
docker-compose down -v
docker-compose up -d

Database Issues

# Wait for MySQL to be ready (can take 30-60 seconds)
docker-compose logs mysql

# Check database connectivity
docker-compose exec mysql mysqladmin ping -h localhost -u root -psnipe_root_password

Python/uv Issues

# If uv command not found (shouldn't happen after setup)
uv run setup-snipe-it            # This will install uv if needed

# Sync dependencies if issues arise
uv sync --dev

# Reinstall pre-commit hooks
uv run pre-commit uninstall
uv run pre-commit install

# Check hook status
uv run pre-commit run --all-files

# View detailed logs for troubleshooting
uv run setup-snipe-it --verbose
uv run backup-snipe-it --verbose

Port Conflicts

If ports 8080 or 3306 are already in use:

Edit docker-compose.yml
Change port mappings (e.g., "8081:80" instead of "8080:80")
Restart: docker-compose down && docker-compose up -d

Permission Issues

# Fix script permissions (Unix/macOS) - not needed for modern CLI
# Scripts are now proper Python packages with entry points

# Fix Docker permissions (Linux)
sudo usermod -aG docker $USER
# Then log out and back in

Windows-Specific Issues

PowerShell Execution Policy

If you get execution policy errors:

# Run as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

uv Installation Issues

# Manual uv installation
irm https://astral.sh/uv/install.ps1 | iex

# Alternative: Download from GitHub releases
# Visit: https://github.com/astral-sh/uv/releases

Path Issues

If commands aren't found after installation:

Restart your terminal/command prompt
Check that Docker Desktop is running
Ensure uv is in your PATH (restart terminal after installation)

🚚 Migration to Production

When ready to move to hosted MySQL:

Export data: uv run python scripts/backup_database.py main
Set up hosted MySQL (AWS RDS, Google Cloud SQL, etc.)
Update environment variables in your production deployment
Import data: mysql -h your-host -u user -p database < database.sql

⚡ Performance Tips

Faster startup: Keep containers running with docker-compose up -d
SSD recommended: Database performance depends on disk speed
Memory: Allocate at least 4GB RAM to Docker Desktop
Network: Use wired connection for large database syncs

🤝 Contributing

Make changes via Snipe-IT web interface
Test your changes work correctly
Commit with descriptive messages
Push to share with the team

📞 Support

Snipe-IT Documentation: https://snipe-it.readme.io/
Docker Issues: Check Docker Desktop status and logs
Git Issues: Ensure database.sql is being tracked and updated

🔐 Security Notes

This setup is for development only
Default passwords are used for convenience
Change all passwords before any production use
Database backup files may contain sensitive data - handle appropriately

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
backups		backups
data		data
scripts		scripts
secrets		secrets
.envrc.example		.envrc.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
README.md		README.md
TECHNOLOGY_ROADMAP.md		TECHNOLOGY_ROADMAP.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
uv.lock		uv.lock

devinnasar/nvt_inventory

Folders and files

Latest commit

History

Repository files navigation

Snipe-IT Collaborative Development Environment

Prerequisites

1. 🐳 Docker

2. 📝 Git

3. 🔧 direnv (Environment Management)

4. ✅ Verification

5. 🔐 Application Key Setup

Manual Setup (Optional)

🛠 Project Setup

Interactive Setup (Recommended):

📚 Technology Roadmap

🛠 What's Included

👥 Team Workflow

Making Changes

Getting Team Updates

Database Backup Process

🛠 Management Commands

Container Management

Database Management

Development Tools

Environment Variables (Automatic with direnv):

Python Development Tools:

🌐 Access Points

📁 Project Structure

🔍 Troubleshooting

Services Won't Start

Database Issues

Python/uv Issues

Port Conflicts

Permission Issues

Windows-Specific Issues

PowerShell Execution Policy

uv Installation Issues

Path Issues

🚚 Migration to Production

⚡ Performance Tips

🤝 Contributing

📞 Support

🔐 Security Notes

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages