docs: add 1.x to 2.0 migration guide pointer and community note (#448)

Root MIGRATING.md pointer + README upgrading link + 1.x community note across README/MIGRATING/docs; drop stale v2.0.0 callout.

Claude-Session: https://claude.ai/code/session_01P22pYJttXCe5cbCzRyfZac
This commit is contained in:
SnapOtter
2026-07-06 18:50:27 +08:00
committed by GitHub
parent d019217969
commit e09feadd68
3 changed files with 44 additions and 2 deletions
+36
View File
@@ -0,0 +1,36 @@
# Migrating from 1.x to 2.0
SnapOtter 1.x stored everything in a single SQLite file. 2.0 uses PostgreSQL and Redis. When you upgrade, 2.0 imports your 1.x database automatically on first boot, as long as it mounts your existing `/data` volume. Your users, saved files, settings, API keys, and pipelines come across, and the old database is never modified, so you can roll back.
> [!NOTE]
> A word to our 1.x users: many of you have been here since the start, and your trust and your feedback are why this guide exists. 2.0 changes a lot under the hood, and the whole point of the steps below is that your data comes with you and nothing you rely on breaks. Take the backup step, follow the path that matches your setup, and you'll land on 2.0 with everything intact.
## Back up the entire /data volume first
Do this before you upgrade. Back up the whole `/data` volume, not the `snapotter.db` file alone.
1.x runs SQLite in WAL mode, so a stopped container usually leaves most of its committed data in `snapotter.db-wal` beside an almost-empty `snapotter.db`. Copy only `snapotter.db` and you capture an empty database. The volume carries `snapotter.db`, `snapotter.db-wal`, `snapotter.db-shm`, and your `files/` directory together, and they have to travel as a set.
```bash
# Adjust the volume name to match yours: docker volume ls | grep -i snapotter
docker run --rm -v SnapOtter-data:/data -v "$PWD":/backup \
alpine tar czf /backup/snapotter-1x-data.tgz -C /data .
```
## Quick upgrade (single container)
Upgrade your 1.x install to 1.17.2 first so it runs its final schema migrations. Then point the 2.0 image at the same volume:
```bash
docker run -d --name snapotter -p 1349:1349 \
-v SnapOtter-data:/data \
snapotter/snapotter:latest
```
2.0 detects `/data/snapotter.db` and imports it on first boot. Log in with your existing credentials.
## Full guide
Compose upgrades, a dry-run preview, exactly what carries over, turning the import off, and rollback are all covered in the complete guide:
**https://docs.snapotter.com/guide/upgrading**
+4 -2
View File
@@ -2,8 +2,9 @@
<img src="branding/social-preview.png" width="800" alt="SnapOtter - A Self-Hosted File Manipulation Suite">
</p>
> [!NOTE]
> **SnapOtter v2.0.0** is the current monorepo version, with 200+ tools across image, video, audio, PDF, and files. For published image channels and GPU variants, see the Docker Tags guide.
<!-- TEMP: 1.x to 2.0 migration note. Remove once 2.0 has been out for a while and most users have upgraded. -->
> [!IMPORTANT]
> **Coming from 1.x?** Many of you have trusted SnapOtter since day one, and your feedback and suggestions shaped everything that followed. 2.0 is a big step, and we worked to make sure it doesn't break what you already depend on. Your accounts, saved files, settings, API keys, and pipelines carry over automatically on first boot, and your old database is never modified. We wrote a full [migration guide](./MIGRATING.md) so the move is safe and boring. Thank you for being here.
<p align="center">
<a href="https://hub.docker.com/r/snapotter/snapotter"><img src="https://img.shields.io/docker/v/snapotter/snapotter?label=Docker%20Hub&logo=docker" alt="Docker Hub"></a>
@@ -119,6 +120,7 @@ For Docker Compose, persistent storage, and other setup options, see the [Gettin
## Documentation
- [Getting Started](https://docs.snapotter.com/guide/getting-started)
- [Upgrading from 1.x to 2.0](https://docs.snapotter.com/guide/upgrading)
- [Configuration](https://docs.snapotter.com/guide/configuration)
- [OIDC / SSO](https://docs.snapotter.com/guide/oidc)
- [Deployment](https://docs.snapotter.com/guide/deployment)
+4
View File
@@ -4,6 +4,10 @@ SnapOtter 1.x stored everything in a single SQLite file and ran as one container
The short version: reuse your existing `/data` volume, and 2.0 imports your 1.x database automatically on first boot. Your users, saved files, settings, API keys, and pipelines come across. The old database is never modified, so you can always roll back.
::: tip A note for our 1.x users
Many of you have trusted SnapOtter since day one, and your feedback shaped this release. 2.0 changes a lot under the hood, and this guide exists so the move doesn't cost you anything you care about. Your accounts, files, settings, API keys, and pipelines carry over, and your old database is never touched. Thank you for upgrading with us.
:::
## Before you start: back up the whole `/data` volume
Do this first, every time. Back up the **entire** `/data` volume, not just the `snapotter.db` file.