qrcode-inventory/SETUP_GUIDE.md

QR Inventory Management System - Setup Guide for Debian 13

This guide will help you set up and run the QR Inventory Management System on your Debian 13 VM.

System Requirements

• OS: Debian 13 (Trixie)
• Node.js: Version 18 or higher
• Memory: Minimum 2GB RAM (4GB recommended)
• Storage: Minimum 1GB free space
• Network: Port 3000 accessible

Prerequisites Installation

1. Update System Packages

sudo apt update
sudo apt upgrade -y

2. Install Node.js and npm

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

# Verify installation
node --version
npm --version

3. Install Git (if not already installed)

sudo apt install git -y

4. Install Build Tools (required for some npm packages)

sudo apt install build-essential -y

Project Setup

1. Clone or Copy the Project

If you have the project in a git repository:

git clone <your-repository-url>
cd qr-inventory-system

If you're copying the files directly:

# Copy your project files to the VM
# Navigate to the project directory
cd /path/to/your/project

2. Install Dependencies

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

3. Set Up Environment Variables

Create a .env file in the project root:

cp .env.example .env 2>/dev/null || touch .env

Edit the .env file:

nano .env

Add the following configuration:

# Database Configuration
DATABASE_URL="file:./db/custom.db"

# Application Configuration
NODE_ENV="development"
PORT=3000
HOSTNAME="0.0.0.0"

# Optional: Add your domain if you have one
# NEXTAUTH_URL="http://your-domain.com"

4. Set Up Database

# Create database directory if it doesn't exist
mkdir -p db

# Generate Prisma client
npm run db:generate

# Push database schema
npm run db:push

Running the Application

Development Mode

For development with hot-reload:

npm run dev

The application will be available at:

• Local: http://localhost:3000
• Network: http://<your-vm-ip>:3000

Production Mode

For production deployment:

# Build the application
npm run build

# Start the production server
npm start

System Service Setup (Optional)

To run the application as a system service that starts automatically:

1. Create a Systemd Service File

sudo nano /etc/systemd/system/qr-inventory.service

Add the following content:

[Unit]
Description=QR Inventory Management System
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/your/project
ExecStart=/usr/bin/npm start
Restart=always
RestartSec=10
Environment=NODE_ENV=production
Environment=PORT=3000
Environment=HOSTNAME=0.0.0.0

[Install]
WantedBy=multi-user.target

2. Enable and Start the Service

# Reload systemd
sudo systemctl daemon-reload

# Enable the service to start on boot
sudo systemctl enable qr-inventory

# Start the service
sudo systemctl start qr-inventory

# Check service status
sudo systemctl status qr-inventory

3. View Logs

# View service logs
sudo journalctl -u qr-inventory -f

# Or view the application log
tail -f server.log

Firewall Configuration

If you have UFW (Uncomplicated Firewall) enabled:

# Allow port 3000
sudo ufw allow 3000

# Enable firewall if not already enabled
sudo ufw enable

# Check firewall status
sudo ufw status

Nginx Reverse Proxy (Optional)

For better security and to serve the application on a domain:

1. Install Nginx

sudo apt install nginx -y

2. Create Nginx Configuration

sudo nano /etc/nginx/sites-available/qr-inventory

Add the following configuration:

server {
    listen 80;
    server_name your-domain.com www.your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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;
        proxy_cache_bypass $http_upgrade;
    }
}

3. Enable the Site

# Create symbolic link
sudo ln -s /etc/nginx/sites-available/qr-inventory /etc/nginx/sites-enabled/

# Test Nginx configuration
sudo nginx -t

# Restart Nginx
sudo systemctl restart nginx

SSL Certificate (Optional)

For HTTPS with Let's Encrypt:

1. Install Certbot

sudo apt install certbot python3-certbot-nginx -y

2. Obtain SSL Certificate

sudo certbot --nginx -d your-domain.com -d www.your-domain.com

3. Auto-renewal Setup

# Test auto-renewal
sudo certbot renew --dry-run

# Auto-renewal is already set up by certbot

Application Features

Once running, the application provides:

• Inventory Management: Add, edit, delete inventory items
• QR Code Generation: Generate QR codes for inventory items
• QR Code Scanning: Scan QR codes to update inventory
• Excel/CSV Import: Import inventory data from spreadsheets
• Label Printing: Print labels for inventory items
• Real-time Updates: Live inventory updates via WebSocket
• Responsive Design: Works on desktop and mobile devices

Accessing the Application

1. Local Access: http://localhost:3000
2. Network Access: http://<your-vm-ip>:3000
3. Domain Access: http://your-domain.com (if configured)

Troubleshooting

Common Issues

1. Port 3000 is already in use

# Find process using port 3000
sudo lsof -i :3000

# Kill the process
sudo kill -9 <process-id>

2. Permission denied errors

# Fix file permissions
sudo chown -R your-username:your-username /path/to/your/project
chmod -R 755 /path/to/your/project

3. Database connection issues

# Check if database file exists
ls -la db/custom.db

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

4. Build errors

# Clean build
rm -rf .next
npm run build

Log Files

• Development logs: dev.log
• Production logs: server.log
• System service logs: sudo journalctl -u qr-inventory

Health Check

The application provides a health check endpoint:

curl http://localhost:3000/api/health

Maintenance

Database Backup

# Backup database
cp db/custom.db db/custom.db.backup.$(date +%Y%m%d)

# Restore database
cp db/custom.db.backup db/custom.db

Application Updates

# Pull latest changes (if using git)
git pull origin main

# Install new dependencies
npm install

# Rebuild for production
npm run build

# Restart service
sudo systemctl restart qr-inventory

Log Rotation

To prevent log files from growing too large:

# Create logrotate configuration
sudo nano /etc/logrotate.d/qr-inventory

Add the following content:

/path/to/your/project/server.log {
    daily
    missingok
    rotate 7
    compress
    delaycompress
    notifempty
    create 644 your-username your-username
}

Security Considerations

1. Firewall: Only expose necessary ports (3000 or 80/443 with Nginx)
2. Updates: Keep system and packages updated
3. Backups: Regular database backups
4. SSL: Use HTTPS in production
5. Authentication: Implement user authentication (NextAuth.js is included)

Support

If you encounter any issues:

1. Check the logs for error messages
2. Verify all prerequisites are installed
3. Ensure the database is properly configured
4. Check network connectivity and firewall settings

---

This setup guide should help you successfully deploy and run the QR Inventory Management System on your Debian 13 VM.