113 lines
5.5 KiB
Markdown
113 lines
5.5 KiB
Markdown
```text
|
||
[[[ SYNOPSIS ]]]
|
||
|
||
gancioff [options] <configuration file path>
|
||
|
||
[[[ DESCRIPTION ]]]
|
||
|
||
This is GancioFF v0.1, a CLI PHP script that can be used to periodically
|
||
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 path to be passed to it
|
||
as an argument on the command line.
|
||
|
||
[[[ CONFIGURATION FILE ]]]
|
||
|
||
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;
|
||
# 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:
|
||
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; 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:
|
||
max_post_length = 840
|
||
--- End of example configuration file ---
|
||
|
||
[[[ OPTIONS ]]]
|
||
|
||
-h / --help
|
||
Show this help text and exit.
|
||
-p / --do-post <y|n>
|
||
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.
|
||
--
|
||
Treat every possible subsequent argument as non-options. Useful only in the
|
||
very improbable case your config file is named «--help» or as another option.
|
||
|
||
[[[ EXIT VALUES ]]]
|
||
|
||
0: regular run
|
||
1: some error occurred
|
||
99: killed with signal (ctrl+c, etc.)
|
||
|
||
[[[ DISCLAIMER AND LICENSE ]]]
|
||
|
||
This program comes with ABSOLUTELY NO WARRANTY; for details see the source.
|
||
This is free software, and you are welcome to redistribute it under certain
|
||
conditions; see <http://www.gnu.org/licenses/> for details.
|
||
```
|