Provide example config

[davispuh]

Provide example config so it's a lot easier to edit it when you want to change a lot of options.

[mgdigital]

Thanks @davispuh - my thoughts on this:

The available configuration parameters, and their default values, are likely to be in regular flux, especially as we're in alpha at the moment. Users would be advised (at least for the time being) to allow the default values as defined in code to apply - and only to specify config values they need to override - rather than hardcoding the current defaults in a separate file - because these defaults are likely to change from version to version which might cause issues when upgrading.

For the majority of users right now the Postgres and Redis connection details, and the TMDB API key are the only parameters they're likely to need to touch.

It is the intention to provide some sort of admin/configuration panel to make this all more user-friendly but I can't yet say when this will be available.

I wouldn't rule out having a config file generation tool that makes use of the config specifications that are already defined in the code, but having a separate static file like this just means that any change now has to be made in 2 places instead of 1...

[davispuh]

YAML supports comments so values you think are most likely to change can be commented out and thus still supporting this use case of example config while having whatever defaults you want. So users would uncomment those only if they want to change defaults.

It is the intention to provide some sort of admin/configuration panel to make this all more user-friendly but I can't yet say when this will be available.

I don't see any need for this. IMO YAML config file is already user friendly.

I wouldn't rule out having a config file generation tool that makes use of the config specifications that are already defined in the code, but having a separate static file like this just means that any change now has to be made in 2 places instead of 1...

That would be useful indeed so when package is built it could generate latest config file.

[mgdigital]

See here for an example of how to access the configs as defined in code, which could be used for dynamically generating a config file: https://github.com/bitmagnet-io/bitmagnet/blob/main/internal/boilerplate/app/cmd/config/command.go

I see you've also added this package in the Arch repo: https://aur.archlinux.org/packages/bitmagnet-git - I'm not very familiar with Arch but is there a way to link the files you've added under "Sources" to this repo instead of having them defined separately there as otherwise they will inevitably get out-of-date?

[davispuh]

is there a way to link the files you've added under "Sources" to this repo instead of having them defined separately there as otherwise they will inevitably get out-of-date?

Yes by pulling them directly from repo hence #124 #125 so that I could have them taken from here.

[mgdigital]

I don't think a config file needs to be part of the Arch package. Any values that need configuring will likely be bespoke to the user, so what I'd suggest instead is I'll add a CLI command allowing users to set values that will then be written to a file that would be created if it doesn't already exist, something like:

bitmagnet config set tmdb.api_key abc123

If you're happy with this we can open an issue for an enhancement?

[davispuh]

That would work but it adds unnecessary complexity, is not as easily discoverable and 99% of software is configurable thru config files in /etc so I don't see why bitmagnet has to be so special...

You can literally just do

# vim /etc/bitmagnet/config.yml

and edit config according to your needs, or even faster

# sed -i 's|api_key:|api_key: MY_KEY|' /etc/bitmagnet/config.yml

The advantage of simple file based config is that all users are already familiar with that and it allows to see all possible configuration options. Each option then can be looked up on documentation to see what exactly it adjusts etc.

[davispuh]

Also the way how I currently implemented it in AUR package is that it doesn't need any write access to filesystem at all and configuration can't be changed by daemon itself but only root can change config.

# ls -la /etc/bitmagnet/config.yml
-rw-r----- 1 root bitmagnet 1489 jan 28 16:24 /etc/bitmagnet/config.yml

[mgdigital]

99% of software is configurable thru config files in /etc so I don't see why bitmagnet has to be so special...

Bitmagnet adheres to the XDG Base Directory Specification, so the config file should live in $HOME/.config/bitmagnet, not in /etc: https://wiki.archlinux.org/title/XDG_Base_Directory

configuration can't be changed by daemon itself but only root can change config

The config file should be owned by the same user that's running Bitmagnet, which shouldn't be root; the systemd file would likewise live in $HOME/.config/systemd/user: https://wiki.archlinux.org/title/Systemd/User#Basic_setup

the way how I currently implemented it in AUR package is that it doesn't need any write access to filesystem at all

This would prevent some telemetry features being used, which require access to the fs for log aggregation (see https://bitmagnet.io/internals-development/observability-telemetry.html). Future features may also require fs access which would be under $XDG_DATA_HOME/bitmagnet.

As explained above, it's a bad idea for a lot of hardcoded defaults to be written to a standalone config file when the config schema and default values are going to be in flux with each new alpha version. Better to let Bitmagnet resolve the defaults and only set the few values that need overriding and will be kept stable (Postgres, Redis and API keys).

I still think a CLI is the most user-friendly way to do this, and would allow for validation and other conveniences; users can always edit config files manually if they wish, and can refer to the docs available on the website to answer any questions about the format or file location (documented at https://bitmagnet.io/setup/configuration.html#configuration-precedence).

[davispuh]

99% of software is configurable thru config files in /etc so I don't see why bitmagnet has to be so special...

Bitmagnet adheres to the XDG Base Directory Specification, so the config file should live in $HOME/.config/bitmagnet, not in /etc: https://wiki.archlinux.org/title/XDG_Base_Directory

That matters only for desktop applications, but bitmagnet in this case is system daemon so /etc is correct.

configuration can't be changed by daemon itself but only root can change config

The config file should be owned by the same user that's running Bitmagnet, which shouldn't be root; the systemd file would likewise live in $HOME/.config/systemd/user: https://wiki.archlinux.org/title/Systemd/User#Basic_setup

It doesn't have to be, there are few benefits when it can't modify it and also running it as your own user is quite bad idea. So no it being system service is a lot better.

the way how I currently implemented it in AUR package is that it doesn't need any write access to filesystem at all

This would prevent some telemetry features being used, which require access to the fs for log aggregation (see https://bitmagnet.io/internals-development/observability-telemetry.html). Future features may also require fs access which would be under $XDG_DATA_HOME/bitmagnet.

That's only partially true. I think observability can be implemented without Bitmagnet needing to write anything on disk. Anyway if it turns out it is needed it can be very easily changed in future by adding to bitmagnet.service file

# For logs
ReadWritePaths=/var/log/bitmagnet

# If there is need for some additional state
ReadWritePaths=/var/lib/bitmagnet

Also I actually don't see any need for file_rotator at all because there already exists logrotate tool and systemd is collecting logs from stdout/stderr. Also I plan to integrate with https://signoz.io/ but haven't looked into it yet.

As explained above, it's a bad idea for a lot of hardcoded defaults to be written to a standalone config file when the config schema and default values are going to be in flux with each new alpha version. Better to let Bitmagnet resolve the defaults and only set the few values that need overriding and will be kept stable (Postgres, Redis and API keys).

I don't disagree with this, I updated PR and package with commented out fields most likely to change so users will need to update those only if they explicit want.

[mgdigital]

I'm sorry but this PR isn't making progress towards something I can merge. Once the config schema is more stable I'll think about providing a full example config file. Such a file will likely be:

1. fully commented out allowing the application to resolve its own defaults,
2. annotated with comments so users understand what they're configuring, and
3. auto-generated by application code to reduce duplication and the maintenance burden.

In due course there may well be an official package published through something like Flathub that will avoid having to maintain separate packages for each distro, and with its primary focus being as a userspace application - similar to a BitTorrent client - rather than as a system-wide service.

It seems there are several differences in our preferred approach here and you are free to build and maintain an unofficial Arch package as you see fit - I'm happy to assist where I can and will always aim where feasble to allow users to configure it as they choose, while focusing on a core and default recommended/supported configuration.