docs: streamline release v2 documentation (#6760)
This commit is contained in:
Thomas authored and 
GitHub committed
1 parent
ac62e5bfd6
commit
b3aa6155cc
163 files changed
+2908
-4208
No files matched your search
@@ -6,397 +6,76 @@ tags:
|
||||
- Configuration
|
||||
---
|
||||
|
||||
import manageBoardNoApp from "./img/manage-board-no-app.png";
|
||||
import currentKeyboardTileEditing from "../management/boards/img/keyboard-tile-editing.png";
|
||||
import boardDesktopCurrent from "./img/onboarding-board-desktop-current.png";
|
||||
import boardEditModeCurrent from "./img/onboarding-board-edit-mode-current.png";
|
||||
import addContentMenuCurrent from "./img/onboarding-add-content-menu-current.png";
|
||||
import chooseItemCurrent from "./img/onboarding-choose-item-current.png";
|
||||
import editItemCurrent from "./img/onboarding-edit-item-current.png";
|
||||
import boardsHomeMobileMenu from "./img/onboarding-boards-home-mobile-menu.png";
|
||||
import moveResizeMenuCurrent from "./img/onboarding-move-resize-menu-current.png";
|
||||
import currentBoardMobileView from "./img/onboarding-board-mobile-current.png";
|
||||
On first launch, onboarding creates the administrator, connects optional services, and builds the first board. A
|
||||
compatible SQLite backup can also be restored from the welcome screen.
|
||||
|
||||
:::tip
|
||||
If onboarding returns after a restart, check that `/appdata` is writable and persisted. See the
|
||||
[Docker installation guide](/docs/getting-started/installation/docker).
|
||||
|
||||
Read our [glossary](/docs/getting-started/glossary) if you are new to Homarr.
|
||||
## Core concepts
|
||||
|
||||
:::
|
||||
### Boards
|
||||
|
||||
Congratulations on installing Homarr. Now it's time to get yourself familiar with the concepts of Homarr and how to use it.
|
||||
A **board** is a dashboard page containing apps, widgets, and Containers. Boards can be public or restricted to users
|
||||
and groups. Each user can choose a home board.
|
||||
|
||||
## Onboarding
|
||||
|
||||
|
||||
Onboarding appears the first time Homarr starts. Its goal is to create a useful responsive board, not merely an
|
||||
administrator account. The setup uses one guided studio, so you can keep the safe defaults and finish quickly or review
|
||||
every detected service before anything is added to the board.
|
||||
See [Boards](/docs/management/boards) for responsive layouts, access control, appearance, and home-board settings.
|
||||
|
||||
:::note
|
||||
### Apps
|
||||
|
||||
If you see this screen repeatedly after restarting the Homarr container, your Docker mounting paths may be missing,
|
||||
incorrect or read-only. Read [our installation instructions](/docs/getting-started/installation/docker) again to fix this issue.
|
||||
An **app** is a saved shortcut: a name, URL, icon, and optional status check. Add an App tile or a Bookmarks widget to
|
||||
show apps on a board.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
### Restore or start fresh
|
||||
See [Apps](/docs/management/apps) or [Icons](/docs/advanced/icons).
|
||||
|
||||
SQLite installations can restore a complete Homarr database backup from the welcome screen. This restores current
|
||||
boards, people, apps, integrations, and settings. The pre-1.0 ZIP importer is no longer included.
|
||||
### Integrations
|
||||
|
||||
For a new installation, Homarr first creates either a credentials administrator or an administrator group matching your
|
||||
LDAP/OIDC provider. The browser that starts setup claims the first-run session; refreshes are safe, while another browser
|
||||
cannot change credentials or integrations during that setup.
|
||||
An **integration** is a server-side connection from Homarr to a supported service such as Sonarr, Home Assistant, or
|
||||
Docker. Integrations provide data and actions to widgets. They can also be linked to apps.
|
||||
|
||||
### Setup studio
|
||||
|
||||
|
||||
The studio keeps related choices together:
|
||||
See [Managing integrations](/docs/management/integrations) and the
|
||||
[integration catalog](/docs/category/integrations).
|
||||
|
||||
1. **Essentials** sets the default language, color scheme, analytics preference, and the usual host, IP address, domain, or reverse-proxy path used by your services. URL suggestions can use separate ports, subdomains, or one path per service.
|
||||
2. **Discover** checks the actual database, Docker-compatible sockets, Kubernetes configuration, Workshop, and Assistant capabilities. Unavailable sources never block manual setup.
|
||||
3. **Connect** shows detected integrations and apps first, identifying whether each app came from an explicit [`homarr.*` or Homepage Docker label](/docs/integrations/docker-labels) or image matching. Select several integrations and apps at once, review every URL, and use the service-specific link to open its API-key settings when one is available. If a container has no published port or URL label, add its HTTP or HTTPS address before importing it.
|
||||
4. **Board** previews the Base layout, colors, widget radius, sidebars, selected apps, and widgets inferred from integrations or Docker labels. Choose 8 columns for a focused board, 10 for a balanced board, 12 for a wide board, or use the slider for a custom width up to 24 columns. Homarr still creates and reflows the protected Mobile layout automatically. A fast setup adds the integration-free Clock, Weather, and Bookmarks starter widgets.
|
||||
5. **Extend** explains and optionally configures Assistant, the community Workshop, and the separate Homarr MCP endpoint.
|
||||
6. **Review** tests the selected connections, then saves integrations, apps, widgets, settings, and the exact first board together. If any part fails, the database changes are rolled back and your form stays available to correct.
|
||||
### Widgets
|
||||
|
||||
Docker discovery reports each configured host separately. Results from reachable hosts remain selectable if another socket
|
||||
is unavailable, which is useful for remote Docker, rootless Docker, Synology, and mixed deployments. On Kubernetes or
|
||||
bare-metal installations without a Docker socket, enter services manually and use the same integration catalog.
|
||||
A **widget** is a board tile. Some widgets work on their own; others require one or more integrations. Configuration,
|
||||
supported integrations, and non-obvious limitations are documented on each widget page.
|
||||
|
||||
After setup, **Open my board** takes you directly to the configured board. The in-product tour then introduces edit mode,
|
||||
responsive layouts, widgets, and search without delaying completion.
|
||||
|
||||
|
||||
## Creating another board
|
||||
See the [widget catalog](/docs/category/widgets).
|
||||
|
||||
In Homarr, you organize your apps and widgets on boards.
|
||||
Boards use fixed-size tiles so the same widget keeps the same proportions on every screen.
|
||||
Drag, resize, and section controls are available in edit mode.
|
||||
Onboarding already created the first board. To create another one, navigate to `Manage` > `Boards` > `New board`:
|
||||
|
||||
### Containers and rails
|
||||
|
||||
A board must always have a name and can either be public or private.
|
||||
Public boards are also accessible for users, that are not logged in ([see access control for boards](/docs/management/boards/#access-control)).
|
||||
A **Container** groups board items and can be nested. A **rail** reserves a fixed area at the left or right of a
|
||||
responsive layout. Both are configured in board edit mode.
|
||||
|
||||
|
||||
|
||||
|
||||
Congratulations - you've just created another board. You can see the boards you have access to on this page:
|
||||
See [Boards](/docs/management/boards#containers-and-rails).
|
||||
|
||||
<figure>
|
||||
<img
|
||||
src={boardsHomeMobileMenu}
|
||||
alt="Boards management page showing a Home badge and separate desktop and mobile home-board menu entries"
|
||||
style={{ maxWidth: "100%" }}
|
||||
/>
|
||||
<figcaption>The Boards page selects the board opened from Home separately for desktop and mobile.</figcaption>
|
||||
</figure>
|
||||
### Users, groups, and permissions
|
||||
|
||||
The board marked **Home** is the board opened from the desktop Home route. **Set as your mobile board** selects which board
|
||||
opens on phones. This is separate from the **Mobile** layout: the home-board setting chooses a board, while **Mobile** and
|
||||
**Base** are responsive layouts inside that board. A phone can therefore open a different home board and still use that
|
||||
board's Mobile layout.
|
||||
Users inherit permissions and default boards from their groups. Resource-specific access can further restrict boards
|
||||
and integrations.
|
||||
|
||||
New boards start with **Mobile** and **Base** responsive layouts automatically, so you can edit the board for phones and
|
||||
desktops without creating extra layouts first. Mobile starts at `0px` with 3 columns and Base at `768px` with 10 columns.
|
||||
Each layout keeps its own tile positions and sizes.
|
||||
|
||||
|
||||
## Add your first app to Homarr
|
||||
See [Users and groups](/docs/management/users) and [single sign-on](/docs/advanced/single-sign-on).
|
||||
|
||||
To add links to your dashboard, you must first add them as an "app".
|
||||
Navigate to this page to add an app:
|
||||
## Explore further
|
||||
|
||||
|
||||
- [Server settings](/docs/management/settings)
|
||||
- [Assistant](/docs/management/assistant)
|
||||
- [Custom Widgets](/docs/management/custom-widgets)
|
||||
- [Community Workshop](/docs/workshop)
|
||||
- [API](/docs/management/api) and [MCP](/docs/management/mcp)
|
||||
- [Keyboard shortcuts](/docs/advanced/keyboard-shortcuts)
|
||||
|
||||
Next, click on the `New app` button. You'll need to provide a name and an icon to create an app.
|
||||
The name must be at least one character long but you can provide any image URL for the icon.
|
||||
Homarr ships with over 11K icons - so you can just search by entering a search text instead.
|
||||
|
||||
|
||||
|
||||
After you created the app, you'll see in on the apps page:
|
||||
|
||||
|
||||
|
||||
## Arrange and organize your board
|
||||
|
||||
Let's add your freshly created app, from the previous step, to the board.
|
||||
To do this, edit your previously created board by clicking on the big `Open board` button:
|
||||
|
||||
<figure>
|
||||
<img src={boardDesktopCurrent} alt="Current Homarr board opened from the Boards page" style={{ maxWidth: "100%" }} />
|
||||
<figcaption>Open a board to view its dashboard, then enter edit mode to arrange its content.</figcaption>
|
||||
</figure>
|
||||
|
||||
Here you have the following options in the header:
|
||||
|
||||
|
||||
|
||||
- **Search**: Here you can search for data. You can search for integrations, boards, actions, sites and much more. Some actions may be context dependent (eg. will only show when certain widgets are on your page)
|
||||
- **Edit board**: Clicking this button will toggle edit mode. In this mode you can edit the contents of your board.
|
||||
- **Settings**: Clicking this button will redirect you to a settings page where you can adjust the board settings (page title, colors, ...).
|
||||
- **Profile**: This avatar will be visible on every page. Its menu includes the board switcher; press `Shift+C` to open
|
||||
it directly. The current board is left out of the results.
|
||||
|
||||
When entering the edit mode, you'll get some additional buttons to work with:
|
||||
|
||||
<figure>
|
||||
<img
|
||||
src={boardEditModeCurrent}
|
||||
alt="Current Homarr board editor with tile controls visible"
|
||||
style={{ maxWidth: "100%" }}
|
||||
/>
|
||||
<figcaption>The current editor keeps the board visible while its editing controls are available.</figcaption>
|
||||
</figure>
|
||||
|
||||
- **Add board content**: Click this button to create a new item, app, integration, or Container.
|
||||
- **Save board**: Click this button to save your changes and leave edit mode. If you leave with unsaved changes, Homarr asks whether to discard them.
|
||||
|
||||
Outside edit mode, right-click a widget for its live status, refresh, settings, quick options, and supported actions.
|
||||
Hold `Shift` while hovering a widget that supports advanced view to expand it in place while the rest of the board
|
||||
stays visible but dimmed. Release `Shift` to close it. Hold `Shift` plus `Ctrl` on Windows/Linux or `Cmd` on macOS to
|
||||
keep its advanced view open until you close it. Widgets without a distinct advanced experience adapt in place.
|
||||
|
||||
To continue, click **New item** in the add-content menu. New content is placed at the first available position on the main
|
||||
canvas; it is not inserted at a clicked empty cell or directly into a rail or Container:
|
||||
|
||||
<figure>
|
||||
<img
|
||||
src={addContentMenuCurrent}
|
||||
alt="Current add board content menu with item, app, integration, and Container actions"
|
||||
style={{ maxWidth: "100%" }}
|
||||
/>
|
||||
<figcaption>The add-content menu provides the four supported ways to place new content on the board.</figcaption>
|
||||
</figure>
|
||||
|
||||
Next, you can choose what item you'd like to add.
|
||||
We will discuss the other options in the following sections - for now choose "App" to continue.
|
||||
|
||||
<figure>
|
||||
<img
|
||||
src={chooseItemCurrent}
|
||||
alt="Current item picker showing the App card and other item types"
|
||||
style={{ maxWidth: "100%" }}
|
||||
/>
|
||||
<figcaption>Choose the App item from the current picker to add an app tile.</figcaption>
|
||||
</figure>
|
||||
|
||||
As soon as you chose the app, the modal will close and you'll get the following item on your board:
|
||||
|
||||
<img src={manageBoardNoApp} alt="Screenshot of the No app element on the board" />
|
||||
|
||||
This is expected, because you haven't told Homarr what app it should show in this item.
|
||||
To configure this, click on the small 3 dots at the top of the item in the edit mode and choose "Edit item" in the menu.
|
||||
|
||||
<figure>
|
||||
<img
|
||||
src={moveResizeMenuCurrent}
|
||||
alt="Current board tile menu showing Edit item and Move or resize item"
|
||||
style={{ maxWidth: "450px" }}
|
||||
/>
|
||||
<figcaption>The tile menu contains the item editor and the separate move-and-resize tools.</figcaption>
|
||||
</figure>
|
||||
|
||||
In the modal you can edit the app that you want to display:
|
||||
|
||||
<figure>
|
||||
<img src={editItemCurrent} alt="Current Edit item modal for an App tile" style={{ maxWidth: "620px" }} />
|
||||
<figcaption>
|
||||
The Edit item workspace previews option changes as you configure the tile. Save changes to apply them to the board.
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
When adding a widget, set its initial grid width and height directly in the preview. These size controls are only shown before the widget is added.
|
||||
|
||||
As soon as you save your changes, the tile on the board will refresh and display your app.
|
||||
Resize from any visible edge or corner handle. For a Container, activate its top-left grip before using its resize handles.
|
||||
Press and hold a handle, move the pointer, and release it when the tile has the size you want.
|
||||
|
||||
To move a tile in edit mode, press and hold its inert content area, move it to the desired position, and release it.
|
||||
Widget content is disabled while editing so its controls do not intercept the drag; use the tile's settings button for edit actions.
|
||||
The tile snaps to the grid. A single compatible collision may swap the two items when both resulting placements fit;
|
||||
otherwise the collision chain reflows neighboring tiles automatically.
|
||||
|
||||
Every `1 × 1` tile has a logical content size of `200 × 200` pixels.
|
||||
Larger tiles use multiples of that fixed unit, with a consistent gap between cells.
|
||||
Homarr scales the complete board uniformly, like zooming a page.
|
||||
The complete canvas always fits the available width without horizontal board scrolling. Below 100%, Homarr preserves the
|
||||
widget's readable typography and control density instead of shrinking each widget independently.
|
||||
It does not squeeze or reflow the content of individual widgets, so a widget keeps the same design and proportions across screen sizes.
|
||||
|
||||
On a narrow screen, Homarr uses the **Mobile layout** for the selected board and stacks the board content vertically while
|
||||
preserving each widget's fixed logical proportions:
|
||||
|
||||
<figure>
|
||||
<img
|
||||
src={currentBoardMobileView}
|
||||
alt="Homarr's Mobile layout in a 390-pixel-wide viewport, with tiles scaled to fit and stacked vertically"
|
||||
style={{ maxWidth: "390px" }}
|
||||
/>
|
||||
<figcaption>
|
||||
At phone width, the selected board uses its Mobile layout and fits the complete canvas to the viewport.
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
:::note
|
||||
|
||||
Viewing a board initially uses the lightweight, non-interactive layout.
|
||||
For users with edit access, Homarr prepares drag-and-drop and resize controls in the background after the board becomes interactive.
|
||||
If you enter edit mode before that finishes, the existing board stays visible until the editor is ready.
|
||||
|
||||
:::
|
||||
|
||||
:::tip
|
||||
|
||||
We recommend you to experiment for a few minutes, before you start building your actual dashboard.
|
||||
This helps you to explore the capabilities of Homarr before you build your board in a suboptimal way.
|
||||
|
||||
:::
|
||||
|
||||
Keyboard users can focus a tile, press Enter or Space, then use arrow keys to move and Shift plus arrow keys to resize
|
||||
within its current canvas, rail, or Container. Press Escape to stop keyboard editing. Touch dragging starts after a short
|
||||
hold of about `200 ms`; resize handles accept direct touch input. During a pointer or touch move or resize, press Escape
|
||||
to cancel and restore the previous layout. For cross-grid moves or precise numeric controls, choose **Move / resize item**
|
||||
from the tile's edit menu.
|
||||
Keyboard commands at a grid boundary or minimum tile size are ignored and announced; they do not move or shrink the tile.
|
||||
|
||||
<img src={currentKeyboardTileEditing} alt="A board tile focused for keyboard editing" style={{ maxWidth: "100%" }} />
|
||||
|
||||
Open **Move / resize item** from the tile menu to move the tile to another section or rail and enter precise numeric
|
||||
coordinates and dimensions. After making changes, click **Save board** to persist them and leave edit mode.
|
||||
|
||||
## Adding your first integration
|
||||
|
||||
Now it's time to integrate some basic data into your board.
|
||||
To do this, we first need to create an integration.
|
||||
An integration is a connection between Homarr and a third party application - usually something that you run and deploy yourself.
|
||||
|
||||
Navigate to `Manage` > `Integrations` (for example via your user menu).
|
||||
As an example, we are going to use the public demo instance of **Dash.** - a popular application to monitor CPU / hardware usage.
|
||||
Choose the **Dash.** integration from the list of available integrations:
|
||||
|
||||
|
||||
|
||||
Next, choose a name (or leave it at default), enter `https://dash.mauz.dev/` as the URL in the form and click on `Test connection and create`.
|
||||
Pressing the save button will perform a test request to the integration, to confirm that the networking setup is working as expected.
|
||||
Sometimes invalid configurations, firewalls and other mistakes can lead to connectivity problems - [follow this guide here](/docs/management/integrations/#troubleshooting-connection) if you experience issues.
|
||||
|
||||
If connection was successful, you will be redirect back to the list of integrations.
|
||||
Now let's embed it to your board (see next section).
|
||||
|
||||
:::note
|
||||
|
||||
Some integrations may require additional configuration, such as a username, password or API tokens.
|
||||
Depending on your networking setup and applications, the connection from Homarr might also get blocked by firewalls,
|
||||
the target application or your router.
|
||||
|
||||
:::
|
||||
|
||||
## Embed integration data using widgets
|
||||
|
||||
Let's add your integration, that you have configured in the section above, as a widget to your board.
|
||||
First, navigate back to your board that you want to add it to.
|
||||
Next, enter edit mode again and add another item to your board:
|
||||
|
||||
<figure>
|
||||
<img
|
||||
src={addContentMenuCurrent}
|
||||
alt="Current add board content menu with item, app, integration, and Container actions"
|
||||
style={{ maxWidth: "100%" }}
|
||||
/>
|
||||
<figcaption>Use the same add-content menu to place an integration widget on the board.</figcaption>
|
||||
</figure>
|
||||
|
||||
Instead of choosing an app, let's choose `System Health Monitoring` this time.
|
||||
Click on "Add to board":
|
||||
|
||||
|
||||
|
||||
Resize the item slightly and then edit it using the three dots menu at the top:
|
||||
|
||||
|
||||
|
||||
Next, choose your newly created Dash. integration in the integrations dropdown:
|
||||
|
||||
|
||||
|
||||
:::note
|
||||
|
||||
Some widgets may support multiple integrations at the same time.
|
||||
If they do not support multiple integrations, you will be unable to select more than one.
|
||||
|
||||
:::
|
||||
|
||||
Confirm your changes by pressing save.
|
||||
Editing a widget will trigger a data update and data will soon appear:
|
||||
|
||||
|
||||
|
||||
As with every change, click **Save board** to persist your board changes and leave edit mode.
|
||||
|
||||
## Organizing items with Containers
|
||||
|
||||
Containers are resizable areas for apps, widgets, and nested Containers.
|
||||
The same Container works on the main canvas, inside a fixed rail, or inside another Container.
|
||||
Each Container can configure:
|
||||
|
||||
- Its label and whether that label is visible.
|
||||
- Allow or disable collapsing.
|
||||
- Show or hide **Open all in new tabs**.
|
||||
- Change its border color and custom CSS classes.
|
||||
|
||||
Open the add-content menu and choose **New container**.
|
||||
In edit mode, move and resize it like any other item, then drag items into or out of it.
|
||||
Nested content stays within the Container's bounds.
|
||||
While resizing, the solid outline follows the pointer continuously and the dashed grid preview shows the size that will be saved on release.
|
||||
|
||||
### Collapsing and opening apps
|
||||
|
||||
Users can collapse an eligible Container like an accordion in view mode without changing its saved expanded size.
|
||||
The full-width header becomes the compact expansion bar, so the half-row state has no empty pill-shaped spacer.
|
||||
Expanding it restores its bounds and makes room for its contents.
|
||||
If **Open all in new tabs** is enabled, the Container menu can open every app link it contains.
|
||||
|
||||
### Fixed rails
|
||||
|
||||
Open the board's **Layout** settings to enable the left or right rail for each responsive layout.
|
||||
Choose one, two, or three columns with the slider and use the preview to check the remaining canvas width.
|
||||
The rail reserves those columns from the dashboard, so Homarr moves canvas items into the next available positions.
|
||||
Rail content stays visible while the page scrolls and remains editable.
|
||||
Each responsive layout keeps its own rail widths, item positions, and item sizes.
|
||||
|
||||
## Guided tours
|
||||
|
||||
After completing the onboarding, Homarr provides interactive guided tours to help you discover key features.
|
||||
|
||||
### Management tour
|
||||
|
||||
When you first visit the management area (`/manage`), Homarr walks you through the main pages: boards, apps, integrations, and users (admin only).
|
||||
Each page highlights the list view and the create action so you know where to find and add things.
|
||||
|
||||
### Board tour
|
||||
|
||||
When you first open a board, a tour highlights the board header elements: search, edit mode, settings, and the user menu.
|
||||
|
||||
### Tour controls
|
||||
|
||||
- Press **Enter** (or click **Next**) to advance through tour steps
|
||||
- Tours auto-start on first visit and do not repeat once completed
|
||||
- Tours are skipped on mobile screens (below `sm` breakpoint)
|
||||
- You can **reset tours** from the user settings page under **Manage > Users > [Your user] > General**
|
||||
|
||||
## Next steps
|
||||
|
||||
You're done with the basic setup 🔥. Now it's time to organize and customize even more.
|
||||
We highly recommend you to experiment with different options, styles and configurations.
|
||||
See these curated pages for your next steps:
|
||||
|
||||
- Create new apps using the [apps management](/docs/management/apps/)
|
||||
- Customize your board or add more boards using the [boards management](/docs/management/boards/)
|
||||
- Integrate software that you use using the [integrations management](/docs/management/integrations/)
|
||||
- Choose from our beautiful and interactive [widgets](/docs/category/widgets)
|
||||
- See [all supported integrations](/docs/category/integrations)
|
||||
- Integrate with Homarr with your own application using [the API](/docs/management/api/)
|
||||
|
||||
:::danger
|
||||
|
||||
The Homarr Team will never ask for your credentials. Do not send people your credentials, as they manage the access to your applications and can cause harm to your device if they are abused.
|
||||
|
||||
:::
|
||||
See the [glossary](/docs/getting-started/glossary) for a compact list of Homarr terms.
|
||||
@@ -2,12 +2,19 @@
|
||||
|
||||
This glossary explains Homarr's main components and the terms used for them.
|
||||
|
||||
| Term | Definition |
|
||||
| ----------- | --------------------------------------------------------------------------------------- |
|
||||
| Apps | A piece of software that you or a third party hosts (for example, Google) |
|
||||
| Integration | A connection to a service outside of Homarr |
|
||||
| Container | A resizable area that can hold apps, widgets, and nested Containers |
|
||||
| Widget | A tile that uses your integrations to display data or enables you to interact with them |
|
||||
| Edit mode | A temporary state where you can drag, resize, edit, or customize your board |
|
||||
| Board | A customizable page where apps, widgets, and Containers are arranged |
|
||||
| Tasks | Workloads that are performed in the background, even if no user is present |
|
||||
| Term | Definition |
|
||||
| --------------- | -------------------------------------------------------------------------------- |
|
||||
| App | A saved shortcut with a name, destination, icon, and optional status check |
|
||||
| Assistant | A conversation interface that can use model responses and Homarr tools |
|
||||
| Board | A dashboard page where apps, widgets, and Containers are arranged |
|
||||
| Container | A resizable board area containing apps, widgets, or nested Containers |
|
||||
| Custom Widget | A validated definition for an API-backed board tile |
|
||||
| Edit mode | The board state used to add, move, resize, configure, or remove content |
|
||||
| Homarr provider | An Assistant provider routed through Workshop with a per-user allowance |
|
||||
| Integration | A server-side connection from Homarr to a supported service |
|
||||
| Layout | An arrangement of board items selected for a viewport width |
|
||||
| Provider | The model API selected for Assistant |
|
||||
| Rail | A fixed area at the left or right of a non-Mobile board layout |
|
||||
| Task | A background workload that runs without an active browser session |
|
||||
| Widget | A board tile that displays information or provides actions |
|
||||
| Workshop | A separate community service for sharing Custom Widget definitions and board CSS |
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 96 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 75 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 100 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 141 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 140 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 527 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 561 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 97 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 132 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 115 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 60 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 34 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 177 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 45 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 33 KiB |
@@ -1,45 +1,31 @@
|
||||
---
|
||||
title: Prerequisites
|
||||
title: Getting started
|
||||
sidebar_position: 1
|
||||
tags:
|
||||
- Getting Started
|
||||
- Installation
|
||||
- Docker
|
||||
- Unraid
|
||||
---
|
||||
|
||||
import Link from "@docusaurus/Link";
|
||||
import { IconArrowRight } from "@tabler/icons-react";
|
||||
import {
|
||||
GettingStartedOverview,
|
||||
InstallationPaths,
|
||||
} from "@site/src/components/pages/getting-started/getting-started-overview";
|
||||
|
||||
Before you try to install Homarr, please review if your device meets the requirements.
|
||||
Installing on an unsupported device may lead to unstable behaviour and no support will be provided.
|
||||
<GettingStartedOverview />
|
||||
|
||||
## Hardware
|
||||
## Requirements
|
||||
|
||||
- At least 500MB RAM
|
||||
- At least 600MB of free disk space for the Docker image. SSD is preferred.
|
||||
- Single or dual core CPU
|
||||
- Stable network connection, Wi-Fi use is not recommended
|
||||
- `linux/amd64` or `linux/arm64`;
|
||||
- 500 MB RAM;
|
||||
- 600 MB free disk space for the container image;
|
||||
- a persistent writable `/appdata` directory.
|
||||
|
||||
## Architecture
|
||||
`linux/arm/v7` is not supported.
|
||||
|
||||
We build Homarr for a bunch of different architectures, including ARM. Please ensure that your device architecture is supported by Homarr. We won't be able to provide support for unusual or outdated architectures.
|
||||
## Choose an installation method
|
||||
|
||||
| Architecture | Supported |
|
||||
| ------------ | ---------------- |
|
||||
| linux/amd64 | ✅ Supported |
|
||||
| linux/arm64 | ✅ Supported |
|
||||
| linux/arm/v7 | ❌ Not supported |
|
||||
<InstallationPaths />
|
||||
|
||||
## Getting started with installation
|
||||
|
||||
<Link
|
||||
data-attr="Go to installation"
|
||||
className={"button button--secondary button--lg rounded-3xl dark:border-zinc-600 dark:bg-zinc-800"}
|
||||
to="/docs/category/installation-1"
|
||||
>
|
||||
<div className={"flex items-center gap-3"}>
|
||||
<span className={"dark:text-gray-200"}>Go to Installation</span>
|
||||
<IconArrowRight className={"dark:text-gray-200"} size={20} />
|
||||
</div>
|
||||
</Link>
|
||||
After Homarr starts, open it in a browser and complete onboarding. Then continue with
|
||||
[After the installation](/docs/getting-started/after-the-installation) for the core concepts and the most useful next
|
||||
links.
|
||||
@@ -2,106 +2,52 @@ import { DockerInstallSnippet } from "@site/src/components/pages/installation/do
|
||||
|
||||
# Docker
|
||||
|
||||
Docker is our recommended installation method for beginners and professionals.
|
||||
It is easy to use, ships with all dependencies inside a single container and is easy to use and maintain.
|
||||
It requires at least some basic knowledge of [Docker](https://www.docker.com/).
|
||||
We recommend [NetworkChuck's Docker Containers 101](https://www.youtube.com/watch?v=eGz9DS-aIeY) as a good start for complete beginners.
|
||||
Docker Compose is the recommended installation method. Install
|
||||
[Docker Engine](https://docs.docker.com/engine/install/) and the
|
||||
[Compose plugin](https://docs.docker.com/compose/install/).
|
||||
|
||||
## Docker compose
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- A Linux or Windows based system that meets the [hardware prerequisites](/docs/getting-started/#hardware) and [architecture prerequisites](/docs/getting-started/#architecture).
|
||||
- [Docker](https://docs.docker.com/get-docker/)
|
||||
- [Docker Compose](https://docs.docker.com/compose/install/) - _preinstalled on many systems nowadays_
|
||||
|
||||
### Installation
|
||||
## Docker Compose
|
||||
|
||||
<DockerInstallSnippet data-visual-test="blackout" />
|
||||
Finally, run ``docker compose up -d`` in the same directory. This will start the Homarr container in the background.
|
||||
|
||||
:::caution
|
||||
Start Homarr from the directory containing `docker-compose.yaml`:
|
||||
|
||||
Docker compose creates a network by default. Some integrations may not work (specifically Dash.) when the network internal hostname is used since clients do not know this name. It is recommended that you either use a local network wide hostname or the IP directly. An alternative is to create a DNS record with the same internal compose stack hostname for all clients outside.
|
||||
```sh
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
:::
|
||||
Persist `/appdata`; it contains the database and configuration. Mount the Docker socket only when Homarr needs Docker
|
||||
discovery or management.
|
||||
|
||||
### Updating
|
||||
Integration URLs must be reachable from the Homarr container. Browser-facing app URLs may use a different hostname;
|
||||
see [Managing integrations](/docs/management/integrations#configuration).
|
||||
|
||||
To update, navigate to the directory with the `docker-compose.yaml` located.
|
||||
### Update
|
||||
|
||||
- Stop Homarr using `docker compose down`
|
||||
- Pull the newest image of Homarr using `docker compose pull`
|
||||
- Start Homarr again using `docker compose up -d` (`-d` for detached mode - start in background)
|
||||
- Delete the old image using `docker image prune` (_Warning: this also removes you other unused images - not just Homarr_)
|
||||
```sh
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
You can automate this process using [Watchtower](https://containrrr.dev/watchtower/).
|
||||
### Uninstall
|
||||
|
||||
### Uninstalling
|
||||
`docker compose down` removes the containers and Compose network. Delete the configured `/appdata` host directory or
|
||||
volume only when the Homarr data is no longer needed.
|
||||
|
||||
To uninstall, navigate to the directory with the `docker-compose.yaml` located.
|
||||
## Docker CLI
|
||||
|
||||
- Stop Homarr using `docker compose down`
|
||||
- Delete the created directories & files on your root file system (check `docker-compose.yaml` file for your specific locations)
|
||||
- Delete compose file using `rm docker-compose.yaml`
|
||||
- Prune unused Docker images using `docker image prune` (_Warning: this also removes you other unused images - not just Homarr_)
|
||||
- (Optional): Prune any network or volumes if you use any.
|
||||
- (Optional): Remove Homarr from your reverse proxy, VPNs or tunnels if you use any.
|
||||
The equivalent standalone container is:
|
||||
|
||||
## Docker standalone
|
||||
|
||||
:::caution
|
||||
|
||||
[Docker Compose](#docker-compose) is easier and recommended for beginners. Consider using compose instead.
|
||||
|
||||
:::
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- A Linux or Windows based system that meets the [hardware prerequisites](/docs/getting-started/#hardware) and [architecture prerequisites](/docs/getting-started/#architecture).
|
||||
- [Docker](https://docs.docker.com/get-docker/)
|
||||
|
||||
### Installation
|
||||
|
||||
To install Homarr using Docker, simply run the following command.
|
||||
|
||||
```bash
|
||||
docker run \
|
||||
```sh
|
||||
docker run \
|
||||
--name homarr \
|
||||
--restart unless-stopped \
|
||||
-p 7575:7575 \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
-v <your-path>/homarr/appdata:/appdata \
|
||||
-v /absolute/path/to/homarr/appdata:/appdata \
|
||||
-e SECRET_ENCRYPTION_KEY='your_64_character_hex_string' \
|
||||
-d ghcr.io/homarr-labs/homarr:latest
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
Docker will mount the configuration files and icons to your host machine. Please make sure to replace `<your-path>` from the docker run command with your desired storage location. The path must be absolute.
|
||||
|
||||
:::
|
||||
|
||||
### Updating
|
||||
|
||||
To update Homarr, you must remove your container first. Make sure that you've mounted your data and that you have access to it, so your configuration doesn't get lost.
|
||||
|
||||
1. Run `docker rm homarr` to remove the container.
|
||||
2. Pull the latest Homarr image `docker pull ghcr.io/homarr-labs/homarr:latest`.
|
||||
3. Re-run the command you used to install Homarr.
|
||||
|
||||
This process can get tideous, if you update frequently. Thus, we recommend [using docker-compose](#docker-compose)
|
||||
|
||||
:::tip
|
||||
|
||||
Want to update all your containers automatically? Checkout [Watchtower](https://containrrr.dev/watchtower/) a service which will automatically update your containers on a set interval.
|
||||
|
||||
:::
|
||||
|
||||
### Uninstalling
|
||||
|
||||
1. Obtain the container ID of your Homarr container using `docker ps | grep homarr`.
|
||||
2. Delete the container using `docker rm <your-container-id>`
|
||||
3. Prune unused Docker images using `docker image prune` (_Warning: this also removes you other unused images - not just Homarr_)
|
||||
4. (Optional): Prune any network or volumes if you use any.
|
||||
5. (Optional): Remove Homarr from your reverse proxy, VPNs or tunnels if you use any.
|
||||
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.
|
||||
@@ -1,14 +1,8 @@
|
||||
# Portainer
|
||||
|
||||
## Portainer Stacks
|
||||
## Install with a stack
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- [Portainer Stacks](https://www.portainer.io/blog/stacks-docker-compose-the-portainer-way)
|
||||
|
||||
### Installing
|
||||
|
||||
To install Homarr using Portainer Stacks, simply create a new stack and paste the following code into it.
|
||||
Create a Portainer stack with this Compose file:
|
||||
|
||||
```yml title="docker-compose.yml"
|
||||
#---------------------------------------------------------------------#
|
||||
@@ -28,21 +22,12 @@ services:
|
||||
- "7575:7575"
|
||||
```
|
||||
|
||||
:::note
|
||||
Portainer will mount the files to your host machine. Please make sure to replace `<your-path>` from the docker run command with your desired storage location. The path must be absolute.
|
||||
:::
|
||||
|
||||
Then, click on `Deploy the stack` and wait until the container has started.
|
||||
|
||||
:::tip
|
||||
|
||||
If you're unsure how to create a stack, checkout the [Portainer Documentation](https://docs.portainer.io/user/docker/stacks/add).
|
||||
|
||||
:::
|
||||
Replace `<your-path>` with an absolute host path, generate `SECRET_ENCRYPTION_KEY`, then deploy the stack. See
|
||||
[Portainer's stack documentation](https://docs.portainer.io/user/docker/stacks/add) for Portainer-specific options.
|
||||
|
||||
### Updating
|
||||
|
||||
To update Homarr using Docker Compose or Portainer Stacks, simply pull the latest image and restart the container.
|
||||
Pull the current image and redeploy the stack:
|
||||
|
||||
1. Run `docker pull ghcr.io/homarr-labs/homarr:latest` to pull the latest image.
|
||||
2. Re-run `docker-compose up -d` or re-deploy the stack in Portainer.
|
||||
@@ -1,9 +1,11 @@
|
||||
# QNAP
|
||||
|
||||
:::caution
|
||||
QNAP installation guide has not updated to 1.0 yet. There guide is still for 0.15.10.
|
||||
|
||||
The available QNAP guides target Homarr 0.15.10 and have not been updated for 1.0.
|
||||
|
||||
:::
|
||||
|
||||
When installing on QNAP, we recommend you to install Homarr using [Container Station](https://www.qnap.com/en/software/container-station) or [this third-party image](https://www.myqnap.org/product/homarr/).
|
||||
|
||||
There is also a guide available, but note that it is written in Chinese: https://post.smzdm.com/p/awzm7op2/
|
||||
Run Homarr with [Container Station](https://www.qnap.com/en/software/container-station) or the
|
||||
[third-party QNAP package](https://www.myqnap.org/product/homarr/). A community
|
||||
[Container Station guide](https://post.smzdm.com/p/awzm7op2/) is available in Chinese.
|
||||
@@ -1,33 +1,12 @@
|
||||
# Runtipi
|
||||
|
||||
Runtipi is a self-hosted orchestrator that makes it easy to manage and run multiple services on a single server. It is based on Docker and comes with a simple web interface to manage your services. Runtipi is designed to be easy to use, so you don't have to worry about manual configuration or networking.
|
||||
Homarr is available in the default [Runtipi](https://runtipi.io) app store.
|
||||
|
||||
https://runtipi.io
|
||||
## Installation
|
||||
|
||||
## Prerequisites
|
||||
Install **Homarr** from the Runtipi app store and select either a port or domain for access.
|
||||
|
||||
- [Runtipi](https://runtipi.io/docs/getting-started/installation)
|
||||
Runtipi manages start, stop, update, backup, and log operations under **My apps → Homarr**. Use a
|
||||
[user-config](https://runtipi.io/docs/guides/customize-app-config) to override the generated Compose configuration.
|
||||
|
||||
# Installation
|
||||
|
||||
Installing Homarr is pretty untuitive, the app is available in the default appstore :
|
||||
|
||||
1. Search for **"Homarr"** in the App-Store page and select it
|
||||
2. Click on **"Install"**.
|
||||
3. Choose the method you want to access Homarr, through any port or domain name then select **"Install"**
|
||||
|
||||
# Maintenance
|
||||
|
||||
After installation, all you need is available from the WebUI in **"My apps"** > **"Homarr"** :
|
||||
|
||||
- Start/Stop
|
||||
- Update
|
||||
- Backup
|
||||
- Logs
|
||||
|
||||
If you like to tinker with your apps, you can also edit your app's docker-compose with a [user-config](https://runtipi.io/docs/guides/customize-app-config).
|
||||
|
||||
# Getting help
|
||||
|
||||
- If you are looking for help with anything in Runtipi. They provide support on their [Discord](https://discord.gg/Bu9qEPnHsc) and [forums](https://forums.runtipi.io/). If you found vulnerabilities or bugs, [create a new issue here](https://github.com/runtipi/runtipi-appstore/issues).
|
||||
- If you are looking to report a bug, vulnerability or request a new feature for Homarr, use https://github.com/homarr-labs/homarr . You can ask for help on our Discord.
|
||||
See the [Runtipi installation documentation](https://runtipi.io/docs/getting-started/installation) for host setup.
|
||||
Reference in new issue
Block a user