Services Setup

Services Setup

This guide covers configuring the various external services that agaetr can integrate with. Each service requires specific setup steps and configuration in the agaetr.ini file.

Overview

agaetr supports three categories of services:

1. Output Services - Where your content gets posted (social media, bookmarking, archives)
2. URL Services - Link shortening and archival services
3. Utility Services - Supporting services for content processing

All service configurations go in your $HOME/.config/agaetr/agaetr.ini file in the [DEFAULT] section.

Social Media Platforms

Mastodon (via toot)

Required Tool: toot

Installation:

pipx install toot

Setup:

1. Add your Mastodon account:

   toot login

2. List available accounts to get the account identifier:

   toot auth

3. Configure in agaetr.ini:

   toot = /path/to/toot
   mastodon = username@mastodon.example.com

Enable Service:

ln -s $PWD/out_avail/toot.sh $PWD/out_enabled/toot.sh

Bluesky

Required Tool: bsky

Installation:

1. Download binary from releases page
2. Install according to the project directions

Setup:

1. Login with bsky:

   bsky login

   Note: For self-hosted AT Protocol instances, specify the host before handle and password
2. Configure in agaetr.ini:

   bluesky = /path/to/bsky

Enable Service:

ln -s $PWD/out_avail/bluesky.sh $PWD/out_enabled/bluesky.sh

Pixelfed (via toot)

Required Tool: toot (same as Mastodon)

Setup:

1. Add your Pixelfed account using toot:

   toot login

   (Connect to your Pixelfed instance instead of Mastodon)
2. Note the account identifier from toot auth
3. Configure in agaetr.ini:

   toot = /path/to/toot
   pixelfed = username@pixelfed.example.com

Enable Service:

ln -s $PWD/out_avail/pixelfed.sh $PWD/out_enabled/pixelfed.sh

Note: This sender only posts if an image is retrieved from the source article.

Tumblr

Required Tool: python_tumblr_poster

Installation: Follow the installation instructions for python_tumblr_poster, which includes setting up a Python virtual environment.

Setup:

1. Get Tumblr API credentials by registering an application
2. Configure environment variables and paths in agaetr.ini:

   gotumblr = /path/to/run_tumblr.sh
   textmd = /path/to/text.md
   picgo = /path/to/picgo
   TUMBLR_BLOG_NAME=your_blog_name
   TUMBLR_CONSUMER_KEY=your_consumer_key
   TUMBLR_CONSUMER_SECRET=your_consumer_secret
   TUMBLR_OAUTH_TOKEN=your_oauth_token
   TUMBLR_OAUTH_TOKEN_SECRET=your_oauth_token_secret

Note: For locally-hosted images, you'll need picgo installed.

Enable Service:

ln -s $PWD/out_avail/tumblr.sh $PWD/out_enabled/tumblr.sh

Bookmarking and Read-Later Services

Shaarli

Required Tool: Shaarli-Client

Installation:

pipx install shaarli-client

Setup:

1. Configure shaarli-client according to its documentation
2. Set up the configuration file (usually $XDG_DATA_HOME/shaarli/client.ini)
3. Configure in agaetr.ini:

   shaarli = /path/to/shaarli
   shaarli_configs = config_name

If no configuration is specified, the default config will be used.

Enable Service:

ln -s $PWD/out_avail/shaarli.sh $PWD/out_enabled/shaarli.sh

Wallabag

Required Tool: Wallabag-cli

Installation:

pipx install wallabag-client

Setup:

1. Configure wallabag-cli according to its documentation
2. Configure in agaetr.ini:

   wallabag = /path/to/wallabag

Note: Shorteners and wallabag may not work well together.

Enable Service:

ln -s $PWD/out_avail/wallabag.sh $PWD/out_enabled/wallabag.sh

Matrix

It is intended to work with the maubot-webhook plugin:

Required Tools

• Maubot core: https://github.com/maubot/maubot
• Webhook plugin: https://github.com/jkhsjdhjs/maubot-webhook

Setup

1. Configure Maubot with your Matrix server.
2. Configure in agaetr.ini:

   MATRIXSERVER=https://matrix.example.com
   MAUBOT_STATUS_WEBHOOK_INSTANCE=NameOfInstance

3. Configure the Maubot webhook plugin like so:

   path: /THE_SAME_VALUE_AS_MAUBOT_STATUS_WEBHOOK_INSTANCE
   method: POST
   room: '!ROOMIDENTIFIER_FROM_DEVELOPER_OPTIONS_IN_ROOM_INFORMATION'
   message: |-
        {{ json.title }}  
        {{ json.body }}
    message_format: markdown
    message_type: m.notice
    auth_type:
    auth_token:
    force_json: false
    ignore_empty_messages: false
   

Enable Service:

ln -s $PWD/out_avail/matrix.sh $PWD/out_enabled/matrix.sh

XMPP / Jabber

Required Tool: go-sendxmpp

Installation:

sudo apt install go-sendxmpp

