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:

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):

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

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!)

# 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

# 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

# Stop container
docker stop npmplus

# Remove container (volumes are preserved)
docker rm npmplus

Step 4: Create New Container

# 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

# 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

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

   docker logs npmplus --tail 50
   

2. Check volumes:

   docker inspect npmplus --format '{{range .Mounts}}{{.Source}}:{{.Destination}} {{end}}'
   

3. Restore from backup (if needed):

   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):

   ssh root@r630-01
   docker pull zoeyvid/npmplus:2026-01-20-r2
   

2. Import to container's Docker:

   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:

# 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