Upgrade

3 min readStableIntermediate

Move an existing OwnDocs project to a newer release with the owndocs CLI, which backs up your project first and never touches the files you own.

Don't upgrade by extracting a new archive over your project folder. A plain extract has no idea which files are yours, so it can overwrite content/, custom/, and your .env files along with the framework code. The owndocs CLI checks every managed file against a manifest before it changes anything, so your pages and settings survive the upgrade untouched.

Prerequisites

An existing OwnDocs project, installed by following Installation.
The release payload for the version you're moving to: a manifest.json file and a payload/ folder, sent to you the same way your original archive was. Place them at .owndocs/release/<version>/ in your project (matching the version number in the folder name), or save them anywhere and point --payload at that folder.

Steps

Check what's changed since your last upgrade
Bash
Bash
```
npm run owndocs -- status
```
This compares your project against .owndocs/manifest.json and lists any managed file you've edited, any that's missing, and any untracked file sitting in a managed folder. It doesn't touch anything.
Preview the upgrade
Bash
Bash
```
npm run owndocs -- upgrade --dry-run
```
--dry-run prints a report — files added, updated, removed, and any conflicts — without writing to disk or creating a backup. If you have a specific version in mind rather than the newest available payload, add --to <version>.
Run the upgrade
Bash
Bash
```
npm run owndocs -- upgrade
```
The CLI backs up your whole project to .owndocs/backups/<timestamp>/ before it changes a single file, then applies every added and updated file. A file you've edited yourself counts as a conflict, and you get three ways to handle it:
- Run interactively (the default in a terminal) and answer yes or no for each conflicting file as it comes up.
- Add --overwrite to replace every conflicting file with the release version.
- Add --no-overwrite to keep every conflicting file exactly as you have it.
Confirm the upgrade
Bash
Bash
```
npm run owndocs -- status
```
A clean upgrade reports zero modified and zero missing managed files.

Result

Your project now runs the new release version, your content/, custom/, snippets/, public/, data/, and .env files are exactly as you left them, and a full backup of the pre-upgrade project sits in .owndocs/backups/.

Troubleshooting

If the upgrade produced something you didn't expect, restore the backup it made automatically:

Bash

npm run owndocs -- restore

restore uses your most recent backup by default. To restore a specific one, list your backups under .owndocs/backups/ and pass its folder name with --id <backupId>. Restoring replaces the project with that backup, including anything you changed since it was made, so use it to undo a bad upgrade, not as a routine undo button.

Installation

Deployment

Configuration

Was this page helpful?