explorer-monorepo/NPMPLUS_UPDATE_GUIDE.md

# NPMplus Update Guide - 2026-01-20-r2

**Date**: 2026-01-21  
**Target Version**: `zoeyvid/npmplus:2026-01-20-r2`  
**Current Version**: `zoeyvid/npmplus:latest`

---

## Release Notes

According to the [GitHub release](https://github.com/ZoeyVid/NPMplus/releases/tag/2026-01-20-r2):

### Key Changes
- ✅ Fix: zstd module CPU usage when proxy buffering is disabled
- ✅ Add unzstd module (always enabled)
- ✅ Replace broken PowerDNS DNS plugin (certs need to be recreated, not renewed)
- ✅ Streams: Add TLS to upstream button
- ✅ Streams: Temporarily disable cert creation in streams form
- ✅ Redirect to OIDC if password login is disabled
- ✅ Fix: Login as other user
- ✅ Proxy hosts: Add button to block AI/crawler/search bots
- ✅ Certbot now checks for renewals every 6 hours
- ✅ Dependency updates
- ✅ Language updates

### ⚠️ Important Notes
- **Create backup before upgrading** (as always recommended)
- **PowerDNS DNS plugin replaced** - certificates need to be **recreated** (not renewed) if using PowerDNS

---

## Update Methods

### Method 1: Manual Update (Recommended)

**Run directly on Proxmox host (r630-01):**

```bash
# SSH to Proxmox host
ssh root@192.168.11.10
ssh root@r630-01

# 1. Create backup
mkdir -p /data/npmplus-backups
docker exec npmplus tar -czf /tmp/npmplus-backup-$(date +%Y%m%d_%H%M%S).tar.gz -C /data .
docker cp npmplus:/tmp/npmplus-backup-$(date +%Y%m%d_%H%M%S).tar.gz /data/npmplus-backups/
docker exec npmplus rm -f /tmp/npmplus-backup-*.tar.gz

# 2. Pull new image
docker pull zoeyvid/npmplus:2026-01-20-r2

# 3. Stop container
docker stop npmplus

# 4. Get volume mounts
docker inspect npmplus --format '{{range .Mounts}}-v {{.Source}}:{{.Destination}} {{end}}'

# 5. Remove old container
docker rm npmplus

# 6. Create new container with updated image
docker run -d \
  --name npmplus \
  --restart unless-stopped \
  --network bridge \
  -p 80:80 \
  -p 443:443 \
  -p 81:81 \
  -v /data/npmplus:/data \
  -v /data/letsencrypt:/etc/letsencrypt \
  zoeyvid/npmplus:2026-01-20-r2

# 7. Verify
docker ps --filter name=npmplus
curl -I http://192.168.11.167:80
```

### Method 2: Automated Script

**Run from your local machine:**

```bash
cd /home/intlc/projects/proxmox/explorer-monorepo
bash scripts/update-npmplus.sh
```

**Note**: Script may timeout on Docker pull if network is slow. In that case, use Method 1.

---

## Update Steps (Detailed)

### Step 1: Backup (Critical!)

```bash
# On Proxmox host (r630-01)
ssh root@r630-01

# Create backup directory
mkdir -p /data/npmplus-backups

# Backup from container
docker exec npmplus tar -czf /tmp/npmplus-backup-$(date +%Y%m%d_%H%M%S).tar.gz -C /data .
docker cp npmplus:/tmp/npmplus-backup-*.tar.gz /data/npmplus-backups/
docker exec npmplus rm -f /tmp/npmplus-backup-*.tar.gz

# Verify backup
ls -lh /data/npmplus-backups/
```

### Step 2: Pull New Image

```bash
# Pull new image (may take 2-5 minutes)
docker pull zoeyvid/npmplus:2026-01-20-r2

# Verify image
docker images | grep npmplus
```

### Step 3: Stop and Remove Old Container

```bash
# Stop container
docker stop npmplus

# Remove container (volumes are preserved)
docker rm npmplus
```

### Step 4: Create New Container

```bash
# Create new container with updated image
docker run -d \
  --name npmplus \
  --restart unless-stopped \
  --network bridge \
  -p 80:80 \
  -p 443:443 \
  -p 81:81 \
  -v /data/npmplus:/data \
  -v /data/letsencrypt:/etc/letsencrypt \
  zoeyvid/npmplus:2026-01-20-r2
```

### Step 5: Verify Update

```bash
# Check container status
docker ps --filter name=npmplus

# Check version
docker inspect npmplus --format '{{.Config.Image}}'

# Test accessibility
curl -I http://192.168.11.167:80
curl -I https://192.168.11.167:81 -k

# Test proxy functionality
curl -H "Host: explorer.d-bis.org" http://192.168.11.167:80
```

---

## Post-Update Tasks

### 1. Verify NPMplus Dashboard

- Access: `https://192.168.11.167:81`
- Login with credentials
- Check that all proxy hosts are still configured

### 2. Recreate Certificates (If Using PowerDNS)

**⚠️ Important**: If you were using PowerDNS DNS plugin, certificates need to be **recreated** (not renewed):

1. Go to SSL Certificates
2. Delete old certificates that used PowerDNS
3. Create new Let's Encrypt certificates
4. Reassign to proxy hosts

### 3. Test External Access

```bash
# From external network
curl -I https://explorer.d-bis.org

# Should work without SSL errors (if certificate is configured)
```

---

## Troubleshooting

### If Container Fails to Start

1. **Check logs**:
   ```bash
   docker logs npmplus --tail 50
   ```

2. **Check volumes**:
   ```bash
   docker inspect npmplus --format '{{range .Mounts}}{{.Source}}:{{.Destination}} {{end}}'
   ```

3. **Restore from backup** (if needed):
   ```bash
   docker stop npmplus
   docker rm npmplus
   # Restore backup
   docker run -d --name npmplus --restart unless-stopped \
     --network bridge -p 80:80 -p 443:443 -p 81:81 \
     -v /data/npmplus:/data -v /data/letsencrypt:/etc/letsencrypt \
     zoeyvid/npmplus:latest
   ```

### If Network Timeout During Pull

1. **Pull from Proxmox host** (better network):
   ```bash
   ssh root@r630-01
   docker pull zoeyvid/npmplus:2026-01-20-r2
   ```

2. **Import to container's Docker**:
   ```bash
   docker save zoeyvid/npmplus:2026-01-20-r2 | \
     pct exec 10233 -- docker load
   ```

### If Proxy Hosts Missing

Proxy hosts are stored in the database, so they should persist. If missing:

1. Check NPMplus dashboard
2. Verify database is mounted correctly
3. Restore from backup if needed

---

## Rollback (If Needed)

If the update causes issues:

```bash
# Stop new container
docker stop npmplus
docker rm npmplus

# Restore old image
docker run -d \
  --name npmplus \
  --restart unless-stopped \
  --network bridge \
  -p 80:80 \
  -p 443:443 \
  -p 81:81 \
  -v /data/npmplus:/data \
  -v /data/letsencrypt:/etc/letsencrypt \
  zoeyvid/npmplus:latest
```

---

## Summary

**Status**: ⚠️ **READY TO UPDATE**

**Recommended Method**: Manual update on Proxmox host (Method 1)

**Time Required**: 5-10 minutes

**Risk Level**: Low (backup created, volumes preserved)

**Next Step**: Run update commands on Proxmox host (r630-01)

---

**Action**: SSH to r630-01 and run update commands manually