143 lines
7.3 KiB
Markdown
143 lines
7.3 KiB
Markdown
```text
|
||
[[[ SYNOPSIS ]]]
|
||
|
||
gancioff [options] <configuration file path>
|
||
|
||
[[[ DESCRIPTION ]]]
|
||
|
||
This is GancioFF v0.4.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 announcements – on the fediverse through a
|
||
Mastodon account, recording into a state file a reference to each already
|
||
posted announcement in order to post only new or changed 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 fact, GancioFF is a light alternative to federating the Gancio instance,
|
||
moving from its server to the one running Mastodon the burden of posting each
|
||
announcement to each fediverse instance hosting at least one follower, and of
|
||
sending them the image a Gancio user can attach to each announcement, because
|
||
GancioFF will fetch it only once and attach it to the Mastodon post; moreover,
|
||
by default, if an announcement on the Gancio instance fits into a Mastodon
|
||
post GancioFF doesn’t place a link to the original announcement into the post,
|
||
thus further reducing the burden due to the requests the Gancio instance gets
|
||
from every Mastodon instance trying to generate a “link preview”.
|
||
GancioFF is meant to be run periodically, 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 references to already posted
|
||
# announcements (on every run, GancioFF will check this file for entries older
|
||
# than one year and discard them, 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, which may be good for testing).
|
||
# 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 maximum post length allowed by the Mastodon instance, or into
|
||
# the «max_post_length» specified in this configuration file - see above);
|
||
# this further reduces the burden on the Gancio instance (see the second
|
||
# paragraph of the «Description» section).
|
||
# If set to «true», GancioFF will instead always add a link to the original
|
||
# Gancio announcement.
|
||
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 or changed announcements it
|
||
may find in the feed; if set to «n» («no»), GancioFF will not try to post
|
||
them, but it will still record a reference to each of them into the state
|
||
file, so they won’t be posted again on subsequent runs (unless they were
|
||
changed in the meantime).
|
||
This option 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 announcements 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’s «Local» timeline, and possibly your followers’ «Home» timelines,
|
||
with all the announcements 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 of the announcements 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.
|
||
```
|