diff --git a/README.md b/README.md index 43e578d..76e6b4c 100644 --- a/README.md +++ b/README.md @@ -6,26 +6,22 @@ gancioff [options] [[[ DESCRIPTION ]]] This is GancioFF v0.1, a CLI PHP script that can be used to periodically -fetch the RSS feed from a Gancio¹ instance and post its entries – the events – -on the fediverse through a Mastodon account, keeping track of already posted -events in order to post only the new ones. It can be useful, for example, when -the admins of a Gancio instance chose not to use its federation feature -because it would be too heavy on its server: in this case GancioFF is quite -a light alternative, moving from the server running Gancio to the one running -Mastodon the burden of posting each event to all the instances that host at -least one follower, and of sending to them the image a Gancio user can and -almost always do attach to each event, because GancioFF will fetch it only -once and attach it to the corresponding Mastdon post. - GancioFF is meant to be periodically run (every half an hour, or so) by a -cron job or systemd timer or the likes (you can find a sample «gancioff.timer» -and a sample «gancioff.service» in the «systemd» directory). - In order to work, GancioFF needs a configuration file to be passed to it -as an argument on the command line, and the directory containing the specified -configuration file needs to be not only readable, but also writeable by the -user running GancioFF, because that’s where it will save the corresponding -state file that it will use to keep track of already posted events. - -¹ https://gancio.org +fetch the RSS feed from an instance of Gancio (https://gancio.org) and post +its new entries – the events – on the fediverse through a Mastodon account, +keeping track of already posted events’ GUIDs (Global Unique IDentifiers) in +order to post only the new ones on each run. + It can be useful, for example, when the admins of a Gancio instance chose not +to use its federation feature because it would be too heavy on its server: in +this case GancioFF is a quite light alternative, moving from the server +running Gancio to the one running Mastodon the burden of posting each event to +all the instances that host at least one follower, and of sending them the +image a Gancio user can and almost always do attach to each event, because +GancioFF will fetch it only once and attach it to the post for the event. + GancioFF is meant to be periodically run, every half an hour or so, by a cron +job, or systemd timer, or the likes (you can find a sample «gancioff.timer» +and a commented sample «gancioff.service» in the «systemd» directory). + In order to work, GancioFF needs a configuration file to be passed to it as +an argument on the command line. [[[ CONFIGURATION FILE ]]] @@ -34,50 +30,69 @@ The configuration file needs to be like this: --- Example configuration file --- # Lines beginnig with a «#» and empty lines will be ignored -# «feed_url» is required to specify the URL to fetch the RSS feed from, +# «feed_url» is required to specify the URL to fetch the RSS feed from; # for example: feed_url = https://gancio.some.domain/feed/rss?show_recurrent=true # «fedi_hostname» is required to specify the hostname of the Mastodon instance -# you want to post to, for example: +# you want to post to; for example: fedi_hostname = mastodon.another.domain # «fedi_token» is required to specify an «app token» to access the account # that you want to use on the instance defined by «fedi_hostname». On Mastodon # default web frontend you can get such a token under «Preferences» -> # «Development», by clicking on the «New application» button; the new -# application should have at least the «write:statuses» privilege, and when -# you’ll be done setting it up, it will be listed under «Your applications», -# and by clicking on its name you’ll be able to copy «Your access token» and -# paste it here; for example: +# application should have at least the «write:statuses» privilege; when you’ll +# be done setting it up, it will be listed under «Your applications», and by +# clicking on its name you’ll be able to copy «Your access token» and paste it +# here. For example: fedi_token = w6oQ_Ot2LSAm_Q31hrvp0asfl22ip3O4ipYq1kV1ceY +# «state_file_absolute_path» is required to specify the absolute path of the +# state file where GancioFF will store the GUIDs of already posted events and +# the timestamps of the moments when it posted them (on each run, GancioFF +# will check for entries older than one year and discard them, in order to +# avoid the state file to grow too much). For example: +state_file_absolute_path = /var/local/cache/gancio.some.domain.feed.state + +# «posts_language» is required to specify the ISO 639-1 code for the language +# of posts (see https://www.loc.gov/standards/iso639-2/php/code_list.php for +# a complete list); for example: +posts_language = it + +# «posts_visibility» is optional and lets you override the default “public” +# visibility of posts; it can be set to «public» (posts will be visible in the +# «Local» and «Federated» timelines, and any user will be able to boost them), +# «unlisted» (posts will be visible only in the «Home» timeline of followers +# and on the profile of the Mastodon account in use, not in the «Local» or +# «Federated» timelines, but any user will still be able to boost them), +# «private» (AKA «followers only»: posts will be visible only by followers and +# won’t be boostable by anyone), and «direct» (since GancioFF posts won’t ever +# explicitly mention any account, posts with this visibility will be visible +# only from the Mastodon account in use»). For example: +post_visibility = unlisted + # «max_post_length» is optional and lets you override the automatically # detected maximum length that a post can have on the instance specified with # «fedi_hostname»; it can be used for testing purposes or just to keep the -# posts shorter than they would be otherwise. For example: +# posts shorter than they would be otherwise; for example: max_post_length = 840 --- End of example configuration file --- [[[ OPTIONS ]]] -h / --help - Show this help text and exit. --p / --do-post - By default the first run with a given configuration file, i.e. when there’s - no corresponding state file yet, will be a “dry run”, that is: the script - will automatically avoid posting the events it finds in the feed, to avoid - flooding the timelines, but save their IDs in the state filejust as if «--do-not-post» or «-P» were given (see next option description). With «-p» - or «--do-post» it will post them, instead. - Also, if given after «-P» or «--do-not-post», it turns posting back on. --I / --ignore-ids - Ignore events’ IDs, that is: don’t try to load and save already posted - events’ IDs from and to the state file. --P / --do-not-post - Don’t post new events that could be found in the feed. Unless you also - specify «-I» or «--ignore-guids» (see previous option), this will add the IDs - of possible new events to the state file, just as if they were posted, so - those events will never be posted. + Show this help text and exit. +-p / --do-post + Setting this option to «n» («no») will make GancioFF skip posting. Note that + even in this case it will save into the state file the GUIDs of new events + it may find in the feed, so it won’t post them even on the subsequent runs. + You may want to set this option to «n» on the first run on a given feed, i.e. + when the state file doesn’t exist yet and all events in the feed will be + considered new, to avoid flooding the timeline of the given Mastodon + instance. That’s why when the state file doesn’t exist yet, GancioFF refuses + to run unless you explicitly set this option to «n» («no») or «y» («yes»). + When the state file exists, this option defaults to «y» («yes»). -v / --verbose Show some more messages about what the script is doing. -- @@ -88,6 +103,7 @@ max_post_length = 840 0: regular run 1: some error occurred +99: killed with signal (ctrl+c, etc.) [[[ DISCLAIMER AND LICENSE ]]]