mirror of
https://github.com/DI0IK/homepage-plus.git
synced 2025-07-15 17:30:30 +00:00
add mkdocs
This commit is contained in:
Ben Phelps
parent
b215843b26
commit
47765ee05e
144 changed files with 4219 additions and 3 deletions
57
docs/installation/docker.md
Normal file
57
docs/installation/docker.md
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
---
|
||||
title: Docker Installation
|
||||
description: Install and run homepage from Docker
|
||||
---
|
||||
|
||||
Using docker compose:
|
||||
|
||||
```yaml
|
||||
version: "3.3"
|
||||
services:
|
||||
homepage:
|
||||
image: ghcr.io/benphelps/homepage:latest
|
||||
container_name: homepage
|
||||
ports:
|
||||
- 3000:3000
|
||||
volumes:
|
||||
- /path/to/config:/app/config # Make sure your local config directory exists
|
||||
- /var/run/docker.sock:/var/run/docker.sock # (optional) For docker integrations
|
||||
```
|
||||
|
||||
### Running as non-root
|
||||
|
||||
By default, the Homepage container runs as root. Homepage also supports running your container as non-root via the standard `PUID` and `PGID` environment variables. When using these variables, make sure that any volumes mounted in to the container have the correct ownership and permissions set.
|
||||
|
||||
_Using the docker socket directly is not the recommended method of integration and requires either running homepage as root or that the user be part of the docker group_
|
||||
|
||||
In the docker compose example below, the environment variables `$PUID` and `$PGID` are set in a `.env` file.
|
||||
|
||||
```yaml
|
||||
version: "3.3"
|
||||
services:
|
||||
homepage:
|
||||
image: ghcr.io/benphelps/homepage:latest
|
||||
container_name: homepage
|
||||
ports:
|
||||
- 3000:3000
|
||||
volumes:
|
||||
- /path/to/config:/app/config # Make sure your local config directory exists
|
||||
- /var/run/docker.sock:/var/run/docker.sock # (optional) For docker integrations, see alternative methods
|
||||
environment:
|
||||
PUID: $PUID
|
||||
PGID: $PGID
|
||||
```
|
||||
|
||||
### With Docker Run
|
||||
|
||||
```bash
|
||||
docker run -p 3000:3000 -v /path/to/config:/app/config -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/benphelps/homepage:latest
|
||||
```
|
||||
|
||||
### Using Environment Secrets
|
||||
|
||||
You can also include environment variables in your config files to protect sensitive information. Note:
|
||||
|
||||
- Environment variables must start with `HOMEPAGE_VAR_` or `HOMEPAGE_FILE_`
|
||||
- The value of env var `HOMEPAGE_VAR_XXX` will replace `{{HOMEPAGE_VAR_XXX}}` in any config
|
||||
- The value of env var `HOMEPAGE_FILE_XXX` must be a file path, the contents of which will be used to replace `{{HOMEPAGE_FILE_XXX}}` in any config
|
||||
25
docs/installation/index.md
Normal file
25
docs/installation/index.md
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
---
|
||||
title: Installation
|
||||
description: Docs intro
|
||||
---
|
||||
|
||||
<p>
|
||||
You have a few options for deploying homepage, depending on your needs. We offer docker images for a majority of platforms. You can also install and run homepage from source if Docker is not your thing. It can even be installed on Kubernetes with Helm.
|
||||
</p>
|
||||
|
||||
<br>
|
||||
|
||||
<div class="grid cards" style="margin: 0 auto;" markdown>
|
||||
:simple-docker: [ Install on Docker :octicons-arrow-right-24:](docker.md)
|
||||
{ .card }
|
||||
|
||||
:simple-kubernetes: [ Install on Kubernetes :octicons-arrow-right-24:](k8s.md)
|
||||
{ .card }
|
||||
|
||||
:simple-unraid: [ Install on UNRAID :octicons-arrow-right-24:](unraid.md)
|
||||
{ .card }
|
||||
|
||||
:simple-nextdotjs: [ Building from source :octicons-arrow-right-24:](source.md)
|
||||
{ .card }
|
||||
|
||||
</div>
|
||||
341
docs/installation/k8s.md
Normal file
341
docs/installation/k8s.md
Normal file
|
|
@ -0,0 +1,341 @@
|
|||
---
|
||||
title: Kubernetes Installation
|
||||
description: Install on Kubernetes
|
||||
---
|
||||
|
||||
## Install with Helm
|
||||
|
||||
There is an [unofficial helm chart](https://github.com/jameswynn/helm-charts/tree/main/charts/homepage) that creates all the necessary manifests, including the service account and RBAC entities necessary for service discovery.
|
||||
|
||||
```sh
|
||||
helm repo add jameswynn https://jameswynn.github.io/helm-charts
|
||||
helm install homepage jameswynn/homepage -f values.yaml
|
||||
```
|
||||
|
||||
The helm chart allows for all the configurations to be inlined directly in your `values.yaml`:
|
||||
|
||||
```yaml
|
||||
config:
|
||||
bookmarks:
|
||||
- Developer:
|
||||
- Github:
|
||||
- abbr: GH
|
||||
href: https://github.com/
|
||||
services:
|
||||
- My First Group:
|
||||
- My First Service:
|
||||
href: http://localhost/
|
||||
description: Homepage is awesome
|
||||
|
||||
- My Second Group:
|
||||
- My Second Service:
|
||||
href: http://localhost/
|
||||
description: Homepage is the best
|
||||
|
||||
- My Third Group:
|
||||
- My Third Service:
|
||||
href: http://localhost/
|
||||
description: Homepage is 😎
|
||||
widgets:
|
||||
# show the kubernetes widget, with the cluster summary and individual nodes
|
||||
- kubernetes:
|
||||
cluster:
|
||||
show: true
|
||||
cpu: true
|
||||
memory: true
|
||||
showLabel: true
|
||||
label: "cluster"
|
||||
nodes:
|
||||
show: true
|
||||
cpu: true
|
||||
memory: true
|
||||
showLabel: true
|
||||
- search:
|
||||
provider: duckduckgo
|
||||
target: _blank
|
||||
kubernetes:
|
||||
mode: cluster
|
||||
settings:
|
||||
|
||||
# The service account is necessary to allow discovery of other services
|
||||
serviceAccount:
|
||||
create: true
|
||||
name: homepage
|
||||
|
||||
# This enables the service account to access the necessary resources
|
||||
enableRbac: true
|
||||
|
||||
ingress:
|
||||
main:
|
||||
enabled: true
|
||||
annotations:
|
||||
# Example annotations to add Homepage to your Homepage!
|
||||
gethomepage.dev/enabled: "true"
|
||||
gethomepage.dev/name: "Homepage"
|
||||
gethomepage.dev/description: "Dynamically Detected Homepage"
|
||||
gethomepage.dev/group: "Dynamic"
|
||||
gethomepage.dev/icon: "homepage.png"
|
||||
hosts:
|
||||
- host: homepage.example.com
|
||||
paths:
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
```
|
||||
|
||||
## Install with Kubernetes Manifests
|
||||
|
||||
If you don't want to use the unofficial Helm chart, you can also create your own Kubernetes manifest(s) and apply them with `kubectl apply -f filename.yaml`.
|
||||
|
||||
Here's a working example of the resources you need:
|
||||
|
||||
#### ServiceAccount
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: homepage
|
||||
namespace: default
|
||||
labels:
|
||||
app.kubernetes.io/name: homepage
|
||||
secrets:
|
||||
- name: homepage
|
||||
```
|
||||
|
||||
#### Secret
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
type: kubernetes.io/service-account-token
|
||||
metadata:
|
||||
name: homepage
|
||||
namespace: default
|
||||
labels:
|
||||
app.kubernetes.io/name: homepage
|
||||
annotations:
|
||||
kubernetes.io/service-account.name: homepage
|
||||
```
|
||||
|
||||
#### ConfigMap
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: homepage
|
||||
namespace: default
|
||||
labels:
|
||||
app.kubernetes.io/name: homepage
|
||||
data:
|
||||
kubernetes.yaml: |
|
||||
mode: cluster
|
||||
settings.yaml: ""
|
||||
#settings.yaml: |
|
||||
# providers:
|
||||
# longhorn:
|
||||
# url: https://longhorn.my.network
|
||||
custom.css: ""
|
||||
custom.js: ""
|
||||
bookmarks.yaml: |
|
||||
- Developer:
|
||||
- Github:
|
||||
- abbr: GH
|
||||
href: https://github.com/
|
||||
services.yaml: |
|
||||
- My First Group:
|
||||
- My First Service:
|
||||
href: http://localhost/
|
||||
description: Homepage is awesome
|
||||
|
||||
- My Second Group:
|
||||
- My Second Service:
|
||||
href: http://localhost/
|
||||
description: Homepage is the best
|
||||
|
||||
- My Third Group:
|
||||
- My Third Service:
|
||||
href: http://localhost/
|
||||
description: Homepage is 😎
|
||||
widgets.yaml: |
|
||||
- kubernetes:
|
||||
cluster:
|
||||
show: true
|
||||
cpu: true
|
||||
memory: true
|
||||
showLabel: true
|
||||
label: "cluster"
|
||||
nodes:
|
||||
show: true
|
||||
cpu: true
|
||||
memory: true
|
||||
showLabel: true
|
||||
- resources:
|
||||
backend: resources
|
||||
expanded: true
|
||||
cpu: true
|
||||
memory: true
|
||||
- search:
|
||||
provider: duckduckgo
|
||||
target: _blank
|
||||
docker.yaml: ""
|
||||
```
|
||||
|
||||
#### ClusterRole and ClusterRoleBinding
|
||||
|
||||
```yaml
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: ClusterRole
|
||||
metadata:
|
||||
name: homepage
|
||||
labels:
|
||||
app.kubernetes.io/name: homepage
|
||||
rules:
|
||||
- apiGroups:
|
||||
- ""
|
||||
resources:
|
||||
- namespaces
|
||||
- pods
|
||||
- nodes
|
||||
verbs:
|
||||
- get
|
||||
- list
|
||||
- apiGroups:
|
||||
- extensions
|
||||
- networking.k8s.io
|
||||
resources:
|
||||
- ingresses
|
||||
verbs:
|
||||
- get
|
||||
- list
|
||||
- apiGroups:
|
||||
- traefik.containo.us
|
||||
resources:
|
||||
- ingressroutes
|
||||
verbs:
|
||||
- get
|
||||
- list
|
||||
- apiGroups:
|
||||
- metrics.k8s.io
|
||||
resources:
|
||||
- nodes
|
||||
- pods
|
||||
verbs:
|
||||
- get
|
||||
- list
|
||||
---
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: ClusterRoleBinding
|
||||
metadata:
|
||||
name: homepage
|
||||
labels:
|
||||
app.kubernetes.io/name: homepage
|
||||
roleRef:
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
kind: ClusterRole
|
||||
name: homepage
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: homepage
|
||||
namespace: default
|
||||
```
|
||||
|
||||
#### Service
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: homepage
|
||||
namespace: default
|
||||
labels:
|
||||
app.kubernetes.io/name: homepage
|
||||
annotations:
|
||||
spec:
|
||||
type: ClusterIP
|
||||
ports:
|
||||
- port: 3000
|
||||
targetPort: http
|
||||
protocol: TCP
|
||||
name: http
|
||||
selector:
|
||||
app.kubernetes.io/name: homepage
|
||||
```
|
||||
|
||||
#### Deployment
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: homepage
|
||||
namespace: default
|
||||
labels:
|
||||
app.kubernetes.io/name: homepage
|
||||
spec:
|
||||
revisionHistoryLimit: 3
|
||||
replicas: 1
|
||||
strategy:
|
||||
type: RollingUpdate
|
||||
selector:
|
||||
matchLabels:
|
||||
app.kubernetes.io/name: homepage
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app.kubernetes.io/name: homepage
|
||||
spec:
|
||||
serviceAccountName: homepage
|
||||
automountServiceAccountToken: true
|
||||
dnsPolicy: ClusterFirst
|
||||
enableServiceLinks: true
|
||||
containers:
|
||||
- name: homepage
|
||||
image: "ghcr.io/benphelps/homepage:latest"
|
||||
imagePullPolicy: Always
|
||||
ports:
|
||||
- name: http
|
||||
containerPort: 3000
|
||||
protocol: TCP
|
||||
volumeMounts:
|
||||
- name: homepage-config
|
||||
mountPath: /app/config
|
||||
- name: logs
|
||||
mountPath: /app/config/logs
|
||||
volumes:
|
||||
- name: homepage-config
|
||||
configMap:
|
||||
name: homepage
|
||||
- name: logs
|
||||
emptyDir: {}
|
||||
```
|
||||
|
||||
#### Ingress
|
||||
|
||||
```yaml
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: homepage
|
||||
namespace: default
|
||||
labels:
|
||||
app.kubernetes.io/name: homepage
|
||||
annotations:
|
||||
gethomepage.dev/description: Dynamically Detected Homepage
|
||||
gethomepage.dev/enabled: "true"
|
||||
gethomepage.dev/group: Cluster Management
|
||||
gethomepage.dev/icon: homepage.png
|
||||
gethomepage.dev/name: Homepage
|
||||
spec:
|
||||
rules:
|
||||
- host: "homepage.my.network"
|
||||
http:
|
||||
paths:
|
||||
- path: "/"
|
||||
pathType: Prefix
|
||||
backend:
|
||||
service:
|
||||
name: homepage
|
||||
port:
|
||||
number: 3000
|
||||
```
|
||||
25
docs/installation/source.md
Normal file
25
docs/installation/source.md
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
---
|
||||
title: Source Installation
|
||||
description: Install and run homepage from source
|
||||
---
|
||||
|
||||
First, clone the repository:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/benphelps/homepage.git
|
||||
```
|
||||
|
||||
Then install dependencies and build the production bundle (I'm using pnpm here, you can use npm or yarn if you like):
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm build
|
||||
```
|
||||
|
||||
If this is your first time starting, copy the `src/skeleton` directory to `config/` to populate initial example config files.
|
||||
|
||||
Finally, run the server:
|
||||
|
||||
```bash
|
||||
pnpm start
|
||||
```
|
||||
45
docs/installation/unraid.md
Normal file
45
docs/installation/unraid.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
title: UNRAID Installation
|
||||
description: Install and run homepage on UNRAID
|
||||
---
|
||||
|
||||
Homepage has an UNRAID community package that you may use to install homepage. This is the easiest way to get started with homepage on UNRAID.
|
||||
|
||||
## Install the Plugin
|
||||
|
||||
- In the UNRAID webGUI, go to the **Apps** tab.
|
||||
- In the search bar, search for `homepage`.
|
||||
- Click on **Install**.
|
||||
- Change the parameters to your liking.
|
||||
- Click on **APPLY**.
|
||||
|
||||
## Run the Container
|
||||
|
||||
- While the container is running, open the WebUI.
|
||||
- Opening the page will generate the configuration files.
|
||||
|
||||
You may need to set the permissions of the folders to be able to edit the files.
|
||||
|
||||
- Click on the Homepage icon.
|
||||
- Click on **Console**.
|
||||
- Enter `chmod -R u-x,go-rwx,go+u,ugo+X /app/config` and press **Enter**.
|
||||
- Enter `chmod -R u-x,go-rwx,go+u,ugo+X /app/public/icons` and press **Enter**.
|
||||
- Enter `chown -R nobody:users /app/config` and press **Enter**.
|
||||
- Enter `chown -R nobody:users /app/public/icons` and press **Enter**.
|
||||
|
||||
## Some Other Notes
|
||||
|
||||
- To use the [Docker integration](../configs/docker.md), you only need to use the `container:` parameter. There is no need to set the server.
|
||||
|
||||
!!! note
|
||||
|
||||
To view detailed container statistics (CPU, RAM, etc.), or if you use a remote docker socket, `container:` will still need to be set. For example:
|
||||
|
||||
```
|
||||
- Plex:
|
||||
icon: /icons/plex.png
|
||||
href: https://app.plex.com
|
||||
container: plex
|
||||
```
|
||||
|
||||
- When you upload a new image into the **/images** folder, you will need to restart the container for it to show up in the WebUI. Please see the [service icons](../configs/services.md#icons) for more information.
|
||||
Loading…
Add table
Add a link
Reference in a new issue