Upgrading

Upgrade Process

1. Backup Your Data

Always backup before upgrading:

cp database.json database.backup.$(date +%Y%m%d).json
cp settings.json settings.backup.json
cp .env .env.backup

2. Pull Latest Changes

git fetch origin
git checkout main
git pull origin main

3. Check the Changelog

Review the release notes and changelog for:

• Breaking changes
• New required environment variables
• Database format changes
• Dependency updates

4. Install Updated Dependencies

npm install

5. Check for New Environment Variables

Compare .env.example with your .env:

diff .env.example .env

Add any new required variables to your .env.

6. Run Migrations (if any)

If the release includes database format changes, LiveFolio handles them automatically on first run:

npm run dev
# Check console output for migration messages

7. Verify

# Dashboard renders
curl -s http://localhost:3000/dashboard | head -5

# API works
curl -s http://localhost:3000/api/files

# MCP responds
curl -s -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Version Compatibility

Database Format

LiveFolio OSS stores data in database.json with a stable schema. The flat-file format is designed to be backward-compatible. Breaking changes to the database schema are rare and always documented in the release notes.

API Compatibility

The REST API and MCP tools maintain backward compatibility. Deprecated endpoints are supported for at least one major version before removal.

Node.js Version

LiveFolio requires Node.js 18+. Check your version:

node --version
# Should be v18.x.x or v20.x.x

Downgrading

If an upgrade causes issues:

1. Restore the backup:

   cp database.backup.YYYYMMDD.json database.json
   

2. Checkout the previous version:

   git checkout <previous-version-tag>
   

3. Reinstall dependencies:

   npm install
   

4. Restart the server.

Troubleshooting Upgrades

"Module not found" after upgrade

rm -rf node_modules .next
npm install
npm run dev

Database won't load

Check database.json is valid JSON:

cat database.json | python3 -m json.tool > /dev/null && echo "Valid" || echo "Corrupted"

Build errors

rm -rf .next
npm run build

Check for TypeScript errors:

npx tsc --noEmit

Port already in use

lsof -ti:3000 | xargs kill
npm run dev

Staying Current

• Watch the GitHub repository for new releases
• Read the changelog before upgrading
• Test on a copy if you have production folios — copy database.json to a test directory and upgrade there first
• Join the community for upgrade announcements and migration guides