Merge branch 'main' of github.com:OliveTin/docs.olivetin.app

modules/ROOT/pages/action_examples/ssh-manual.adoc

@@ -42,12 +42,21 @@ The steps in detail are below;
 Open a terminal window on _server-with-olivetin_. 
 
 [loweralpha]
-. Run `mkdir /opt/OliveTinSshKeys` to create a shared directory for your SSH key file.
+. Create the `/opt/OliveTinSshKeys` directory, to create a shared directory for your SSH key file.
++
+[source,bash]
+----
+root@server-with-olivetin: mkdir /opt/OliveTinSshKeys
+----
 +
 This will later be used as a "volume mount" when you create a docker container. 
 
 . Run `ssh-keygen` to generate a SSH key just for OliveTin.
 +
+[source,bash]
+----
+root@server-with-olivetin: ssh-keygen
+----
 [lowerroman]
 .. Enter the file in which to save the key: `/opt/OliveTinSshKeys/id_rsa`
 .. Enter passphrase (empty for no passphrase): `<enter>`

modules/ROOT/pages/action_execution.adoc

@@ -228,10 +228,10 @@ actions:
   - title: Check date and send notification via apprise
     icon: date
     shell: date
-    shellAfterCompleted: "apprise -c /config/apprise.yml -t 'Notification: Backup script completed' -b 'The backup script completed with code {{ exitCode}}. The log is: \n {{ stdout }} '"
+    shellAfterCompleted: "apprise -c /config/apprise.yml -t 'Notification: Backup script completed' -b 'The backup script completed with code {{ exitCode}}. The log is: \n {{ output }} '"
 ----
 
-When running shellAfterCompleted, you *cannot* use argument values - they are not passed to the command. However two special arguments are defined as shown above - `exitCode` and `stdout` from the previous `shell` command. 
+When running shellAfterCompleted, you *cannot* use argument values - they are not passed to the command. However two special arguments are defined as shown above - `exitCode` and `output` from the previous `shell` command. 
 
 You can only use a single `shellAfterCompleted`, so use it for notifications, or similar. It would be an antipattern to use this do run 2 commands making up a mini script.
 

modules/ROOT/pages/advanced_configuration.adoc

@@ -42,6 +42,26 @@ actions:
 .The same user interface, but with the "Actions" and "Settings" buttons hidden (`showNavigation: false`)
 image::images/defaultUiHideNav.png[]
 
