qrcode-inventory/DEPLOYMENT_CHECKLIST.md

QR Inventory Management System - Deployment Checklist

Pre-Deployment Checklist

System Requirements

• Debian 13 VM is ready
• Minimum 2GB RAM available
• Minimum 1GB free disk space
• Port 3000 is available
• Network connectivity is working

User Setup

• Non-root user account created
• User has sudo privileges
• SSH access is configured

Installation Steps

1. System Preparation

• Update system packages: sudo apt update && sudo apt upgrade -y
• Install Node.js 18+: curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - && sudo apt-get install -y nodejs
• Install Git: sudo apt install git -y
• Install build tools: sudo apt install build-essential -y
• Verify Node.js: node --version (should be 18+)
• Verify npm: npm --version

2. Project Setup

• Copy project files to VM
• Navigate to project directory: cd /path/to/project
• Install dependencies: npm install
• Create .env file with proper configuration
• Create database directory: mkdir -p db

3. Database Setup

• Generate Prisma client: npm run db:generate
• Push database schema: npm run db:push
• Verify database file exists: ls -la db/custom.db

4. Application Build

• Build the application: npm run build
• Check for build errors
• Verify .next directory was created

Testing Checklist

1. Development Mode Test

• Start development server: npm run dev
• Wait for "Ready on http://0.0.0.0:3000" message
• Access application at http://localhost:3000
• Verify all pages load correctly
• Test QR code generation
• Test QR code scanning
• Test inventory management features

2. Production Mode Test

• Stop development server (Ctrl+C)
• Start production server: npm start
• Access application at http://localhost:3000
• Verify all features work in production
• Check for any console errors

3. API Health Check

• Test health endpoint: curl http://localhost:3000/api/health
• Should return: {"status":"ok","message":"API is running"}
• Test inventory API: curl http://localhost:3000/api/inventory

Production Deployment

1. System Service Setup (Optional)

• Copy systemd service file: sudo cp qr-inventory.service /etc/systemd/system/
• Edit service file with correct user and path
• Reload systemd: sudo systemctl daemon-reload
• Enable service: sudo systemctl enable qr-inventory
• Start service: sudo systemctl start qr-inventory
• Check status: sudo systemctl status qr-inventory

2. Firewall Configuration

• Check if UFW is enabled: sudo ufw status
• Allow port 3000: sudo ufw allow 3000
• Or allow HTTP/HTTPS if using reverse proxy

3. Reverse Proxy Setup (Optional)

• Install Nginx: sudo apt install nginx -y
• Create Nginx configuration file
• Enable the site: sudo ln -s /etc/nginx/sites-available/qr-inventory /etc/nginx/sites-enabled/
• Test Nginx config: sudo nginx -t
• Restart Nginx: sudo systemctl restart nginx

4. SSL Certificate (Optional)

• Install Certbot: sudo apt install certbot python3-certbot-nginx -y
• Obtain certificate: sudo certbot --nginx -d your-domain.com
• Test auto-renewal: sudo certbot renew --dry-run

Network Access

1. Local Access

• Access via localhost: http://localhost:3000
• Verify all features work

2. Network Access

• Find VM IP address: hostname -I
• Access via IP: http://:3000
• Test from different machines on network

3. Domain Access (if configured)

• Access via domain: http://your-domain.com
• Test HTTPS: https://your-domain.com

Security Checklist

1. Basic Security

• Change default passwords if any
• Update system regularly
• Use SSH key authentication
• Disable root SSH login

2. Application Security

• Use HTTPS in production
• Set up proper environment variables
• Don't commit sensitive data to git
• Use strong database credentials

3. Network Security

• Configure firewall properly
• Only expose necessary ports
• Use fail2ban if needed
• Monitor access logs

Maintenance Checklist

1. Backup Setup

• Set up database backups
• Test backup restoration
• Set up off-site backups
• Document backup procedure

2. Monitoring

• Set up log monitoring
• Configure log rotation
• Set up alerts for downtime
• Monitor disk space

3. Updates

• Regular system updates: sudo apt update && sudo apt upgrade
• Update npm packages: npm update
• Check for security updates
• Test updates before deployment

Troubleshooting

1. Common Issues

• Port conflicts: Check with sudo lsof -i :3000
• Permission issues: Check file ownership
• Database issues: Check database file permissions
• Build errors: Clear .next directory and rebuild

2. Log Files

• Application logs: tail -f server.log
• Development logs: tail -f dev.log
• System service logs: sudo journalctl -u qr-inventory
• Nginx logs: sudo tail -f /var/log/nginx/access.log

3. Health Checks

• API health: curl http://localhost:3000/api/health
• Database connectivity: Check if db/custom.db exists
• Service status: sudo systemctl status qr-inventory

Final Verification

1. Full Application Test

• Add inventory item
• Generate QR code
• Scan QR code
• Update quantity
• Print labels
• Import/export data
• Test on mobile device

2. Performance Test

• Check page load times
• Test with multiple users
• Monitor memory usage
• Check database performance

3. Documentation

• Update setup documentation
• Document any custom configurations
• Create user guide
• Document backup procedures

---

Quick Start Commands

# Update system
sudo apt update && sudo apt upgrade -y

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install dependencies with legacy peer deps for React 19 compatibility
npm install --legacy-peer-deps

# Setup database
npm run db:generate
npm run db:push

# Build and run
npm run build
npm start

Emergency Commands

# Stop the application
sudo systemctl stop qr-inventory

# Restart the application
sudo systemctl restart qr-inventory

# Check logs
sudo journalctl -u qr-inventory -f

# Reset database
rm -f db/custom.db
npm run db:push

# Clean build
rm -rf .next
npm run build