If your distribution does not package it, install the binary according to the upstream project and make sure go-sendxmpp is available in your PATH.

Setup:

1. Choose the XMPP account that will send the message and the conference room to receive it.
2. Configure in agaetr.ini:

   JID=username@xmpp.server.com
   JPW=your_xmpp_password
   JCONFERENCE=roomid@conference.xmpp.server.com

3. Confirm go-sendxmpp is installed:

   command -v go-sendxmpp

Enable Service:

ln -s $PWD/out_avail/xmpp.sh $PWD/out_enabled/xmpp.sh

Note:

• The current sender posts to the conference configured in JCONFERENCE.
• Credentials are currently read directly from agaetr.ini, so treat that file as sensitive.

URL and Archive Services

YOURLS (URL Shortening)

Required: A functioning YOURLS instance

Setup:

1. Get your API key (secret signature token) from the Tools page of your YOURLS admin interface
2. Configure in agaetr.ini:

   yourls_api = your_api_key_here
   yourls_site = https://your-yourls-site.com

Enable Service:

ln -s $PWD/short_avail/yourls.sh $PWD/short_enabled/yourls.sh

Wayback Machine (Internet Archive)

Required: Internet Archive account with S3 API access

Setup:

1. Get your access keys from Internet Archive S3 page
2. Configure in agaetr.ini:

   wayback_access = your_access_key
   wayback_secret = your_secret_key

3. Configure how archived links appear in posts:

   ArchiveLinks = separate

   Options: replace, append, separate (default), ignore

Enable Service:

ln -s $PWD/out_avail/wayback.sh $PWD/out_enabled/wayback.sh

Note:

• Adding an access key automatically enables archiving
• This service frequently times out and can take 1-3 minutes when working
• You can also symlink this as an output service, but archived URLs won't appear in posts

Communication Services

Email

Setup: Configure SMTP settings in agaetr.ini:

smtp_server = your.smtp.server.com
smtp_port = 587
smtp_username = your_username
smtp_password = your_password
email_from = sender@example.com
email_to = recipient1@example.com,recipient2@example.com

Enable Service:

ln -s $PWD/out_avail/email.sh $PWD/out_enabled/email.sh

Note: For locally-hosted images, you'll need picgo installed.

RSS Generation

Required Tool: XMLStarlet

Installation:

sudo apt install xmlstarlet

Setup: Configure paths in agaetr.ini:

rss_output_path = /full/path/to/output.xml
self_link = https://your-site.com/output.xml

Enable Service:

ln -s $PWD/out_avail/rss_gen.sh $PWD/out_enabled/rss_gen.sh

Note: For locally-hosted images, you'll need picgo installed.

Content Capture Services

Screenshot Capture (JPG/PNG)

Required Tool: cutycapt

Installation: Install cutycapt according to your distribution's packages.

Setup: Configure save directory in agaetr.ini:

save_directory = /path/to/save/captures

Enable Services:

# For JPG capture
ln -s $PWD/out_avail/jpg_capture.sh $PWD/out_enabled/jpg_capture.sh

# For PNG capture
ln -s $PWD/out_avail/png_capture.sh $PWD/out_enabled/png_capture.sh

PDF Capture

Required Tool: cutycapt

Setup: Same as screenshot capture above.

Enable Service:

ln -s $PWD/out_avail/pdf_capture.sh $PWD/out_enabled/pdf_capture.sh

Content Management Services

Daily Post Creation

Setup: Configure directory in agaetr.ini:

daily_post = /path/to/daily/posts/directory

This creates markdown files named YYYYMMDD.md with all the day's links.

Enable Service:

ln -s $PWD/out_avail/daily_posts.sh $PWD/out_enabled/daily_posts.sh

Note: For locally-hosted images, you'll need picgo installed.

HTML Save

Setup: Configure save directory in agaetr.ini:

save_directory = /path/to/save/html/files

Enable Service:

ln -s $PWD/out_avail/save_html.sh $PWD/out_enabled/save_html.sh

Special Configuration Notes

Image Hosting for Certain Services

For services that require local image hosting (Tumblr, Daily Posts, RSS, Email), install picgo:

picgo = /path/to/picgo

Multiple Accounts

For services that support multiple accounts (like Mastodon/Pixelfed via toot), you can specify which account to use with the service-specific configuration:

mastodon = account1@mastodon.social
pixelfed = account2@pixelfed.social

Service-Specific Limitations

• Pixelfed: Only sends posts that include images
• Wayback Machine: Often times out; be patient
• Wallabag: May conflict with URL shorteners
• Email: Supports multiple recipients separated by commas
• Capture Services: Require GUI environment for cutycapt

Adding New Services

To add support for a new service:

1. Create a new script in out_avail/ following the pattern of existing scripts
2. The script should check if it's being sourced and define a servicename_send function
3. The function receives standard variables: $title, $description, $link, $imgurl, etc.
4. Add configuration options to agaetr.ini as needed
5. Create a symlink in out_enabled/ when ready to use

See existing scripts in out_avail/ for examples and templates.