Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
012d122d55 | ||
|
|
8b9e577601 |
No files matched your search
@@ -0,0 +1,74 @@
|
|||||||
|
---
|
||||||
|
title: Upgrade from v1 to v2
|
||||||
|
sidebar_position: 2
|
||||||
|
tags:
|
||||||
|
- Getting started
|
||||||
|
- Upgrade
|
||||||
|
- Migration
|
||||||
|
- Backup
|
||||||
|
---
|
||||||
|
|
||||||
|
Homarr v2 upgrades the existing v1 database in place. Keep the same data storage, database configuration, and
|
||||||
|
`SECRET_ENCRYPTION_KEY`; only change the Homarr image or package version for the first start.
|
||||||
|
|
||||||
|
:::danger Back up before starting v2
|
||||||
|
|
||||||
|
In Homarr v1, go to **Management → Tools → Backup**, export a backup, and keep the downloaded file somewhere safe
|
||||||
|
before starting v2. See [Backup and restore](/docs/management/backup) for details.
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
## Upgrade
|
||||||
|
|
||||||
|
1. Pin the Homarr image to `ghcr.io/homarr-labs/homarr:v2.0.0` for the first v2 start.
|
||||||
|
2. Keep the existing `/appdata` mount, database variables, Redis configuration, and `SECRET_ENCRYPTION_KEY` unchanged.
|
||||||
|
3. Start one Homarr replica and follow its logs. Startup must reach `Migration complete`; Homarr aborts startup when a
|
||||||
|
database migration fails.
|
||||||
|
4. Open Homarr and sign in. Confirm **Management → About** reports v2 before starting additional replicas.
|
||||||
|
5. After validation, keep the version pinned or return to your normal stable release policy.
|
||||||
|
|
||||||
|
For Docker Compose, the change is limited to the image tag before the usual update:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
services:
|
||||||
|
homarr:
|
||||||
|
image: ghcr.io/homarr-labs/homarr:v2.0.0
|
||||||
|
```
|
||||||
|
|
||||||
|
```sh
|
||||||
|
docker compose pull
|
||||||
|
docker compose up -d
|
||||||
|
docker compose logs --follow homarr
|
||||||
|
```
|
||||||
|
|
||||||
|
Do not add `-v` when stopping the Compose deployment; that can remove named volumes.
|
||||||
|
|
||||||
|
## What v2 migrates
|
||||||
|
|
||||||
|
The startup migration:
|
||||||
|
|
||||||
|
- creates the Custom Widget v2, Assistant, header preference, and branding storage;
|
||||||
|
- adds Base/Mobile layout roles and left/right board gutters;
|
||||||
|
- converts legacy Categories and dynamic sections into Containers and rails;
|
||||||
|
- preserves legacy Custom Widget definitions, encrypted secrets, and board references for explicit migration.
|
||||||
|
|
||||||
|
Legacy Custom Widgets are not silently rewritten. In **Management → Custom Widgets**, entries marked
|
||||||
|
**Migration required** provide a credential-free migration prompt. Review and test the resulting v2 definition before
|
||||||
|
removing the archived v1 version. See [Custom Widgets: Import and Workshop](/docs/management/custom-widgets#import-and-workshop).
|
||||||
|
|
||||||
|
## Verify the upgraded instance
|
||||||
|
|
||||||
|
- Sign in with each enabled authentication method and verify administrator access.
|
||||||
|
- Open every important board on desktop and mobile. Check Containers, former Categories, rails, item placement, and
|
||||||
|
home-board assignments.
|
||||||
|
- Test at least one read and one permitted action for each critical integration. Recheck integration and board access
|
||||||
|
for representative Viewer, Editor, and Admin groups.
|
||||||
|
- Check Docker or Podman endpoints, search engines, uploaded media, trusted certificates, scheduled tasks, WebSockets,
|
||||||
|
and external Redis when used.
|
||||||
|
- Review every legacy Custom Widget and migrate it only after its v2 preview and requests work.
|
||||||
|
- Restart Homarr once more and confirm the logs contain no migration, database, Redis, authentication, or task errors.
|
||||||
|
|
||||||
|
## Roll back
|
||||||
|
|
||||||
|
Use the backup exported before the upgrade if you need to restore your v1 installation. Do not reuse a database that
|
||||||
|
v2 has already migrated with v1.
|
||||||
Generated
+29
-23
@@ -696,7 +696,6 @@ overrides:
|
|||||||
linkifyjs@<4.3.2: '>=4.3.3'
|
linkifyjs@<4.3.2: '>=4.3.3'
|
||||||
nanoid@>=4.0.0 <5.0.9: '>=5.1.16'
|
nanoid@>=4.0.0 <5.0.9: '>=5.1.16'
|
||||||
prismjs@<1.30.0: '>=1.30.0'
|
prismjs@<1.30.0: '>=1.30.0'
|
||||||
protobufjs@<7.5.5: '>=7.5.5 <8'
|
|
||||||
proxmox-api>undici: 7.28.0
|
proxmox-api>undici: 7.28.0
|
||||||
react-is: ^19.2.7
|
react-is: ^19.2.7
|
||||||
rollup@>=4.0.0 <4.22.4: '>=4.62.2'
|
rollup@>=4.0.0 <4.22.4: '>=4.62.2'
|
||||||
@@ -7088,26 +7087,29 @@ packages:
|
|||||||
'@protobufjs/base64@1.1.2':
|
'@protobufjs/base64@1.1.2':
|
||||||
resolution: {integrity: sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==}
|
resolution: {integrity: sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==}
|
||||||
|
|
||||||
'@protobufjs/codegen@2.0.5':
|
'@protobufjs/codegen@2.0.4':
|
||||||
resolution: {integrity: sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==}
|
resolution: {integrity: sha512-YyFaikqM5sH0ziFZCN3xDC7zeGaB/d0IUb9CATugHWbd1FRFwWwt4ld4OYMPWu5a3Xe01mGAULCdqhMlPl29Jg==}
|
||||||
|
|
||||||
'@protobufjs/eventemitter@1.1.1':
|
'@protobufjs/eventemitter@1.1.0':
|
||||||
resolution: {integrity: sha512-vW1GmwMZNnL+gMRaovlh9yZX74kc+TTU3FObkkurpMaRtBfLP3ldjS9KQWlwZgraRE0+dheEEoAxdzcJQ8eXZg==}
|
resolution: {integrity: sha512-j9ednRT81vYJ9OfVuXG6ERSTdEL1xVsNgqpkxMsbIabzSo3goCjDIveeGv5d03om39ML71RdmrGNjG5SReBP/Q==}
|
||||||
|
|
||||||
'@protobufjs/fetch@1.1.1':
|
'@protobufjs/fetch@1.1.0':
|
||||||
resolution: {integrity: sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==}
|
resolution: {integrity: sha512-lljVXpqXebpsijW71PZaCYeIcE5on1w5DlQy5WH6GLbFryLUrBD4932W/E2BSpfRJWseIL4v/KPgBFxDOIdKpQ==}
|
||||||
|
|
||||||
'@protobufjs/float@1.0.2':
|
'@protobufjs/float@1.0.2':
|
||||||
resolution: {integrity: sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==}
|
resolution: {integrity: sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==}
|
||||||
|
|
||||||
|
'@protobufjs/inquire@1.1.0':
|
||||||
|
resolution: {integrity: sha512-kdSefcPdruJiFMVSbn801t4vFK7KB/5gd2fYvrxhuJYg8ILrmn9SKSX2tZdV6V+ksulWqS7aXjBcRXl3wHoD9Q==}
|
||||||
|
|
||||||
'@protobufjs/path@1.1.2':
|
'@protobufjs/path@1.1.2':
|
||||||
resolution: {integrity: sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==}
|
resolution: {integrity: sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==}
|
||||||
|
|
||||||
'@protobufjs/pool@1.1.0':
|
'@protobufjs/pool@1.1.0':
|
||||||
resolution: {integrity: sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==}
|
resolution: {integrity: sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==}
|
||||||
|
|
||||||
'@protobufjs/utf8@1.1.2':
|
'@protobufjs/utf8@1.1.0':
|
||||||
resolution: {integrity: sha512-b1UQwcEZ4yCnMCD8DAL1VlbvBJE9/IX4FTIp7BG1xYpf29SLazLSrqUkj4w7Y5y7cCVP6E5tcqqcI0xemPkHug==}
|
resolution: {integrity: sha512-Vvn3zZrhQZkkBE8LSuW3em98c0FwgO4nxzv6OdSxPKJIEKY2bGbHn+mhGIPerzI4twdxaP8/0+06HBpwf345Lw==}
|
||||||
|
|
||||||
'@pwshub/bellajs@13.0.2':
|
'@pwshub/bellajs@13.0.2':
|
||||||
resolution: {integrity: sha512-OWOaE7Ieufo7VMv957iahOzv/w5oXyyXO28Jh2x6rLU96ZLqC508kAKTgdMJRXgVjda2s+/0C6Kno+k16OmJsQ==}
|
resolution: {integrity: sha512-OWOaE7Ieufo7VMv957iahOzv/w5oXyyXO28Jh2x6rLU96ZLqC508kAKTgdMJRXgVjda2s+/0C6Kno+k16OmJsQ==}
|
||||||
@@ -14883,8 +14885,8 @@ packages:
|
|||||||
proto-list@1.2.4:
|
proto-list@1.2.4:
|
||||||
resolution: {integrity: sha512-vtK/94akxsTMhe0/cbfpR+syPuszcuwhqVjJq26CuNDgFGj682oRBXOP5MJpv2r7JtE8MsiepGIqvvOTBwn2vA==}
|
resolution: {integrity: sha512-vtK/94akxsTMhe0/cbfpR+syPuszcuwhqVjJq26CuNDgFGj682oRBXOP5MJpv2r7JtE8MsiepGIqvvOTBwn2vA==}
|
||||||
|
|
||||||
protobufjs@7.6.6:
|
protobufjs@7.4.0:
|
||||||
resolution: {integrity: sha512-dYDWdjSl5RNb7SgPxGQcRU+GtvP7s2fpkrY0r432PcOIaZ0/rBcxEZnQN67iJhFuQiVw754JDoPruPCNdGsbjg==}
|
resolution: {integrity: sha512-mRUWCc3KUU4w1jU8sGxICXH/gNS94DvI1gxqDvBzhj1JpcsimQkYiOJfwsPUykUI5ZaspFbSgmBLER8IrQ3tqw==}
|
||||||
engines: {node: '>=12.0.0'}
|
engines: {node: '>=12.0.0'}
|
||||||
|
|
||||||
proxmox-api@1.1.1:
|
proxmox-api@1.1.1:
|
||||||
@@ -20814,7 +20816,7 @@ snapshots:
|
|||||||
dependencies:
|
dependencies:
|
||||||
lodash.camelcase: 4.3.0
|
lodash.camelcase: 4.3.0
|
||||||
long: 5.3.2
|
long: 5.3.2
|
||||||
protobufjs: 7.6.6
|
protobufjs: 7.4.0
|
||||||
yargs: 17.7.2
|
yargs: 17.7.2
|
||||||
|
|
||||||
'@hapi/bourne@3.0.0': {}
|
'@hapi/bourne@3.0.0': {}
|
||||||
@@ -22509,21 +22511,24 @@ snapshots:
|
|||||||
|
|
||||||
'@protobufjs/base64@1.1.2': {}
|
'@protobufjs/base64@1.1.2': {}
|
||||||
|
|
||||||
'@protobufjs/codegen@2.0.5': {}
|
'@protobufjs/codegen@2.0.4': {}
|
||||||
|
|
||||||
'@protobufjs/eventemitter@1.1.1': {}
|
'@protobufjs/eventemitter@1.1.0': {}
|
||||||
|
|
||||||
'@protobufjs/fetch@1.1.1':
|
'@protobufjs/fetch@1.1.0':
|
||||||
dependencies:
|
dependencies:
|
||||||
'@protobufjs/aspromise': 1.1.2
|
'@protobufjs/aspromise': 1.1.2
|
||||||
|
'@protobufjs/inquire': 1.1.0
|
||||||
|
|
||||||
'@protobufjs/float@1.0.2': {}
|
'@protobufjs/float@1.0.2': {}
|
||||||
|
|
||||||
|
'@protobufjs/inquire@1.1.0': {}
|
||||||
|
|
||||||
'@protobufjs/path@1.1.2': {}
|
'@protobufjs/path@1.1.2': {}
|
||||||
|
|
||||||
'@protobufjs/pool@1.1.0': {}
|
'@protobufjs/pool@1.1.0': {}
|
||||||
|
|
||||||
'@protobufjs/utf8@1.1.2': {}
|
'@protobufjs/utf8@1.1.0': {}
|
||||||
|
|
||||||
'@pwshub/bellajs@13.0.2': {}
|
'@pwshub/bellajs@13.0.2': {}
|
||||||
|
|
||||||
@@ -27178,7 +27183,7 @@ snapshots:
|
|||||||
'@grpc/grpc-js': 1.12.5
|
'@grpc/grpc-js': 1.12.5
|
||||||
'@grpc/proto-loader': 0.7.13
|
'@grpc/proto-loader': 0.7.13
|
||||||
docker-modem: 5.0.7(supports-color@10.2.2)
|
docker-modem: 5.0.7(supports-color@10.2.2)
|
||||||
protobufjs: 7.6.6
|
protobufjs: 7.4.0
|
||||||
tar-fs: 2.1.4
|
tar-fs: 2.1.4
|
||||||
transitivePeerDependencies:
|
transitivePeerDependencies:
|
||||||
- supports-color
|
- supports-color
|
||||||
@@ -27189,7 +27194,7 @@ snapshots:
|
|||||||
'@grpc/grpc-js': 1.12.5
|
'@grpc/grpc-js': 1.12.5
|
||||||
'@grpc/proto-loader': 0.7.13
|
'@grpc/proto-loader': 0.7.13
|
||||||
docker-modem: 5.0.7(supports-color@10.2.2)
|
docker-modem: 5.0.7(supports-color@10.2.2)
|
||||||
protobufjs: 7.6.6
|
protobufjs: 7.4.0
|
||||||
tar-fs: 2.1.4
|
tar-fs: 2.1.4
|
||||||
transitivePeerDependencies:
|
transitivePeerDependencies:
|
||||||
- supports-color
|
- supports-color
|
||||||
@@ -31426,17 +31431,18 @@ snapshots:
|
|||||||
|
|
||||||
proto-list@1.2.4: {}
|
proto-list@1.2.4: {}
|
||||||
|
|
||||||
protobufjs@7.6.6:
|
protobufjs@7.4.0:
|
||||||
dependencies:
|
dependencies:
|
||||||
'@protobufjs/aspromise': 1.1.2
|
'@protobufjs/aspromise': 1.1.2
|
||||||
'@protobufjs/base64': 1.1.2
|
'@protobufjs/base64': 1.1.2
|
||||||
'@protobufjs/codegen': 2.0.5
|
'@protobufjs/codegen': 2.0.4
|
||||||
'@protobufjs/eventemitter': 1.1.1
|
'@protobufjs/eventemitter': 1.1.0
|
||||||
'@protobufjs/fetch': 1.1.1
|
'@protobufjs/fetch': 1.1.0
|
||||||
'@protobufjs/float': 1.0.2
|
'@protobufjs/float': 1.0.2
|
||||||
|
'@protobufjs/inquire': 1.1.0
|
||||||
'@protobufjs/path': 1.1.2
|
'@protobufjs/path': 1.1.2
|
||||||
'@protobufjs/pool': 1.1.0
|
'@protobufjs/pool': 1.1.0
|
||||||
'@protobufjs/utf8': 1.1.2
|
'@protobufjs/utf8': 1.1.0
|
||||||
'@types/node': 24.13.3
|
'@types/node': 24.13.3
|
||||||
long: 5.3.2
|
long: 5.3.2
|
||||||
|
|
||||||
|
|||||||
@@ -260,7 +260,6 @@ overrides:
|
|||||||
"linkifyjs@<4.3.2": ">=4.3.3"
|
"linkifyjs@<4.3.2": ">=4.3.3"
|
||||||
"nanoid@>=4.0.0 <5.0.9": ">=5.1.16"
|
"nanoid@>=4.0.0 <5.0.9": ">=5.1.16"
|
||||||
"prismjs@<1.30.0": ">=1.30.0"
|
"prismjs@<1.30.0": ">=1.30.0"
|
||||||
"protobufjs@<7.5.5": ">=7.5.5 <8"
|
|
||||||
"proxmox-api>undici": "7.28.0"
|
"proxmox-api>undici": "7.28.0"
|
||||||
"react-is": "^19.2.7"
|
"react-is": "^19.2.7"
|
||||||
"rollup@>=4.0.0 <4.22.4": ">=4.62.2"
|
"rollup@>=4.0.0 <4.22.4": ">=4.62.2"
|
||||||
|
|||||||
Reference in new issue
Block a user