fix: tighten v2 setup and release safeguards (#6824)
This commit is contained in:
Thomas authored and 
GitHub committed
1 parent
e21a0bb6da
commit
2049c6ade0
11 files changed
+74
-128
No files matched your search
@@ -90,7 +90,7 @@ homarr run dev
|
||||
homarr run --detach dev
|
||||
homarr run --pr 6441
|
||||
homarr run --pr 6441 --demo
|
||||
homarr --pr 6441 --env WORKSHOP_WEB_URL=https://app-v2.preview.homarr.dev/
|
||||
homarr --pr 6441 --env WORKSHOP_WEB_URL=https://workshop.example.com/workshop
|
||||
```
|
||||
|
||||
- `--pr <number>`: Pull and run a PR image from GHCR (shorthand: `homarr --pr <number>`).
|
||||
|
||||
@@ -31,9 +31,13 @@ pnpm install --frozen-lockfile
|
||||
### Run the Homarr application
|
||||
|
||||
1. Copy `.env.example` to `.env`.
|
||||
2. Set `DB_URL` to an absolute writable SQLite file path.
|
||||
3. Keep Redis and the optional local databases running in one terminal.
|
||||
4. Apply migrations and start Next.js in another terminal.
|
||||
2. Run `openssl rand -hex 32` twice. Set `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` to the two different generated
|
||||
values in `.env`; the example leaves both empty. Keep this file private and preserve `SECRET_ENCRYPTION_KEY`
|
||||
when reusing a database.
|
||||
3. Set `DB_URL` to an absolute writable SQLite file path. Migration and application commands run from different
|
||||
workspace directories, so a relative path can point them at different databases.
|
||||
4. Keep Redis and the optional local databases running in one terminal.
|
||||
5. Apply migrations and start Next.js in another terminal.
|
||||
|
||||
```sh
|
||||
cp .env.example .env
|
||||
@@ -57,6 +61,20 @@ Homarr becomes the instance administrator.
|
||||
Use `pnpm docker:dev:up` instead when you only need Redis in the background. Running the migration also seeds the
|
||||
default data; use `pnpm db:seed` to seed it explicitly later.
|
||||
|
||||
`pnpm dev` starts only Next.js. When your work needs scheduled tasks or live subscriptions, run the relevant service
|
||||
in a separate terminal alongside it:
|
||||
|
||||
```sh
|
||||
pnpm --filter @homarr/tasks dev
|
||||
```
|
||||
|
||||
```sh
|
||||
pnpm --filter @homarr/websocket dev
|
||||
```
|
||||
|
||||
The WebSocket service listens on port 3001. Production startup embeds both services, so these extra commands are
|
||||
only needed for development.
|
||||
|
||||
Workshop contributors can set up PocketBase and Docusaurus with the dedicated
|
||||
[Workshop development guide](./workshop).
|
||||
|
||||
@@ -80,8 +98,8 @@ Workshop contributors can set up PocketBase and Docusaurus with the dedicated
|
||||
- `pnpm typecheck` — typecheck all workspaces.
|
||||
- `pnpm test` — unit and contract suites.
|
||||
- `pnpm build` — production monorepo build.
|
||||
- `docker build -t homarr .` — build a production Docker image.
|
||||
- `docker run -p 7575:7575 -e SECRET_ENCRYPTION_KEY='your_64_character_hex_string' homarr:<name>` — run it.
|
||||
- `docker build -t homarr:local .` — build a production Docker image.
|
||||
- `docker run -p 7575:7575 -e SECRET_ENCRYPTION_KEY='your_64_character_hex_string' homarr:local` — run it.
|
||||
|
||||
## CI and focused validation
|
||||
|
||||
|
||||
@@ -24,6 +24,10 @@ see [Managing integrations](/docs/management/integrations#configuration).
|
||||
|
||||
### Update
|
||||
|
||||
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.
|
||||
|
||||
```sh
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
|
||||
@@ -21,8 +21,8 @@ This method is only useful, when you want to develop on Homarr or extend it with
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Node.js](https://nodejs.org/en/download/)
|
||||
- [pnpm](https://pnpm.io/installation)
|
||||
- [Node.js](https://nodejs.org/en/download/) 24.18 or newer
|
||||
- [pnpm](https://pnpm.io/installation) at the version pinned in the repository's `package.json`
|
||||
- [Redis](https://redis.io/download)
|
||||
|
||||
## Steps
|
||||
@@ -38,9 +38,9 @@ This method is only useful, when you want to develop on Homarr or extend it with
|
||||
Install all dependencies using <code>pnpm install</code>
|
||||
</li>
|
||||
<li>
|
||||
Copy the `.env.example` file to `.env`. Its `DB_URL='./db.sqlite'` value is ready for local use and stores the
|
||||
database in the cloned repository. Replace it with an absolute writable path such as
|
||||
`DB_URL='/home/username/homarr/db.sqlite'` if you want to store the database elsewhere.
|
||||
Copy `.env.example` to `.env` and set `DB_URL` to an absolute writable path, such as
|
||||
`DB_URL='/home/username/homarr/db.sqlite'`. Migration and application commands run from different workspace
|
||||
directories, so a relative path can point them at different databases.
|
||||
</li>
|
||||
<li>
|
||||
Run `openssl rand -hex 32` twice and set `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` to the two different generated
|
||||
|
||||
@@ -1,88 +0,0 @@
|
||||
---
|
||||
title: Try the v2 beta
|
||||
sidebar_position: 2
|
||||
tags:
|
||||
- Getting started
|
||||
- Upgrade
|
||||
- Migration
|
||||
- Backup
|
||||
---
|
||||
|
||||
This page covers the temporary Homarr v2 public beta. Try the [live demo](https://app-v2.preview.homarr.dev/)
|
||||
without installing anything, or run the beta image published in the
|
||||
[public beta announcement](https://github.com/homarr-labs/homarr/issues/6600):
|
||||
|
||||
```sh
|
||||
docker pull ghcr.io/homarr-labs/homarr-test:v2
|
||||
```
|
||||
|
||||
For a fresh beta installation, follow the [Docker installation guide](/docs/getting-started/installation/docker),
|
||||
use `ghcr.io/homarr-labs/homarr-test:v2` as the image, and use a separate `/appdata` volume.
|
||||
Set `WORKSHOP_API_URL=https://v2.preview.homarr.dev` to use the preview Workshop.
|
||||
|
||||
Homarr runs database migrations automatically at startup; no manual database migration command is needed.
|
||||
Once v2 is released, existing installations can use their normal update process. The beta image below is temporary.
|
||||
|
||||
:::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.
|
||||
|
||||
:::
|
||||
|
||||
## Try the beta with existing v1 data
|
||||
|
||||
1. Change the Homarr image to `ghcr.io/homarr-labs/homarr-test:v2`.
|
||||
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. Keep using the beta image for beta updates. To return to v1, restore the pre-beta backup as described below.
|
||||
|
||||
Keep your other existing Compose settings, including environment variables. For Docker Compose, update the image and preview Workshop URL before the usual update:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
homarr:
|
||||
image: ghcr.io/homarr-labs/homarr-test:v2
|
||||
environment:
|
||||
WORKSHOP_API_URL: https://v2.preview.homarr.dev
|
||||
```
|
||||
|
||||
```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.
|
||||
@@ -57,5 +57,5 @@ Legacy definitions show **Migration required**. The migration prompt excludes cr
|
||||
describe the visible behavior separately, import the returned v2 definition, and verify it before removing the archived
|
||||
version.
|
||||
|
||||
Back up the database and `SECRET_ENCRYPTION_KEY` before upgrading or rolling back. Multi-replica installations must use
|
||||
the same Redis service so cached responses invalidate consistently.
|
||||
Keep `SECRET_ENCRYPTION_KEY` unchanged when updating Homarr so existing credentials remain readable. Multi-replica
|
||||
installations must use the same Redis service so cached responses invalidate consistently.
|
||||
@@ -18,8 +18,9 @@ password. Decimal units are the default. Change them from the user form or **Com
|
||||
Preferences → Data size units**. Byte rates follow the same preference; bit rates stay decimal and use labels such as
|
||||
Mb/s. Deleting a user does not delete boards they created.
|
||||
|
||||
In demo mode (`DEMO_MODE=true`), user deletion and password changes are disabled for everyone, including administrators,
|
||||
even when `DEMO_READ_ONLY=false` allows other changes. This applies to the UI and API.
|
||||
In demo mode (`DEMO_MODE=true`), user deletion, password changes, and local username changes are disabled for everyone,
|
||||
including administrators, even when `DEMO_READ_ONLY=false` allows other changes. With demo editing enabled, other
|
||||
profile preferences remain editable. This applies to the UI and API.
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in new issue
Block a user