+[#section-navgiation-style]
+==== Section Navigation Style
+
+`sectionNavigationStyle` - You can choose to have the section navigation buttons displayed as a Sidebar (`sidebar` - default), or along the top (`topbar`).
+
+[#custom-js]
+==== Custom JavaScript
+
+This is considered an advanced feature, and is not recommended unless you like writing your own code.
+
+You can add custom JavaScript to OliveTin, which will be executed on every page load. This can be useful for adding custom functionality to the web UI.
+
+The custom javascript should be in a file called `custom.js` and saved in `custom-webui/`, which should be in the same directory as your `config.yaml`.
+
+You will need to set `enableCustomJs` to `true` in your `config.yaml` to enable this feature.
+
+==== Custom Themes / Stylesheet rules
+
+See <<themes>>.
+
 [#show-new-versions]
 ==== Show new versions
 

modules/ROOT/pages/args.adoc

@@ -34,7 +34,7 @@ A full list of argument types are below;
 | Type                        | Rendered as                       | Allowed values
 | (default)                   | <<arg-textbox,Textbox>>           | If a `type:` is not set, and `choices:` is empty, then ascii will be used, and a warning will be logged. It is recommended that you set the type explicitly, rather than relying on defaults.
 | ascii                       | <<arg-textbox,Textbox>>           | a-z (case insensitive), 0-9, but no spaces or punctuation
-| ascii_identifier            | <<arg-textbox,Textbox>>           | Like a DNS name, a-Z (case insensitive), 0-0, `-`, `.`, and `_`. 
+| ascii_identifier            | <<arg-textbox,Textbox>>           | Like a DNS name, a-Z (case insensitive), 0-9, `-`, `.`, and `_`. 
 | ascii_sentence              | <<arg-textbox,Textbox>>           | a-z (case insensitive), 0-9, with spaces, `.` and `,`. 
 | very_dangerous_raw_string   | <<arg-textbox,Textbox>>           | Anything. This is **incredibly dangerous**, as effectively people can type anything they like, including executing additional commands beyond what you specify. Absolutely should not be used unless your OliveTin instance can only be used by people you trust entirely.
 | regex:...                   | <<arg-textbox,Textbox>>           | Version 2024.03.081 and above support custom regex patterns. See <<args-custom-regex,Custom regex arguments>>. 
@@ -98,6 +98,8 @@ image::images/args3.png[]
 
 OliveTin version 2024.02.081 and above support custom regex patterns for argument types. Here is an example to validate against any 3 letter word;
 
+NOTE: The regex pattern should be enclosed in single quotes, otherwise you will probably get a YAML error when starting OliveTin.
+
 [source,yaml]
 .`config.yaml`
 ----
@@ -107,9 +109,12 @@ actions:
     shell: echo "{{ message }}"
     arguments:
       - name: message
-        type: "regex:^\w\w\w$"
+        type: 'regex:^\w\w\w$'
 ----
 
+The site http://regex101.com is a good place to test your regex patterns.
+
+
 
 [#arg-suggestions]
 === Suggestions

modules/ROOT/pages/config.adoc

@@ -55,6 +55,7 @@ All configuration options are covered in the sollution sections
 | `defaultIconForActions` | The default icon to use for actions. | `smile` | Requires Restart | -
 | `defaultIconForDirectories` | The default icon to use for directories. | `directory` | Requires Restart | -
 | `defaultIconForBack` | The default icon to use for back (from directories). | `«` | Requires Restart | -
+| `enableCustomJs` | Enable custom JavaScript. | `false` | Live Reloadable, band refreshing the web browser is required. | <<custom-js,Custom JS>>.
 | `themeName` | The theme to use. | `` | Restart recommended | <<themes,Themes>>.
 |===
 

modules/ROOT/pages/dashboards.adoc

@@ -5,6 +5,8 @@ OliveTin generates a default view of actions which is useful for simple OliveTin
 
 If you want to start organizing OliveTin actions more effectively, then **Dashboards** are for you!
 
+one of the biggest reasons to use Dashboards as opposed to just the "Actions" section, is that dashboards allow you to use <<folders>>, and dashboards really start to get exciting when you start using <<entities,entities>> and displays.
+
 image::images/dashboard.png[]
 
 Example configuration
@@ -21,10 +23,12 @@ actions:
  - title: '{{ server.name }} Wake on Lan'
    shell: 'wol {{ server.name }}'
    timeout: 10
+   entity: server
 
  - title: '{{ server.name }} Power Off'
-   shell: 'ssh root@{{ server.name}} "poweroff"'
+   shell: 'ssh root@{{ server.name }} "poweroff"'
    timeout: 10
+   entity: server
 
 
 # Dashboards are a way of taking actions from the default "actions" view, and
@@ -207,17 +211,50 @@ dashboards:
           - title: 'Stop {{ container.Names }}'
 ----
 
+==== CSS Classes
+
+You can also add CSS classes to the display, which can be useful for styling.
+
+[source,yaml]
+----
+dashboards:
+  - title: My Containers
+    contents:
+      - title: 'Container {{ container.Names.0 }} ({{ container.Image }})'
+        entity: container
+        type: fieldset
+        contents:
+          - type: display
+            cssClass: '{{ container.State }}'
+            title: |
+              {{ container.Status }} <br /><br /><strong>{{ container.State }}</strong>
+          - title: 'Start {{ container.Names.0 }}'
+          - title: 'Stop {{ container.Names.0 }}'
+          - title: 'Remove {{ container.Names.0 }}'
+----
+
+You can then use the following CSS to style the display;
+
+[source,css]
+----
+div.display.running {
+  color: green;
+}
+----
+
 [#output-views]
 === Most recent action output
 
-This is considered an advanced and experimental feature at the moment. 
+This is considered an advanced and experimental feature at the moment.
 
-WARNING: If you execute too frequently (like every 5-10 seconds) OliveTin is prone to crashing. This will be fixed later.
+The `stdout-most-recent-execution` view is a way to display the most recent output of an action on a dashboard. This is useful for actions that are run on a schedule, or actions that are run on startup. This is a picture of what it looks like:
 
-WARNING: If you are running a status command, you should use `execOnStartup` and `execOnCron` to make sure it is ready for when the webui loads, or OliveTin is likely to crash.
+image::images/mre.png[]
 
-----
+To set this up, here is the configuration you need to add to your `config.yaml` file;
 
+[source,yaml]
+----
 actions:
   - title: Get status
     id: status_command
@@ -236,4 +273,6 @@ dashboards:
             title: status_command
 ----
 
-Please discuss on Discord if you need support.
+Note that the output only refreshes with the browser, not when the button is clicked. 
+
+As this is an experimental feature, please look at options for <<support>> if you need help getting it to work.

modules/ROOT/pages/install/index.adoc

@@ -17,6 +17,8 @@ include::linux_alpine.adoc[]
 
 include::linux_arch.adoc[]
 
+include::linux_manjaro.adoc[]
+
 include::container.adoc[]
 
 include::docker_compose.adoc[]

modules/ROOT/pages/install/linux_manjaro.adoc

@@ -0,0 +1,18 @@
+[#install-manjaro]
+=== Manjaro (pamac/AUR)
+
+Please see teh <<install-archbtw>> page for a description of the difference between `olivetin-bin` and `olivetin` in AUR. This page assumes you want to compile from source (`olivetin` package).
+
+[source,bash]
+----
+PATH=$PATH:~/go/bin/
+pamac install buf
+pamac install olivetin
+sudo mkdir -p /etc/OliveTin/custom-webui/themes/
+sudo mkdir -p /etc/OliveTin/entities/
+----
+
+
+include::snippit_post_systemd.adoc[]
+
+

modules/ROOT/pages/integrations/homeassistant.adoc

@@ -42,7 +42,7 @@ From the file editor now in your sidebar, browse the filesystem to the configura
 ----
 rest_command:
   olivetin_sleep_mindstorm:
-    url: http://olivetin.webapps.teratan.lan/api/StartActionByGetAndWait/sleep_server
+    url: http://olivetin.webapps.teratan.lan/api/StartActionByGetAndWait/server_sleep
     method: get
 ----
 

modules/ROOT/pages/reference/reference_themes_for_developers.adoc

@@ -1,10 +1,9 @@
 [#themes-dev]
 === Themes (for theme developers)
 
-include::../snippit_earlydoc.adoc[]
-
 ==== Step by step theme guide
 
+* OliveTin will by default only read theme.css once on startup. If you are intending to change theme.css while OliveTin is running, set `themeCacheDisabled: true` in your config.yaml. This will make OliveTin read theme.css on every request, and is useful for development.
 * Go to https://github.com/OliveTin/theme-template and use this template repository to create your new theme repository on GitHub. 
 * Install OliveTin somewhere, and clone your new repository using `git clone` into your themes directory.
 * Set `themeName: <your-folder>` in your OliveTin config.yaml and restart OliveTin.
@@ -13,6 +12,32 @@ Write beautiful CSS to create your theme as you like it, commit your changes to
 
 Note that OliveTin will load `/theme.css` depending on `themeName:` in your config file. Images and any other assets will be served at `/custom-webui/themes/mytheme/`.
 
+==== Understanding theme URLs
+
+When you create a theme, OliveTin will serve your theme's CSS at `/theme.css` and any other assets at `/custom-webui/themes/mytheme/`. This might be a little strange at first, as your theme.css file wil be in the `/custom-webui/themes/mytheme/` directory, but OliveTin will still serve it at `/theme.css`. Let's explain why this happens;
+
+OliveTin wants to make it easy for your reverse proxy, cache server, or browser, to cache as much content as possible. This means that if OliveTin had to inject a new CSS file into the HTML every time you changed your theme, then your reverse proxy, cache server, or browser would have to re-download the HTML every time you changed your theme. This is not ideal. 
+
+It is possible that OliveTin's initial webUiSettings.json (that is loaded to setup the page), could include the theme name, and then the JavaScript could then add an extra stylesheet to load, but this is slow, and creates a horrible "page flash" effect as the theme is requested.
+
+To make things fast, OliveTin will copy the content of your `/custom-webui/themes/mytheme/theme.css` file into memory when it starts, and then requests for `/theme.css` will load this file. 
+
+What this means for you, is that to get to files like `backgrond.png` from your CSS, you must write your CSS to point to the file in the `/custom-webui/themes/mytheme/` directory;
+
+.Correct example
+```
+body {
+    background-image: url('/custom-webui/themes/mytheme/background.png');
+}
+```
+
+.Incorrect example
+```
+body {
+    background-image: url('/background.png');
+}
+```
+
 ==== How to list your theme on the OliveTin themes page
 
 The OliveTin themes page is here; https://olivetin.app/themes

modules/ROOT/pages/reference/reference_themes_for_users.adoc

@@ -1,17 +1,46 @@
 [#themes]
 === Themes (for users)
 
-include::../snippit_earlydoc.adoc[]
+You can look for themes on the link:http://www.olivetin.app/themes/[OliveTin Theme Site].
 
-Very early version of a theme website: http://www.olivetin.app/themes/
+==== Installing a theme
 
-==== The custom-webui directory
+There are 3 ways to install a theme;
 
-OliveTin will server a directory called `custom-webui` at `http://yourserver:1337/custom-webui/`, this means that all theme content should go into `custom-webui/themes`.
+1. Use the `olivetin-get-theme` command to easily Git clone the theme into your `custom-webui/themes/` directory.
+2. Download the theme .zip and copy it across to your `custom-webui/themes/` directory.
+3. Git Clone the theme into your `custom-webui/themes/` directory.
 
-In the past, OliveTin used to lookup the theme name and send that theme name to your browser so that it could then manually request the theme stylesheet. This approach was slow, it stopped browsers caching, and it caused an awkward "flash" whenever the new theme was loaded. Now, OliveTin internally looks up your theme.css file based on your `themeName`, and will always serve this `theme.css` file at `http://yourServer:1337/theme.css`. If you are not using a custom theme, OliveTin will just serve an empty CSS file.
+==== How to use the `olivetin-get-theme` command
 
-Install Themes into your **custom-webui** directory, which should be in your config directory. If this directory does not exist, you can create it.
+The default OliveTin configuration comes with an action to get new OliveTin themes. If you deleted it from your configuration, you can add it back in by adding the following to your `config.yaml` file;
+
+[source,bash]
+----
+actions:
+  - title: Get OliveTin Theme
+    shell: olivetin-get-theme {{ themeGitRepo }} {{ themeFolderName }}
+    icon: theme
+    arguments:
+      - name: themeGitRepo
+        title: Theme's Git Repository
+        description: Find new themes at https://olivetin.app/themes
+        type: url
+
+      - name: themeFolderName
+        title: Theme's Folder Name
+        type: ascii_identifier
+----
+
+When you are browsing the OliveTin Theme Site, you can click on a theme and see it's Git Repository URL. You can then copy this URL and paste it into the `olivetin-get-theme` command.
+
+==== Where do I find my themes directory?
+
+When OliveTin starts up, it will try to create a directory called `custom-webui/themes/` in your config directory. This directory is where you can put your own custom themes.
+
+OliveTin will then serve this theme directory at `http://yourserver:1337/custom-webui/themes/`, this means that all theme content should go into `/custom-webui/themes/mytheme/`.
+
+Install Themes into your `custom-webui/themes/` directory, which should be in your config directory. If this directory does not exist, you can create it.
 
 [source,yaml]
 ----
@@ -32,7 +61,7 @@ Install Themes into your **custom-webui** directory, which should be in your con
 
 ==== Create your own theme (without any intention of publishing it)
 
-Create a sub-directory under your theme directory (normally /var/www/olivetin/themes) called "mytheme"
+Create a sub-directory under your theme directory (eg `custom-webui/themes/mytheme`);
 
 Set your theme in your config
 
@@ -42,7 +71,7 @@ Set your theme in your config
 themeName: mytheme
 ----
 
-Add your css into /var/www/olivetin/themes/mytheme/theme.css
+Add your css into `custom-webui/themes/mytheme/theme.css`.
 
 Your theme css will be loaded "on top" of the existing stylesheet.
 
@@ -56,10 +85,5 @@ body {
 
 Profit.
 
-==== Create a theme for other people to use
+Check out <<themes-dev>> for more information on how to develop themes.
 
-. Use this GitHub repository as a template to create your own theme repo: https://github.com/OliveTin/theme-template
-. Fork https://github.com/olivetin/themes
-. Create a directory under "content/posts" called something like "mytheme", and populate index.md, and cover.png. 
-. Raise a pull request back to github.com/olivetin/themes/
-. Rejoice!

modules/ROOT/pages/reference/upgrade_notes.adoc

@@ -3,6 +3,14 @@
 
 OliveTin releases are published to GitHub, and the release notes are contained there. This page includes a summary of "Upgrade Notes" for breaking changes between releases.
 
+==== 2024.08.14
+
+===== Navigation change - Subpaths no longer supported
+
+In the past, OliveTin supported subpaths in the URL, for example, `http://yourServer:1337/olivetin/` would load the OliveTin web interface. This was convenient for people who wanted to run OliveTin on a subpath of their domain for some reason, but it actually creates a lot of complexity in the code, and makes it harder to maintain. One particular change that was wanted was to be able to link to specific pages in OliveTin, for example, `http://yourServer:1337/logs` or `http://yourServer:1337/myDashboard/myFolder` - this became incredibly difficult to implement with the subpath support.
+
+Therefore, OliveTin no longer supports subpaths in the URL. If you have been using OliveTin with a subpath, you will need to change your configuration to use a subdomain or a different port.
+
 ==== 2024.04.09
 
 ===== Themes Directory (for theme users)