Upgrading Nexgent
Keep your Nexgent installation up to date with the latest features and security fixes.
Before Upgrading
⚠️
Always backup your database before upgrading. While migrations are tested, having a backup ensures you can recover if something goes wrong.
Pre-Upgrade Checklist
- Read the release notes (opens in a new tab) for breaking changes
- Backup your database
- Note your current version
- Plan for brief downtime (typically 2-5 minutes)
Check Current Version
# In your nexgent directory
git describe --tags
# Or check package.json
cat package.json | grep versionBackup Database
docker exec nexgent-postgres pg_dump -U postgres nexgent > backup_$(date +%Y%m%d).sqlUpgrade Process
Stop the Application
# If using PM2
pm2 stop all
# Or if running directly
# Ctrl+C to stop the processPull Latest Changes
cd ~/nexgent
git fetch origin
git checkout main
git pull origin mainUpdate Dependencies
pnpm installRun Database Migrations
pnpm --filter backend db:migrate:deployRebuild Application
pnpm buildRestart Application
# If using PM2
pm2 restart all
# Or start directly
pnpm startVerify Upgrade
curl http://localhost:4000/api/v1/healthHandling Breaking Changes
Identifying Breaking Changes
Breaking changes are marked in release notes with:
- BREAKING: prefix
- Major version bump (e.g., 1.x → 2.x)
Common Breaking Changes
Environment Variable Changes
If a variable is renamed or added:
# Check env.example for new variables
diff packages/backend/env.example packages/backend/.env
# Add any missing variables to your .envDatabase Schema Changes
Migrations handle schema changes automatically. If a migration fails:
# Check migration status
pnpm --filter backend prisma migrate status
# If stuck, check the failed migration
cat packages/backend/src/infrastructure/database/migrations/*/migration.sqlAPI Changes
If you have external integrations:
- Check API documentation for changes
- Update API keys if required
- Test integrations after upgrade
Rollback Procedures
If an upgrade causes issues, roll back to the previous version.
Rollback Steps
Stop Application
pm2 stop allCheckout Previous Version
# Find the previous version tag
git tag --list
# Checkout that version
git checkout v1.2.3Restore Dependencies
pnpm installRestore Database (if needed)
# If migration caused issues, restore from backup
psql -h localhost -U nexgent -d nexgent < backup_20250120.sqlRebuild and Restart
pnpm build
pm2 restart all⚠️
Database rollback may cause data loss for any data created after the upgrade. Only restore if necessary.
Automated Updates
For advanced users, you can automate updates:
Update Script
#!/bin/bash
# /home/nexgent/update.sh
set -e # Exit on error
cd ~/nexgent
echo "Creating backup..."
PGPASSWORD=$DB_PASSWORD pg_dump -h localhost -U nexgent nexgent > ~/backups/pre_update_$(date +%Y%m%d_%H%M%S).sql
echo "Pulling latest changes..."
git fetch origin
git checkout main
git pull origin main
echo "Installing dependencies..."
pnpm install
echo "Running migrations..."
pnpm --filter backend db:migrate:deploy
echo "Building..."
pnpm build
echo "Reloading application..."
pm2 reload all
echo "Verifying health..."
sleep 5
if curl -s http://localhost:4000/api/v1/health | grep -q "ok"; then
echo "Update successful!"
else
echo "Health check failed! Check logs with: pm2 logs"
exit 1
fiScheduled Updates (Optional)
⚠️
Automated updates can be risky. Only use if you have good monitoring and rollback procedures.
# Weekly update on Sunday at 3 AM
0 3 * * 0 /home/nexgent/update.sh >> /home/nexgent/logs/update.log 2>&1Version Compatibility
Node.js Compatibility
| Nexgent Version | Node.js Version |
|---|---|
| 0.1.x | 18.x, 20.x |
| 1.0.x | 18.x, 20.x, 22.x |
Database Compatibility
| Nexgent Version | PostgreSQL Version |
|---|---|
| All | 14.x, 15.x, 16.x |
Breaking Version History
| Version | Breaking Changes |
|---|---|
| - | None yet (initial release) |
Getting Help
If you encounter issues during upgrade:
- Check logs:
pm2 logsor deployment logs - Review release notes: GitHub Releases (opens in a new tab)
- Search issues: GitHub Issues (opens in a new tab)
- Ask for help: GitHub Discussions (opens in a new tab)