diff --git a/docs/authentication.md b/docs/authentication.md index 694dbe9d..13f42242 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -263,7 +263,7 @@ In NGINX you can specify [control access](https://docs.nginx.com/nginx/admin-gui ```text server { - listen 80; + listen 8080; server_name www.dashy.example.com; location / { root /path/to/dashy/; diff --git a/docs/configuring.md b/docs/configuring.md index a510f79f..3c812995 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -1,6 +1,6 @@ # Configuring -All app configuration is specified in [`/public/conf.yml`](https://github.com/Lissy93/dashy/blob/master/public/conf.yml) which is in [YAML Format](https://yaml.org/) format. If you're using Docker, this file can be passed in as a volume. Changes can either be made directly to this file, or done [through the UI](#editing-config-through-the-ui). From the UI you can also export, backup, reset, validate and download your configuration file. +All app configuration is specified in [`/user-data/conf.yml`](https://github.com/Lissy93/dashy/blob/master/user-data/conf.yml) which is in [YAML Format](https://yaml.org/) format. If you're using Docker, this file can be passed in as a volume. Changes can either be made directly to this file, or done [through the UI](#editing-config-through-the-ui). From the UI you can also export, backup, reset, validate and download your configuration file. ## There are three ways to edit the config diff --git a/docs/deployment.md b/docs/deployment.md index 175a44b0..89345b63 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -67,8 +67,8 @@ Dashy has a built container image hosted on [Docker Hub](https://hub.docker.com/ ```bash docker run -d \ - -p 8080:80 \ - -v /root/my-local-conf.yml:/app/public/conf.yml \ + -p 8080:8080 \ + -v /root/my-local-conf.yml:/app/user-data/conf.yml \ --name my-dashboard \ --restart=always \ lissy93/dashy:latest @@ -110,9 +110,9 @@ services: container_name: Dashy # Pass in your config file below, by specifying the path on your host machine # volumes: - # - /root/my-config.yml:/app/public/conf.yml + # - /root/my-config.yml:/app/user-data/conf.yml ports: - - 4000:80 + - 4000:8080 # Set any environmental variables environment: - NODE_ENV=production @@ -166,8 +166,8 @@ Installing dashy is really simply and fast: ```bash docker run -d \ - -p 4000:80 \ - -v /volume1/docker/dashy/my-local-conf.yml:/app/public/conf.yml \ + -p 4000:8080 \ + -v /volume1/docker/dashy/my-local-conf.yml:/app/user-data/conf.yml \ --name dashy \ --restart=always \ lissy93/dashy:latest @@ -182,7 +182,7 @@ dashy should be up within 1-2min after you've started the install task procedure If you do not want to use Docker, you can run Dashy directly on your host system. For this, you will need both [git](https://git-scm.com/downloads) and the latest or LTS version of [Node.js](https://nodejs.org/) installed, and optionally [yarn](https://yarnpkg.com/) 1. Get Code: `git clone https://github.com/Lissy93/dashy.git` and `cd dashy` -2. Configuration: Fill in you're settings in `./public/conf.yml` +2. Configuration: Fill in you're settings in `./user-data/conf.yml` 3. Install dependencies: `yarn` 4. Build: `yarn build` 5. Run: `yarn start` diff --git a/docs/developing.md b/docs/developing.md index 281f86f9..0168fc78 100644 --- a/docs/developing.md +++ b/docs/developing.md @@ -51,7 +51,7 @@ Dashy should now be being served on . Hot reload is enab #### Utils and Checks -- **`yarn validate-config`** - If you have quite a long configuration file, you may wish to check that it's all good to go, before deploying the app. This can be done with `yarn validate-config` or `docker exec -it [container-id] yarn validate-config`. Your config file needs to be in `/public/conf.yml` (or within your Docker container at `/app/public/conf.yml`). This will first check that your YAML is valid, and then validates it against Dashy's [schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js). +- **`yarn validate-config`** - If you have quite a long configuration file, you may wish to check that it's all good to go, before deploying the app. This can be done with `yarn validate-config` or `docker exec -it [container-id] yarn validate-config`. Your config file needs to be in `/user-data/conf.yml` (or within your Docker container at `/app/user-data/conf.yml`). This will first check that your YAML is valid, and then validates it against Dashy's [schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js). - **`yarn health-check`** - Checks that the application is up and running on it's specified port, and outputs current status and response times. Useful for integrating into your monitoring service, if you need to maintain high system availability #### Alternate Start Commands diff --git a/docs/development-guides.md b/docs/development-guides.md index 54d854d6..ffc6bd75 100644 --- a/docs/development-guides.md +++ b/docs/development-guides.md @@ -104,7 +104,7 @@ If you are not comfortable with making pull requests, or do not want to modify t This section is for, adding a new setting to the config file. -All of the users config is specified in `./public/conf.yml` - see [Configuring Docs](./configuring.md) for info. +All of the users config is specified in `./user-data/conf.yml` - see [Configuring Docs](./configuring.md) for info. It's important to first ensure that there isn't a similar option already available, the new option is definitely necessary, and most importantly that it is fully backwards compatible. Next choose the appropriate section to place it under diff --git a/docs/management.md b/docs/management.md index 89efd476..76b88653 100644 --- a/docs/management.md +++ b/docs/management.md @@ -30,11 +30,11 @@ _The following article is a primer on managing self-hosted apps. It covers every Although not essential, you will most likely want to provide several assets to your running app. -This is easy to do using [Docker Volumes](https://docs.docker.com/storage/volumes/), which lets you share a file or directory between your host system, and the container. Volumes are specified in the Docker run command, or Docker compose file, using the `--volume` or `-v` flags. The value of which consists of the path to the file / directory on your host system, followed by the destination path within the container. Fields are separated by a colon (`:`), and must be in the correct order. For example: `-v ~/alicia/my-local-conf.yml:/app/public/conf.yml` +This is easy to do using [Docker Volumes](https://docs.docker.com/storage/volumes/), which lets you share a file or directory between your host system, and the container. Volumes are specified in the Docker run command, or Docker compose file, using the `--volume` or `-v` flags. The value of which consists of the path to the file / directory on your host system, followed by the destination path within the container. Fields are separated by a colon (`:`), and must be in the correct order. For example: `-v ~/alicia/my-local-conf.yml:/app/user-data/conf.yml` In Dashy, commonly configured resources include: -- `./public/conf.yml` - Your main application config file +- `./user-data/conf.yml` - Your main application config file - `./public/item-icons` - A directory containing your own icons. This allows for offline access, and better performance than fetching from a CDN - Also within `./public` you'll find standard website assets, including `favicon.ico`, `manifest.json`, `robots.txt`, etc. There's no need to pass these in, but you can do so if you wish - `/src/styles/user-defined-themes.scss` - A stylesheet for applying custom CSS to your app. You can also write your own themes here. @@ -238,7 +238,7 @@ Once you've generated your SSL cert, you'll need to pass it to Dashy. This can b ```bash docker run -d \ - -p 8080:80 \ + -p 8080:8080 \ -v ~/my-private-key.key:/etc/ssl/certs/dashy-priv.key:ro \ -v ~/my-public-key.pem:/etc/ssl/certs/dashy-pub.pem:ro \ lissy93/dashy:latest @@ -276,9 +276,9 @@ services: container_name: Dashy image: lissy93/dashy volumes: - - /root/my-config.yml:/app/public/conf.yml + - /root/my-config.yml:/app/user-data/conf.yml ports: - - 4000:80 + - 4000:8080 environment: - BASE_URL=/my-dashboard restart: unless-stopped @@ -550,7 +550,7 @@ upstream dashy { } server { - listen 80; + listen 8080; server_name dashy.mydomain.com; # Setup SSL @@ -577,7 +577,7 @@ Similarly, a basic `Caddyfile` might look like: ```text dashy.example.com { - reverse_proxy / nginx:80 + reverse_proxy / nginx:8080 } ``` @@ -614,7 +614,7 @@ To prevent known container escape vulnerabilities, which typically end in escala Docker enables you to limit resource consumption (CPU, memory, disk) on a per-container basis. This not only enhances system performance, but also prevents a compromised container from consuming a large amount of resources, in order to disrupt service or perform malicious activities. To learn more, see the [Resource Constraints Docs](https://docs.docker.com/config/containers/resource_constraints/) For example, to run Dashy with max of 1GB ram, and max of 50% of 1 CP core: -`docker run -d -p 8080:80 --cpus=".5" --memory="1024m" lissy93/dashy:latest` +`docker run -d -p 8080:8080 --cpus=".5" --memory="1024m" lissy93/dashy:latest` ### Don't Run as Root @@ -629,7 +629,7 @@ One of the best ways to prevent privilege escalation attacks, is to configure th You can specify a user, using the [`--user` param](https://docs.docker.com/engine/reference/run/#user), and should include the user ID (`UID`), which can be found by running `id -u`, and the and the group ID (`GID`), using `id -g`. With Docker run, you specify it like: -`docker run --user 1000:1000 -p 8080:80 lissy93/dashy` +`docker run --user 1000:1000 -p 8080:8080 lissy93/dashy` Of if you're using Docker-compose, you could use an environmental variable @@ -639,7 +639,7 @@ services: dashy: image: lissy93/dashy user: ${CURRENT_UID} - ports: [ 4000:80 ] + ports: [ 4000:8080 ] ``` And then to set the variable, and start the container, run: `CURRENT_UID=$(id -u):$(id -g) docker-compose up` @@ -659,7 +659,7 @@ version: "3.8" services: dashy: image: lissy93/dashy - ports: [ 4000:80 ] + ports: [ 4000:8080 ] cap_drop: - ALL cap_add: @@ -675,7 +675,7 @@ services: To prevent processes inside the container from getting additional privileges, pass in the `--security-opt=no-new-privileges:true` option to the Docker run command (see [docs](https://docs.docker.com/engine/reference/run/#security-configuration)). Run Command: -`docker run --security-opt=no-new-privileges:true -p 8080:80 lissy93/dashy` +`docker run --security-opt=no-new-privileges:true -p 8080:8080 lissy93/dashy` Docker Compose @@ -701,14 +701,14 @@ You can specify that a specific volume should be read-only by appending `:ro` to ```bash docker run -d \ - -p 8080:80 \ - -v ~/dashy-conf.yml:/app/public/conf.yml \ + -p 8080:8080 \ + -v ~/dashy-conf.yml:/app/user-data/conf.yml \ -v ~/dashy-icons:/app/public/item-icons:ro \ -v ~/dashy-theme.scss:/app/src/styles/user-defined-themes.scss:ro \ lissy93/dashy:latest ``` -You can also prevent a container from writing any changes to volumes on your host's disk, using the `--read-only` flag. Although, for Dashy, you will not be able to write config changes to disk, when edited through the UI with this method. You could make this work, by specifying the config directory as a temp write location, with `--tmpfs /app/public/conf.yml` - but that this will not write the volume back to your host. +You can also prevent a container from writing any changes to volumes on your host's disk, using the `--read-only` flag. Although, for Dashy, you will not be able to write config changes to disk, when edited through the UI with this method. You could make this work, by specifying the config directory as a temp write location, with `--tmpfs /app/user-data/conf.yml` - but that this will not write the volume back to your host. ### Set the Logging Level @@ -778,8 +778,8 @@ Create a new file in `/etc/nginx/sites-enabled/dashy` ```text server { - listen 80; - listen [::]:80; + listen 8080; + listen [::]:8080; root /var/www/dashy/html; index index.html; @@ -898,7 +898,7 @@ Similar to above, you'll first need to fork and clone Dashy to your local system Then, either use Dashy's default [`Dockerfile`](https://github.com/Lissy93/dashy/blob/master/Dockerfile) as is, or modify it according to your needs. -To build and deploy locally, first build the app with: `docker build -t dashy .`, and then start the app with `docker run -p 8080:80 --name my-dashboard dashy`. Or modify the `docker-compose.yml` file, replacing `image: lissy93/dashy` with `build: .` and run `docker compose up`. +To build and deploy locally, first build the app with: `docker build -t dashy .`, and then start the app with `docker run -p 8080:8080 --name my-dashboard dashy`. Or modify the `docker-compose.yml` file, replacing `image: lissy93/dashy` with `build: .` and run `docker compose up`. Your container should now be running, and will appear in the list when you run `docker container ls –a`. If you'd like to enter the container, run `docker exec -it [container-id] /bin/ash`. diff --git a/docs/quick-start.md b/docs/quick-start.md index 3bfa083f..bf1c83f3 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -20,7 +20,7 @@ To pull the latest image, and build and start the app run: ```bash docker run -d \ -p 8080:80 \ - -v ~/my-conf.yml:/app/public/conf.yml \ + -v ~/my-conf.yml:/app/user-data/conf.yml \ --name my-dashboard \ --restart=always \ lissy93/dashy:latest @@ -35,7 +35,7 @@ Your dashboard should now be up and running at `http://localhost:8080` (or your ## 3. Configure Now that you've got Dashy running, you are going to want to set it up with your own content. -Config is written in [YAML Format](https://yaml.org/), and saved in [`/public/conf.yml`](https://github.com/Lissy93/dashy/blob/master/public/conf.yml). +Config is written in [YAML Format](https://yaml.org/), and saved in [`/user-data/conf.yml`](https://github.com/Lissy93/dashy/blob/master/user-data/conf.yml). The format on the config file is pretty straight forward. There are three root attributes: - [`pageInfo`](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#pageinfo) - Dashboard meta data, like title, description, nav bar links and footer text @@ -72,7 +72,7 @@ sections: # An array of sections Notes: - You can use a Docker volume to pass a config file from your host system to the container - - E.g. `-v ./host-system/my-local-conf.yml:/app/public/conf.yml` + - E.g. `-v ./host-system/my-local-conf.yml:/app/user-data/conf.yml` - It's also possible to edit your config directly through the UI, and changes will be saved in this file - Check your config against Dashy's schema, with `docker exec -it [container-id] yarn validate-config` - You might find it helpful to look at some examples, a collection of which can be [found here](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10) @@ -118,7 +118,7 @@ yarn build # Build the app yarn start # Start the app ``` -Then edit `./public/conf.yml` and rebuild the app with `yarn build` +Then edit `./user-data/conf.yml` and rebuild the app with `yarn build` --- @@ -129,7 +129,7 @@ Don't have a server? No problem! You can run Dashy for free on Netlify (as well 1. Fork Dashy's repository on GitHub 2. [Log in](app.netlify.com/login/) to Netlify with GitHub 3. Click "New site from Git" and select your forked repo, then click **Deploy**! -4. You can then edit the config in `./public/conf.yml` in your repo, and Netlify will rebuild the app +4. You can then edit the config in `./user-data/conf.yml` in your repo, and Netlify will rebuild the app --- diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 44fcfcbc..83b04cf0 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -234,7 +234,7 @@ Version 2.0.4 introduced changes to how the config is read, and the app is build ```yaml volumes: -- /srv/dashy/conf.yml:/app/public/conf.yml +- /srv/dashy/conf.yml:/app/user-data/conf.yml - /srv/dashy/item-icons:/app/public/item-icons ``` @@ -273,12 +273,12 @@ See also: #479, #409, #507, #491, #341, #520 Error response from daemon: OCI runtime create failed: container_linux.go:380: starting container process caused: process_linux.go:545: container init caused: rootfs_linux.go:76: mounting "/home/ubuntu/my-conf.yml" to rootfs at -"/app/public/conf.yml" caused: mount through procfd: not a directory: +"/app/user-data/conf.yml" caused: mount through procfd: not a directory: unknown: Are you trying to mount a directory onto a file (or vice-versa)? Check if the specified host path exists and is the expected type. ``` -If you get an error similar to the one above, you are mounting a directory to the config file's location, when a plain file is expected. Create a YAML file, (`touch my-conf.yml`), populate it with a sample config, then pass it as a volume: `-v ./my-local-conf.yml:/app/public/conf.yml` +If you get an error similar to the one above, you are mounting a directory to the config file's location, when a plain file is expected. Create a YAML file, (`touch my-conf.yml`), populate it with a sample config, then pass it as a volume: `-v ./my-local-conf.yml:/app/user-data/conf.yml` ---