diff --git a/apps/docs/blog/2026/09-03-homarr-2.0/index.mdx b/apps/docs/blog/2026/09-03-homarr-2.0/index.mdx index 6b376c7ee..ece68059e 100644 --- a/apps/docs/blog/2026/09-03-homarr-2.0/index.mdx +++ b/apps/docs/blog/2026/09-03-homarr-2.0/index.mdx @@ -43,7 +43,7 @@ Homarr 2.0 builds on the dashboard you already use. Here is what changed. {/* Historical excerpt boundary. */} -SQLite and PostgreSQL users can update their Homarr image as usual; database migrations run automatically at startup. **MySQL users must convert before upgrading**, as explained below. Workshop uses the production service by default, with no preview URL configuration required. +**Back up before upgrading:** database migrations run automatically at startup and change the existing database in place. Follow the [upgrade and rollback guidance](/docs/getting-started/installation/docker#update), including the note on board sizing. **MySQL users must convert before upgrading**, as explained below. Workshop uses the production service by default, with no preview URL configuration required. ## Database support in v2 diff --git a/apps/docs/docs/getting-started/installation/docker.mdx b/apps/docs/docs/getting-started/installation/docker.mdx index d9371261b..dd4898b4c 100644 --- a/apps/docs/docs/getting-started/installation/docker.mdx +++ b/apps/docs/docs/getting-started/installation/docker.mdx @@ -24,15 +24,44 @@ see [Managing integrations](/docs/management/integrations#configuration). ### Update + +**Back up before upgrading from v1 to v2.** v2 migrates the existing database in place. For SQLite, this is +`/appdata/db/db.sqlite` by default; v1 cannot use the upgraded database. Switching back to the v1 image alone is not a +rollback. Image-rollback tools that revert only the container image do not restore the database; you still need +the pre-upgrade backup. + +Stop Homarr before copying the complete `/appdata` directory or volume. Keep the pre-upgrade copy, your container +configuration, and `SECRET_ENCRYPTION_KEY` securely. If you use an external PostgreSQL database, back it up with its +native tools as well. See [Backup and restore](/docs/management/backup). + + + Update the image and recreate the container with the same configuration. Homarr runs database migrations automatically at startup, including when moving from v1 to v2; no separate upgrade procedure is needed. Keep the `/appdata` mount and `SECRET_ENCRYPTION_KEY` unchanged. Workshop connects to the production service by default. +Existing MySQL installations must [convert to SQLite before upgrading to v2](/docs/advanced/mysql-to-sqlite). + ```sh docker compose pull docker compose up -d ``` +To roll back, stop v2, restore the **pre-upgrade** database and `/appdata` backup with the matching configuration and +encryption key, then start the previously used v1 image. A backup taken after v2 has migrated the database cannot +restore v1 compatibility. + +#### Board sizing after upgrading to v2 + +v2 uses fixed `200 × 200` logical-pixel cells and scales the whole board to fit the available width. A migrated +12-column layout can therefore show smaller widgets and text than in v1. Reducing the column count in +[board layout settings](/docs/management/boards#responsive-layouts) makes cells appear larger at the same viewport +width; choose a count that fits your content. + +Back up before changing columns: reducing the count can resize Containers and displace widgets. Check the layout in +edit mode before saving. In v2.0.0, increasing the count again may not restore the previous arrangement after widgets +or Containers have been displaced or resized; keep a backup rather than relying on reversing the column change. + ### Uninstall `docker compose down` removes the containers and Compose network. Delete the configured `/appdata` host directory or @@ -53,5 +82,6 @@ docker run \ -d ghcr.io/homarr-labs/homarr:latest ``` -Remove the Docker socket mount when it is not required. To update, pull the current image, recreate the container with -the same arguments, and keep the `/appdata` mount and `SECRET_ENCRYPTION_KEY` unchanged. +Remove the Docker socket mount when it is not required. To update, follow the [backup guidance above](#update), pull +the current image, recreate the container with the same arguments, and keep the `/appdata` mount and +`SECRET_ENCRYPTION_KEY` unchanged. diff --git a/apps/docs/docs/management/boards/index.mdx b/apps/docs/docs/management/boards/index.mdx index 10fd76c4a..effa13748 100644 --- a/apps/docs/docs/management/boards/index.mdx +++ b/apps/docs/docs/management/boards/index.mdx @@ -38,8 +38,8 @@ Mobile and Base are protected layouts. New boards use three Mobile columns; Base creation. Additional layouts use unique breakpoints. Homarr selects the layout with the highest breakpoint that fits the current viewport. -Tiles use fixed `200 × 200` logical-pixel cells with a `24px` gap. Homarr scales the complete layout to the available -width instead of changing each widget's proportions. **Reset from Base** regenerates a Mobile or custom layout from the +The logical grid uses fixed `200 × 200` cells with a `12px` gap. Visible tile spacing also depends on card insets and +canvas scaling. Homarr scales the complete layout to the available width instead of changing each widget's proportions. **Reset from Base** regenerates a Mobile or custom layout from the current Base layout. Changing column or sidebar counts keeps a saved source arrangement while its generated positions remain unedited.