docs: add Beszel, SQLite backup, and Custom widgets documentation (#5930)

This commit is contained in:
Thomas authored and GitHub committed 2026-06-12 13:56:53 +02:00
1 parent d16571d4c4
commit 7567842c4c
23 files changed
+726 -8

No files matched your search

@@ -0,0 +1,100 @@
---
title: Custom Widgets
tags:
- Management
- Widgets
- Custom
- API
---
Custom widgets let you create your own dashboard widgets that fetch data from any external API and render it with configurable displays. They are managed from the **Management → Custom Widgets** page (admin only).
:::note Beta
Custom widgets are currently in beta. Share feedback and report issues in the [GitHub discussion](https://github.com/homarr-labs/homarr/discussions/5916).
:::
## Overview
Custom widgets connect to any HTTP API endpoint and display the response data using one of several built-in display types. You can create multiple widget definitions, each with its own API configuration, display settings, and optional secrets for authentication.
## Creating a Custom Widget
Navigate to **Management → Custom Widgets** and click **New Custom Widget**. You'll need to configure:
### API Configuration
- **URL** — The full URL of the API endpoint to fetch
- **Method** — HTTP method (`GET`, `POST`, etc.)
- **Headers** — Custom HTTP headers (e.g. `Authorization`, `Content-Type`)
- **Body** — Request body for POST/PUT methods
- **Auth type** — Authentication method (`none`, `bearer`, `basic`, `API key in header`, `API key in query`)
### Secrets
Custom widgets support encrypted secret storage for API keys and passwords. Secrets are stored using AES-256-CBC encryption (same as integration secrets) and are **excluded from exports** for security.
### Display Configuration
Choose from the following display types:
| Display Type | Description |
|---|---|
| **Single Value** | Shows a single extracted value prominently |
| **Key-Value** | Displays data as labeled key-value pairs |
| **Table** | Renders data in a table layout |
| **Stat Grid** | Shows multiple statistics in a grid |
| **Progress Bars** | Visualizes values as progress bars |
| **Status Indicator** | Shows status with colored indicators |
| **Count Grid** | Displays count values in a grid layout |
| **Raw** | Shows the raw API response |
| **Action Button** | A button that triggers an API call when clicked |
| **Custom JSX** | Write custom JSX templates using whitelisted Mantine components |
:::tip Refresh interval
When adding a Custom API widget to a board, you can configure its **refresh interval** (1–3600 seconds, default 30s) in the widget's board options.
:::
## Custom JSX Display
The Custom JSX display type lets you write JSX templates to create rich, interactive displays. For security, only whitelisted components are allowed:
- **Mantine components** — `Text`, `Badge`, `Group`, `Stack`, `Paper`, `Progress`, `RingProgress`, `ThemeIcon`, `Anchor`, `Image`, `Divider`, `Code`, `Table`, and more
- **Interactive components** — `PaginatedList`, `TabsContainer`, `Collapsible`, `StatBar`, `TypeBadge`
Templates have access to the API response data and can use JSONPath expressions to extract values.
:::warning Security
The JSX sandbox blocks dangerous patterns like `eval`, `Function`, `__proto__`, and `javascript:` URLs. However, only admins can create custom widgets.
:::
## Live Preview
The widget editor includes a live preview panel that shows how the widget will look with real API data. Use the **Debug** panel to inspect the raw API response and test JSONPath expressions.
## Copy AI Prompt
Click the **Copy AI Prompt** button to copy a prompt containing the API's JSON Schema and sample response. Paste this into an LLM to get help writing JSONPath expressions or Custom JSX templates.
## Import & Export
Custom widget definitions can be exported as JSON files and imported on other Homarr instances:
- **Export** — Downloads a JSON file with the widget definition (secrets are excluded)
- **Import** — Upload a previously exported JSON file to create a new widget definition
- The export format uses `$schema: "homarr-custom-widget-v2"`
## Using Custom Widgets on a Board
Once created, custom widgets appear in the widget picker when editing a board. Each custom widget definition can be added to any board like a built-in widget.
## Seed Fixtures
Homarr ships with example custom widget definitions (disabled by default) to help you get started:
- **Currency Exchange (JPY)** — Live exchange rates
- **Random Dog Fact** — Random dog facts
- **Jellyfin library** — Jellyfin server statistics
Enable them from the custom widgets management page or use them as templates for your own widgets.
Additional examples like the Pokédex are available as importable JSON files in the repository under `packages/db/seed/custom-widgets/`.
@@ -0,0 +1,5 @@
{
"label": "Tools",
"collapsed": true,
"position": 10
}
@@ -0,0 +1,66 @@
---
title: SQLite Backup & Restore
tags:
- Management
- Backup
- Restore
- SQLite
---
The SQLite Backup & Restore feature allows you to export and import your entire Homarr database as a portable ZIP file. This is useful for creating backups, migrating between instances, or recovering from failures.
:::info SQLite only
This feature is only available when using the SQLite database driver (`DB_DRIVER=better-sqlite3`). MySQL and PostgreSQL users should use their respective database backup tools.
:::
## Accessing Backup & Restore
Navigate to **Management → Tools → Backup** from the sidebar. This page is only visible when running with SQLite.
## Exporting a Backup
Click the **Export** button to download a ZIP archive containing:
- **`db.sqlite`** — A consistent snapshot of your database (created via `VACUUM INTO`)
- **`metadata.json`** — Contains:
- `homarrVersion` — The version of Homarr that created the backup
- `exportedAt` — Timestamp of the export
- `dbDialect` — The database dialect (`sqlite`)
- `encryptionKey` — Your `SECRET_ENCRYPTION_KEY` (needed to decrypt integration secrets)
:::caution
The exported ZIP contains your encryption key and database. Store it securely and do not share it publicly.
:::
A confirmation dialog will ask you to type **"I understand"** before the export proceeds.
## Importing a Backup
1. Click the **Import** button and upload a previously exported ZIP file
2. Homarr analyzes the backup **entirely in your browser** using WebAssembly (sql.js) — no data is sent to the server during preview
3. The preview shows:
- **Entity counts** — How many boards, apps, users, integrations, etc. are in the backup
- **Board names** — A list of all boards contained in the backup
- **Migration status** — If the backup is from an older version, Homarr shows each pending database migration as animated timeline steps
4. Review the preview and type **"I understand"** to confirm
5. Homarr applies any pending migrations, re-encrypts integration secrets if the `SECRET_ENCRYPTION_KEY` differs between instances, and replaces the live database
6. The server automatically restarts to pick up the new database
:::tip
The import process is **backward-compatible** with older backups that used a separate `encryption-key.txt` file instead of embedding the key in `metadata.json`.
:::
## Onboarding Integration
When setting up a fresh Homarr instance with SQLite, the onboarding wizard includes a **"Restore from SQLite backup"** option. This lets you upload a backup ZIP to bootstrap your new instance with data from a previous installation.
## Docker Restart Behavior
After a successful import, only the Next.js process restarts — nginx and Redis remain running. The `run.sh` script automatically restarts Next.js in a loop, so the application comes back online within seconds. Running `docker stop` still works gracefully.
## Best Practices
- **Back up regularly** — Create exports before major updates or configuration changes
- **Test restores** — Periodically verify your backups by importing them on a test instance
- **Secure storage** — Keep backups in an encrypted or access-controlled location since they contain your encryption key
- **Check versions** — Backups from newer versions cannot be imported into older Homarr instances; always import into the same or newer version