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

```bash
sudo apt update
sudo apt upgrade -y
```

### 2. Install Node.js and npm

```bash
# 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)

```bash
sudo apt install git -y
```

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

```bash
sudo apt install build-essential -y
```

## Project Setup

### 1. Clone or Copy the Project

If you have the project in a git repository:
```bash
git clone <your-repository-url>
cd qr-inventory-system
```

If you're copying the files directly:
```bash
# Copy your project files to the VM
# Navigate to the project directory
cd /path/to/your/project
```

### 2. Install Dependencies

```bash
# 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:
```bash
cp .env.example .env 2>/dev/null || touch .env
```

Edit the `.env` file:
```bash
nano .env
```

Add the following configuration:
```env
# 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

```bash
# 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:
```bash
npm run dev
```

The application will be available at:
- **Local**: `http://localhost:3000`
- **Network**: `http://<your-vm-ip>:3000`

### Production Mode

For production deployment:
```bash
# 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

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

Add the following content:
```ini
[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

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
sudo apt install nginx -y
```

### 2. Create Nginx Configuration

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

Add the following configuration:
```nginx
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

```bash
# 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

```bash
sudo apt install certbot python3-certbot-nginx -y
```

### 2. Obtain SSL Certificate

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

### 3. Auto-renewal Setup

```bash
# 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
```bash
# Find process using port 3000
sudo lsof -i :3000

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

#### 2. Permission denied errors
```bash
# 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
```bash
# Check if database file exists
ls -la db/custom.db

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

#### 4. Build errors
```bash
# 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:
```bash
curl http://localhost:3000/api/health
```

## Maintenance

### Database Backup

```bash
# 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

```bash
# 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:

```bash
# 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.