second commit

SETUP_GUIDE.md

@@ -0,0 +1,416 @@
+# 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.