141 lines
7.2 KiB
Markdown
141 lines
7.2 KiB
Markdown
```text
|
||
[[[ SYNOPSIS ]]]
|
||
|
||
gancioff [options] <configuration file path>
|
||
|
||
[[[ DESCRIPTION ]]]
|
||
|
||
This is GancioFF v0.4, 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:media» and «write:statuses»
|
||
# privileges; 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
|
||
|
||
# «always_link_gancio_post» is optional and if unspecified it defaults to
|
||
# «false», which means that GancioFF adds to the Mastodon post a link to the
|
||
# original Gancio post only if the latter is too long to fit into the first
|
||
# (i.e. into the Mastodon instance “max post length”, or into the
|
||
# «max_post_length» specified in this configuration file - see above); this
|
||
# way, GancioFF reduces the burden on the Gancio instance that is due to the
|
||
# requests that it gets from every Mastodon instance where a Mastodon post
|
||
# with a link to the original Gancio post will end up, in order for each of
|
||
# them to generate a “link preview”; such burden gets reduced in different
|
||
# measures depending on the average length of a post on the Gancio instance
|
||
# and on the “max post length” on the Mastodon instance that GancioFF is using
|
||
# to post (or on the «max_post_length» explicitly specified in this file).
|
||
# If set to «true», GancioFF will instead always add a link to the original
|
||
# Gancio post.
|
||
always_link_gancio_post = true
|
||
--- End of example configuration file ---
|
||
|
||
[[[ OPTIONS ]]]
|
||
|
||
-h / --help
|
||
Show this help text and exit.
|
||
-p / --do-post <y|n>
|
||
When a state file already exists, this option defaults to «y» («yes»), which
|
||
means that GancioFF will try to post all the new events it may find in the
|
||
feed; if set to «n» («no»), GancioFF will not try to post them, but it will
|
||
save their GUIDs into the state file nonetheless, so they won’t be posted
|
||
again on subsequent runs.
|
||
This is mainly useful on GancioFF’s first run on a given feed, i.e. when
|
||
the state file specified in the configuration file doesn’t exist yet and thus
|
||
all the events in the feed will be considered “new”: in this case, GancioFF
|
||
refuses to run unless you explicitly set this option to «y» or «n»: this is a
|
||
way to prevent you from unintentionally flooding your Mastodon instance with
|
||
all the events in the feed.
|
||
When “test mode” is active (see the next option description), setting this
|
||
option has no effect.
|
||
-t / --test
|
||
Do a test: GancioFF will try as always to read the configuration file, fetch
|
||
the defined Mastodon instance’s info, load the state file and fetch the feed,
|
||
but it will post only the first event it may find there, with a visibility of
|
||
«direct», even if according to the state file it has already been posted, and
|
||
won’t update the state file.
|
||
This option also activates “verbose mode” (see below).
|
||
-v / --verbose
|
||
When this option is not set GancioFF prints only warning and error messages;
|
||
when it is set it also prints informational messages about what it’s 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.
|
||
```
|