We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
- Reporting a bug
@ -8,16 +9,20 @@ We love your input! We want to make contributing to this project as easy and tra
- Becoming a maintainer
## We Develop with Github
We use github to host code, to track issues and feature requests, as well as accept pull requests.
## Any contributions you make will be under the GNU General Public License v3.0
In short, when you submit code changes, your submissions are understood to be under the same [GNU General Public License v3.0](https://choosealicense.com/licenses/gpl-3.0/) that covers the project. Feel free to contact the maintainers if that's a concern.
## Report bugs using Github's [issues](https://github.com/gethomepage/homepage/issues)
We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/gethomepage/homepage/issues/new); it's that easy!
## Write bug reports with detail, background, and sample configurations
Homepage includes a lot of configuration options and is often deploying in larger systems. Please include as much information (configurations, deployment method, Docker & API versions, etc) as you can when reporting an issue.
Homepage includes a lot of configuration options and is often deploying in larger systems. Please include as much information (configurations, deployment method, Docker & API versions, etc) as you can when reporting an issue.
**Great Bug Reports** tend to have:
@ -29,16 +34,20 @@ Homepage includes a lot of configuration options and is often deploying in large
- What actually happens
- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
People *love* thorough bug reports. I'm not even kidding.
People _love_ thorough bug reports. I'm not even kidding.
## Development Guidelines
Please see the [documentation regarding development](https://gethomepage.dev/latest/more/development/) and specifically the [guidelines for new service widgets](https://gethomepage.dev/latest/more/development/#service-widget-guidelines) if you are considering making one.
## Use a Consistent Coding Style
This project follows the [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript), please follow it when submitting pull requests.
## License
By contributing, you agree that your contributions will be licensed under its GNU General Public License.
## References
This document was adapted from the open-source contribution guidelines for [Facebook's Draft](https://github.com/facebook/draft-js/blob/main/CONTRIBUTING.md)
- CONTAINERS=1 # Allow access to viewing containers
- SERVICES=1 # Allow access to viewing services (necessary when using Docker Swarm)
- TASKS=1 # Allow access to viewing tasks (necessary when using Docker Swarm)
- POST=0 # Disallow any POST operations (effectively read-only)
ports:
- 127.0.0.1:2375:2375
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro # Mounted as read-only
restart: unless-stopped
homepage:
image: ghcr.io/gethomepage/homepage:latest
container_name: homepage
volumes:
- /path/to/config:/app/config
ports:
- 3000:3000
restart: unless-stopped
image: ghcr.io/gethomepage/homepage:latest
container_name: homepage
volumes:
- /path/to/config:/app/config
ports:
- 3000:3000
restart: unless-stopped
```
Then, inside of your `docker.yaml` settings file, you'd configure the docker instance like so:
```yaml
my-docker:
host: dockerproxy
port: 2375
host: dockerproxy
port: 2375
```
## Using Socket Directly
@ -76,14 +76,14 @@ If you'd rather use the socket directly, first make sure that you're passing the
```yaml
homepage:
image: ghcr.io/gethomepage/homepage:latest
container_name: homepage
volumes:
- /path/to/config:/app/config
- /var/run/docker.sock:/var/run/docker.sock # pass local proxy
ports:
- 3000:3000
restart: unless-stopped
image: ghcr.io/gethomepage/homepage:latest
container_name: homepage
volumes:
- /path/to/config:/app/config
- /var/run/docker.sock:/var/run/docker.sock # pass local proxy
ports:
- 3000:3000
restart: unless-stopped
```
If you're using `docker run`, this would be `-v /var/run/docker.sock:/var/run/docker.sock`.
@ -92,7 +92,7 @@ Then, inside of your `docker.yaml` settings file, you'd configure the docker ins
```yaml
my-docker:
socket: /var/run/docker.sock
socket: /var/run/docker.sock
```
## Services
@ -118,18 +118,18 @@ Below is an example of the same service entry shown above, as docker labels.
```yaml
services:
emby:
image: lscr.io/linuxserver/emby:latest
container_name: emby
ports:
- 8096:8096
restart: unless-stopped
labels:
- homepage.group=Media
- homepage.name=Emby
- homepage.icon=emby.png
- homepage.href=http://emby.home/
- homepage.description=Media server
emby:
image: lscr.io/linuxserver/emby:latest
container_name: emby
ports:
- 8096:8096
restart: unless-stopped
labels:
- homepage.group=Media
- homepage.name=Emby
- homepage.icon=emby.png
- homepage.href=http://emby.home/
- homepage.description=Media server
```
When your Docker instance has been properly configured, this service will be automatically discovered and added to your Homepage. **You do not need to specify the `server` or `container` values, as they will be automatically inferred.**
@ -142,32 +142,32 @@ You may also configure widgets, along with the standard service entry, again, us
@ -176,8 +176,8 @@ Docker swarm is supported and Docker services are specified with the same `serve
```yaml
my-docker:
socket: /var/run/docker.sock
swarm: true
socket: /var/run/docker.sock
swarm: true
```
For the automatic service discovery to discover all services it is important that homepage should be deployed on a manager node. Set deploy requirements to the master node in your stack yaml config, e.g.
@ -205,9 +205,9 @@ In order to detect every service within the Docker swarm it is necessary that se
As of v0.6.4 discovered services can include an optional `weight` field to determine sorting such that:
- Default weight for discovered services is 0
- Default weight for configured services is their index within their group scaled by 100, i.e. (index + 1) \* 100
- If two items have the same weight value, then they will be sorted by name
- Default weight for discovered services is 0
- Default weight for configured services is their index within their group scaled by 100, i.e. (index + 1) \* 100
- If two items have the same weight value, then they will be sorted by name
When the Kubernetes cluster connection has been properly configured, this service will be automatically discovered and added to your Homepage. **You do not need to specify the `namespace` or `app` values, as they will be automatically inferred.**
@ -103,33 +103,33 @@ Homepage can also read ingresses defined using the Traefik IngressRoute custom r
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: emby
annotations:
gethomepage.dev/href: "https://emby.example.com"
gethomepage.dev/enabled: "true"
gethomepage.dev/description: Media Server
gethomepage.dev/group: Media
gethomepage.dev/icon: emby.png
gethomepage.dev/app: emby-app # optional, may be needed if app.kubernetes.io/name != ingress metadata.name
@ -7,39 +7,39 @@ Homepage has an UNRAID community package that you may use to install homepage. T
## 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**.
- 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.
- 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**.
- 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.
- 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
!!! 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
```
```
- 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.
- 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.
As of v0.7.2 homepage migrated from benphelps/homepage to an "organization" repository located at [gethomepage/homepage](https://github.com/gethomepage/homepage/). The reason for this was to setup the project for longevity and allow for community maintenance.
Migrating your installation should be as simple as changing `image: ghcr.io/benphelps/homepage:latest` to `image: ghcr.io/gethomepage/homepage:latest`.
Migrating your installation should be as simple as changing `image: ghcr.io/benphelps/homepage:latest` to `image: ghcr.io/gethomepage/homepage:latest`.
Homepage is developed in English, component contributions must be in English. All translations are community provided, so a huge thanks go out to all those who have helped out so far!
Homepage is developed in English, component contributions must be in English. All translations are community provided, so a huge thanks go out to all those who have helped out so far!
All service widgets work essentially the same, that is, homepage makes a proxied call to an API made available by that service. The majority of the time widgets don't work it is a configuration issue. Of course, sometimes things do break. Some basic steps to try:
1. Ensure that you follow the rule mentioned on https://gethomepage.dev/latest/configs/service-widgets/. **Unless otherwise noted, URLs should not end with a / or other API path. Each widget will handle the path on its own.**. This is very important as including a trailing slash can result in an error.
1. Ensure that you follow the rule mentioned on https://gethomepage.dev/latest/configs/service-widgets/. **Unless otherwise noted, URLs should not end with a / or other API path. Each widget will handle the path on its own.**. This is very important as including a trailing slash can result in an error.
2. Verify the homepage installation can connect to the IP address or host you are using for the widget `url`. This is most simply achieved by pinging the server from the homepage machine, in Docker this means _from inside the container_ itself, e.g.:
2. Verify the homepage installation can connect to the IP address or host you are using for the widget `url`. This is most simply achieved by pinging the server from the homepage machine, in Docker this means _from inside the container_ itself, e.g.:
```
docker exec homepage ping SERVICEIPORDOMAIN
@ -27,10 +27,10 @@ All service widgets work essentially the same, that is, homepage makes a proxied
If your homepage install (container) cannot reach the service then you need to figure out why, for example in Docker this can mean putting the two containers on the same network, checking firewall issues, etc.
3. If you have verified that homepage can in fact reach the service then you can also check the API output using e.g. `curl`, which is often helpful if you do need to file a bug report. Again, depending on your networking setup this may need to be run from _inside the container_ as IP / hostname resolution can differ inside vs outside.
3. If you have verified that homepage can in fact reach the service then you can also check the API output using e.g. `curl`, which is often helpful if you do need to file a bug report. Again, depending on your networking setup this may need to be run from _inside the container_ as IP / hostname resolution can differ inside vs outside.
!!! note
`curl` is not installed in the base image by default but can be added inside the container with `apk add curl`.
The exact API endpoints and authentication vary of course, but in many cases instructions can be found by searching the web or if you feel comfortable looking at the homepage source code (e.g. `src/widgets/{widget}/widget.js`).
@ -9,9 +9,9 @@ Formatting is locale aware and will present your date in the regional format you
```yaml
- datetime:
text_size: xl
format:
timeStyle: short
text_size: xl
format:
timeStyle: short
```
Any options passed to `format` are passed directly to [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat), please reference the MDN documentation for all available options.
The API key & secret can be generated via the webui by creating a new user at _System/Access/Users_. Ensure "Generate a scrambled password to prevent local database logins for this user" is checked and then edit the effective privileges selecting **only**:
- Diagnostics: System Activity
- Status: Traffic Graph
- Diagnostics: System Activity
- Status: Traffic Graph
Finally, create a new API key which will download an `apikey.txt` file with your key and secret in it. Use the values as the username and password fields, respectively, in your homepage config.
shamoon
1 year ago