From f097fac8eaad2aa315bba788bcc836b81ce1334e Mon Sep 17 00:00:00 2001 From: FoxxMD Date: Wed, 22 Mar 2023 11:39:51 -0400 Subject: [PATCH] docs: Add systemd usage and add preview flatpak install instructions --- docs/installation.md | 50 ++++++++++++++++---- docs/service.md | 68 ++++++++++++++++++++++++++++ flatpak/README.md | 14 +++--- flatpak/io.github.multiscrobbler.yml | 17 ------- 4 files changed, 117 insertions(+), 32 deletions(-) create mode 100644 docs/service.md diff --git a/docs/installation.md b/docs/installation.md index 5b37edbc..e0fd5844 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,10 +1,14 @@ # Installation -## Local +# Local + +After installation see [service.md](/docs/service.md) to configure multi-scrobbler to run automatically in the background. + +## Nodejs Clone this repository somewhere and then install from the working directory -```bash +```shell git clone https://github.com/FoxxMD/multi-scrobbler.git . cd multi-scrobbler nvm use # optional, to set correct Node version @@ -13,23 +17,51 @@ npm build npm start ``` -### Local Usage Examples +### Usage Examples * The web UI is served on port `9078`. This can be modified using the `PORT` environmental variable. #### Using [file-based](/docs/configuration.md#file-based-configuration) configuration -```bash +```shell npm start ``` #### Using [env-based](/docs/configuration.md#env-based-configuration) configuration -```bash +```shell SPOTIFY_CLIENT_ID=yourId SPOTIFY_CLIENT_SECRET=yourSecret MALOJA_URL="http://domain.tld" node src/index.js ``` -## [Docker](https://hub.docker.com/r/foxxmd/multi-scrobbler) +## Flatpak + +**(Coming soon!)** + +You must have [Flatpak](https://flatpak.org/) installed on your system. + +```shell +flatpak install flathub io.github.multiscrobbler +``` + +### Usage Examples + +#### Using [file-based](/docs/configuration.md#file-based-configuration) configuration + +The config directory for multi-scrobbler as a flatpak can be found under `/home/YourUser/.var/app/io.githubmultiscrobbler/config` + +```shell +flatpak run io.github.multiscrobbler +``` + +#### Using [env-based](/docs/configuration.md#env-based-configuration) configuration + +There are a few [options for running flatpak applications with temporary or permanent environmental variables.](https://ardasevinc.dev/launch-flatpak-apps-with-custom-args-and-environment-variables) + +```shell +flatpak run --env=SPOTIFY_CLIENT_ID=yourId --envSPOTIFY_CLIENT_SECRET=yourSecret --env=MALOJA_URL="http://domain.tld" io.github.multiscrobbler +``` + +# [Docker](https://hub.docker.com/r/foxxmd/multi-scrobbler) Cross-platform images are built for x86 (Intel/AMD) and ARM (IE Raspberry Pi) @@ -65,15 +97,15 @@ To get the UID and GID for the current user run these commands from a terminal: * `id -u` -- prints UID * `id -g` -- prints GID -### Docker Usage Examples +## Docker Usage Examples -#### Using [env-based](/docs/configuration.md#env-based-configuration) configuration +### Using [env-based](/docs/configuration.md#env-based-configuration) configuration ```bash docker run -e "SPOTIFY_CLIENT_ID=yourId" -e "SPOTIFY_CLIENT_SECRET=yourSecret" -e "MALOJA_URL=http://domain.tld" -e "MALOJA_API_KEY=1234" -e "PUID=1000" -e "PGID=1000" -p 9078:9078 -v /path/on/host/config:/config foxxmd/multi-scrobbler ``` -#### Using [file-based](/docs/configuration.md#file-based-configuration) configuration +### Using [file-based](/docs/configuration.md#file-based-configuration) configuration ```bash docker run -e "PUID=1000" -e "PGID=1000" -p 9078:9078 -v /path/on/host/config:/config foxxmd/multi-scrobbler diff --git a/docs/service.md b/docs/service.md new file mode 100644 index 00000000..ca185d7a --- /dev/null +++ b/docs/service.md @@ -0,0 +1,68 @@ +If you have multi-scrobbler installed [locally](/docs/installation.md#local) you can enable it to run as a background service when you login. + +Before running as a service you should run it at least once in the foreground to ensure it can start up correctly! + +# [Systemd](https://systemd.io/) + +Systemd is system and service manager that is used by [most popular linux distros](https://en.wikipedia.org/wiki/Systemd#Adoption) including [Ubuntu](https://wiki.ubuntu.com/SystemdForUpstartUsers), [Fedora](https://docs.fedoraproject.org/en-US/quick-docs/understanding-and-administering-systemd/), Pop!_OS, [Debian](https://wiki.debian.org/systemd), and [Arch](https://wiki.archlinux.org/title/systemd). + +This setup will create a [user service](https://wiki.archlinux.org/title/systemd/User) that runs on login. + +## Create A Unit File + +Create a new service file for multi-scrobbler under your HOME config: + +```console +mkdir -p ~/.config/systemd/user +touch ~/.config/systemd/user/multi-scrobbler.service +``` + +In a text editor add contents below to the file you created, `multi-scrobbler.service`: + +```ini +[Unit] +Description=multi-scrobbler +After=network.target + +[Service] +Type=simple +ExecStart=flatpak run io.github.multiscrobbler +Restart=no + +[Install] +WantedBy=default.target +``` + +The above assumes you [installed multi-scrobbler using flatpak](/docs/installation.md#flatpak) + +### Node.js Installs + +If you are running multi-scrobbler directly with [nodejs from a clone repository directory](/docs/installation.md#nodejs) you should modify the `[Service]`: + +```ini +[Service] +Type=simple +WorkingDirectory=/path/to/multi-scrobbler/directory +ExecStart=node src/index.js +Restart=no +``` + +## Start the Service + +Save the file then run: + +```console +systemctl daemon-reload +systemctl --user enable multi-scrobbler.service +systemctl --user start multi-scrobbler.service +``` + +This will + +* scan for new services and pickup our multi-scrobbler user service +* enable the service to run at login automatically +* start the service now + +# Other Service Methods + +Open a PR if you would like to document setting up multi-scrobbler for other service managers! diff --git a/flatpak/README.md b/flatpak/README.md index 1ecadff6..9e58b1b5 100644 --- a/flatpak/README.md +++ b/flatpak/README.md @@ -12,13 +12,11 @@ Install [flatpak-builder](https://docs.flatpak.org/en/latest/first-build.html#bu Requires python 3.7+, [pip](https://pip.pypa.io/en/stable/)/[pipx](https://pypa.github.io/pipx/) -## - -# 1. Update Project source +# 2. Update Project source Set the `branch` `tag` or `commit` to use for MS in the `git` source in [`io.github.multiscrobbler.yml`](/flatpak/io.github.multiscrobbler.yml) -# 2. Use `flatpak-node-generator` to generate sources +# 3. Use `flatpak-node-generator` to generate sources First, [make sure `node_modules` is deleted or empty.](https://github.com/flatpak/flatpak-builder-tools/issues/354#issuecomment-1478518442) @@ -30,8 +28,12 @@ flatpak-node-generator npm package-lock.json Move `generated-sources.json` into [`/flatpak`](/flatpak) -# 3. Build flatpak +# 4. Build flatpak From MS project root: -flatpak-builder --repo=/tmp/multi-scrobbler-repo /tmp/multi-scrobbler-build flatpak/io.github.multiscrobbler.yml --force-clean +```console +cd flatpak +flatpak-builder --repo=/home/yourUser/multi-scrobbler-repo /home/yourUser/multi-scrobbler-build io.github.multiscrobbler.yml --force-clean +``` +Add `--install --user` to have the app installed immediately. diff --git a/flatpak/io.github.multiscrobbler.yml b/flatpak/io.github.multiscrobbler.yml index 096af0d5..bda746ce 100644 --- a/flatpak/io.github.multiscrobbler.yml +++ b/flatpak/io.github.multiscrobbler.yml @@ -102,20 +102,3 @@ modules: # - type: file # path: io.github.multiscrobbler.metainfo.xml - generated-sources.json - -# https://docs.flatpak.org/en/latest/electron.html -# generated-sources from flatpak-node-generator not working? may be due to git source for winston -# TODO systemd - -# potential references -# https://github.com/flathub/com.sindresorhus.Caprine/blob/master/com.sindresorhus.Caprine.yaml -# https://github.com/flathub/com.github.rssguard/blob/master/com.github.rssguard.yaml -# https://github.com/Lunarequest/moderndeck-flatpak/blob/mistress/com.dangeredwolf.ModernDeck.yaml - -#permission -# https://github.com/flathub/io.mpv.Mpv/blob/master/io.mpv.Mpv.yml#LL9 - - -# flatpak-node-generator yarn yarn.lock -# flatpak-builder ~/flatms io.github.multiscrobbler.yml --force-clean --install --user -# flatpak run io.github.foxxmd.multiscrobbler