Compare commits

...

91 commits
v4.1.5 ... main

Author SHA1 Message Date
Michael
205b0731db
Merge pull request #103 from likeazir/patch-1
Add sharkey as misskey-api-capable
2024-03-04 07:14:45 +00:00
Jonas
bf0ed943ec
add sharkey as misskey-api-capable 2024-03-02 09:56:41 +00:00
Michael
f5c1033fc9
Merge pull request #102 from benyafai/main
🐳 docker-compose
2024-02-28 17:07:35 +00:00
Ben Yafai
ca302bb8db 🐳 docker-compose 2024-02-28 17:05:09 +00:00
Michael
34d07a4fa1
Merge pull request #95 from nanos/update-for-node-20
Update build-container.yaml
2024-02-02 07:25:44 +00:00
Michael
e86863a8ae
Update build-container.yaml 2024-02-02 07:25:08 +00:00
Michael
e4fca0d67e
Merge pull request #94 from nanos/node-16-depracation
Update some actions to use Node 20, now that Node 16 is deprecated
2024-02-02 07:05:45 +00:00
Michael
fe1c69f3ba
Update get_context.yml
Update upload-artifact
2024-01-30 21:10:29 +00:00
Michael
0416cc159a
Update get_context.yml
update correct line
2024-01-26 16:32:54 +00:00
Michael
52d3b8d9e9
Update get_context.yml
Update 2nd ceckout too
2024-01-26 16:31:22 +00:00
Michael
3d8ab95f11
Update get_context.yml
Update action for Node 16 deprecation (#92)
2024-01-26 15:52:45 +00:00
Michael
a8dc809787
Merge pull request #90 from himynameisjonas/patch-1
Build docker image for arm64 as well
2023-12-18 10:19:11 +00:00
Jonas Brusman
099ef7d37a
Build docker image for arm64 as well
Makes it possible to run it on a RaspberryPi
2023-12-16 16:07:36 +01:00
Michael
f69eaed5a6
Merge pull request #88 from zotanmew/main
Add support for Iceshrimp
2023-10-24 13:23:15 +01:00
Laura Hausmann
7be5dfb9b1
Add support for Iceshrimp 2023-10-21 23:41:05 +02:00
nanos
95b644d431 Define nodeLoc (fixes #82) 2023-09-07 08:43:10 +01:00
Michael
bed11e83f1
Merge pull request #80 from lhoBas/fix/k8s-cronjob
examples/k8s-cronjob.yaml: fix job naming
2023-08-31 08:33:12 +01:00
Bas
dafaf93d50
examples/k8s-cronjob.yaml: fix job naming
Fixes validation errors upon applying the k8s manifest:

```
The CronJob "FediFetcher" is invalid:
* metadata.name: Invalid value: "FediFetcher": a lowercase RFC 1123 subdomain must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character (e.g. 'example.com', regex used for validation is '[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*')
* spec.jobTemplate.spec.template.spec.containers[0].name: Invalid value: "FediFetcher": a lowercase RFC 1123 label must consist of lower case alphanumeric characters or '-', and must start and end with an alphanumeric character (e.g. 'my-name',  or '123-abc', regex used for validation is '[a-z0-9]([-a-z0-9]*[a-z0-9])?')
```
2023-08-18 10:49:22 +02:00
nanos
31f475dcdd fixes #79 2023-08-18 08:00:09 +01:00
Michael
a76b52642d
Merge pull request #71 from ToadKing/retry-cleanup
remove redundant code for retrying on HTTP 429
2023-08-14 15:49:14 +01:00
Michael
0744caad6f
Merge pull request #75 from YoannMa/fixLog
fix bug when failing to get user's posts
2023-08-06 22:42:45 +01:00
Yoann MALLEMANCHE
adc0d4ec4e
fix bug when failing to get user's posts 2023-08-06 17:54:34 +02:00
nanos
253c7c4f2b Revert "print current version on startup" (#70)
This reverts commit 213ef57abe.
2023-08-06 09:45:33 +01:00
Toad King
db2dcce2ff remove redundant code for retrying on HTTP 429 2023-08-05 11:44:48 -05:00
nanos
712d88cf0d Update list of supported servers 2023-08-05 09:29:49 +01:00
Michael
ffa6617fff
Merge pull request #66 from ToadKing/misskey
add support for misskey and calckey/firefish
2023-08-05 09:04:08 +01:00
nanos
e207bb6435 document remember-hosts-for-days 2023-08-03 15:23:23 +01:00
nanos
c90a7e42ab fix incorrect rate limit handling for mastodon 2023-08-03 15:21:59 +01:00
nanos
3294a44f76 cache host failures for a shorter time 2023-08-03 15:21:12 +01:00
nanos
174448a2b0 fix bug in writing file to disk 2023-08-03 10:54:14 +01:00
nanos
ae55c96506 improve caching to provide timeout 2023-08-03 10:53:17 +01:00
nanos
5a2b2c2311 Save seen_hosts on disk 2023-08-03 08:01:42 +01:00
nanos
179bb65253 move note regarding access token further up 2023-08-01 16:13:06 +01:00
Toad King
a7611c6e6f remove GoToSocial from Mastodon API support list
https://github.com/superseriousbusiness/gotosocial/issues/2038
2023-07-31 17:10:29 -05:00
Toad King
80ee1387f7 hook up host software lookup to user/post fetching
add depth fetching for misskey posts (works in firefish and foundkey)
2023-07-30 03:19:47 -05:00
Toad King
c92d4e1c2c start on server software detection 2023-07-26 01:14:06 -05:00
Toad King
c169b2ae30 add hacky support for misskey and calckey/firefish 2023-07-25 01:02:41 -05:00
nanos
213ef57abe print current version on startup (#58) 2023-07-03 08:46:20 +01:00
Michael
4dc41ee02c
Merge pull request #61 from Teqed/fix/crash-on-zero-notifications
fix: handle zero notifications
2023-07-03 07:02:16 +01:00
Timothy Quilling
47e8b485a5 fix: handle zero notifications 2023-07-02 23:54:29 -04:00
nanos
93d5b503af Update to indicate Lemmy support 2023-07-01 20:47:25 +01:00
Michael
f7d015004e
Merge pull request #56 from Teqed/feat/lemmy
feat: lemmy
2023-07-01 20:43:58 +01:00
Timothy Quilling
6f7392cfaa feat: fetch root lemmy post 2023-06-30 01:36:56 -04:00
Timothy Quilling
0472fe6e0c fix: match pixelfed profile last 2023-06-30 01:34:30 -04:00
Timothy Quilling
8edfbc030c chore: access context items safely 2023-06-30 01:33:19 -04:00
Timothy Quilling
d212e7a8a3
feat: lemmy communities and users 2023-06-30 00:26:52 -04:00
Timothy Quilling
b04664f9d5 chore: deliminate regex with forward slash 2023-06-30 00:21:17 -04:00
Timothy Quilling
4751d96a1d chore: check none type 2023-06-30 00:18:39 -04:00
Timothy Quilling
4011883ef2 feat: lemmy-2 2023-06-30 00:16:59 -04:00
Timothy Quilling
e290f2c05f chore: use getters 2023-06-30 00:11:33 -04:00
Timothy Quilling
b7ef2be02e chore: refactor get_all_known_context_urls 2023-06-29 01:57:33 -04:00
Timothy Quilling
c1f0e8ac61 feat: lemmy 2023-06-29 00:20:12 -04:00
nanos
535bf1f404 update readme 2023-06-15 11:17:25 +01:00
nanos
12fbd0ed72 check out own fork when running GH action (fixes #52) 2023-06-15 11:12:18 +01:00
nanos
9fec312b38 documentation updates 2023-06-15 09:11:45 +01:00
nanos
9edbee7285 Deal better with it, when someone provides a URL instead of a server name (#50, #45) 2023-06-15 08:00:05 +01:00
Michael
3620b4944b
Merge pull request #51 from nanos/improve-config
Improve config
2023-06-15 07:25:45 +01:00
nanos
8168aa8036 minor fixes 2023-06-14 10:49:15 +01:00
nanos
bf1b73bc04 Improve and unify configuration options (#49) 2023-06-14 10:41:30 +01:00
nanos
46a5be98df Fix bug in providing access token as config where it isn't being recognised as array 2023-06-14 09:51:56 +01:00
nanos
5a3db443cb Allow us to pass configuration options in a json file
Addresses #48
2023-06-09 21:55:09 +01:00
nanos
d4dfa1e315 Wrap URLs in quotes. This fixes #46 2023-06-01 21:35:16 +01:00
Michael
c7e0555394
Update README 2023-04-28 20:57:32 +01:00
Michael
5f6ef2646a
Merge pull request #43 from nanos/dev
support for fetching context to favourites (#42)
2023-04-28 20:49:45 +01:00
nanos
1fffddcb23 support for fetching context to favourites (#42) 2023-04-28 20:40:24 +01:00
nanos
311353348c readme updates 2023-04-21 10:48:39 +01:00
nanos
080c5dfb78 add link 2023-04-11 09:17:59 +01:00
nanos
3ae3be9184 Add a note on supported servers 2023-04-10 16:28:22 +01:00
nanos
8235cda859 support for multiple access tokens 2023-04-10 16:28:09 +01:00
nanos
d0cb212315 fix silly comment 🤦‍♂️ 2023-04-06 09:13:30 +01:00
nanos
bfbffc0773 Fix backfill options [#37] 2023-04-06 08:00:28 +01:00
nanos
b9d82dc073 Fixes missing arguments (#35) 2023-04-05 09:15:24 +01:00
Michael
886a0cecd2
Merge pull request #29 from arachnist/configurable-state-location
make the state location configurable
2023-04-05 07:49:35 +01:00
nanos
12ba458563 lowercase container name (#34) 2023-04-05 07:35:05 +01:00
nanos
a3f2b23022 dont attempt to backfill reblogs, as we cannot 2023-04-04 17:00:35 +01:00
nanos
9f28ba2333 bug fixes 2023-04-03 08:57:31 +01:00
nanos
2b707e7807 some refactoring 2023-04-03 08:36:09 +01:00
Robert Gerus
73a296c310 make the state file configurable 2023-04-01 16:03:43 +02:00
nanos
56039cfdea only request context to a toot, if we know context exists 2023-04-01 08:44:12 +01:00
nanos
f51d19730b put a cap on mentions to backfill during any given executions 2023-03-31 17:23:12 +01:00
nanos
9ea4ba05fb allow us to choose whether to get context when backfilling 2023-03-31 17:22:35 +01:00
nanos
785499ab82 do make sure we also backfill users from reblogs 2023-03-31 10:23:47 +01:00
nanos
a357470328 also backfill post authors 2023-03-31 09:05:51 +01:00
nanos
5f438ee873 backfill any user mentioned in the home timeline 2023-03-31 09:05:43 +01:00
nanos
dc0d94a274 Add Context when adding posts 2023-03-31 09:05:29 +01:00
nanos
0c87cd6727 Allow us to parse Pixelfed URLs
fixes #30
2023-03-31 07:51:18 +01:00
nanos
44f15de367 readme updates 2023-03-28 09:38:48 +01:00
nanos
871cfdeab6 Added a note re .pyw and Windows as suggested in #27 2023-03-28 09:34:56 +01:00
nanos
e40a5447ee Add a sample bash script 2023-03-28 07:04:31 +01:00
nanos
9b7093e478 Allow us to backfill posts from users that are mentioned in notifications 2023-03-28 07:04:03 +01:00
Michael
c5208568b5
Update k8s-cronjob.yaml
Must be lower case
2023-03-27 09:51:41 +01:00
9 changed files with 1047 additions and 239 deletions

View file

@ -9,11 +9,12 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Set up QEMU
uses: docker/setup-qemu-action@v2
uses: docker/setup-qemu-action@v3
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
uses: docker/setup-buildx-action@v3
- name: Login to GHCR
uses: docker/login-action@v2
uses: docker/login-action@v3
if: github.event_name != 'pull_request'
with:
registry: ghcr.io
@ -21,9 +22,10 @@ jobs:
password: ${{ secrets.GITHUB_TOKEN }}
- name: Build and push
id: docker_build
uses: docker/build-push-action@v4
uses: docker/build-push-action@v5
with:
push: true
platforms: linux/amd64,linux/arm64
tags: |
ghcr.io/${{ github.repository_owner }}/fedifetcher:${{ github.ref_name }}
ghcr.io/${{ github.repository_owner }}/fedifetcher:latest

View file

@ -12,20 +12,17 @@ jobs:
environment: mastodon
steps:
- name: Checkout original repository
uses: actions/checkout@v3
uses: actions/checkout@v4
with:
repository: nanos/FediFetcher
fetch-depth: 0
- name: Checkout latest release tag
run: git checkout $(git describe --tags)
- name: Set up Python
uses: actions/setup-python@v4
uses: actions/setup-python@v5
with:
python-version: '3.10'
cache: 'pip' # caching pip dependencies
- run: pip install -r requirements.txt
- name: Download all workflow run artifacts
uses: dawidd6/action-download-artifact@v2
uses: dawidd6/action-download-artifact@v3
with:
name: artifacts
workflow: get_context.yml
@ -33,14 +30,14 @@ jobs:
path: artifacts
- name: Get Directory structure
run: ls -lR
- run: python find_posts.py --lock-hours=0 --access-token=${{ secrets.ACCESS_TOKEN }} --server=${{ vars.MASTODON_SERVER }} --reply-interval-in-hours=${{ vars.REPLY_INTERVAL_IN_HOURS || 0 }} --home-timeline-length=${{ vars.HOME_TIMELINE_LENGTH || 0 }} --max-followings=${{ vars.MAX_FOLLOWINGS || 0 }} --user=${{ vars.USER }} --max-followers=${{ vars.MAX_FOLLOWERS || 0 }} --http-timeout=${{ vars.HTTP_TIMEOUT || 5 }} --max-follow-requests=${{ vars.MAX_FOLLOW_REQUESTS || 0 }} --on-fail=${{ vars.ON_FAIL }} --on-start=${{ vars.ON_START }} --on-done=${{ vars.ON_DONE }} --max-bookmarks=${{ vars.MAX_BOOKMARKS || 0 }}
- run: python find_posts.py --lock-hours=0 --access-token=${{ secrets.ACCESS_TOKEN }} -c="./config.json"
- name: Upload artifacts
uses: actions/upload-artifact@v3
uses: actions/upload-artifact@v4
with:
name: artifacts
path: |
artifacts
- name: Checkout user's forked repository for keeping workflow alive
uses: actions/checkout@v3
uses: actions/checkout@v4
- name: Keep workflow alive
uses: gautamkrishnar/keepalive-workflow@v1

162
README.md
View file

@ -2,109 +2,173 @@
This GitHub repository provides a simple script that can pull missing posts into Mastodon using the Mastodon API. FediFetcher has no further dependencies, and can be run as either a GitHub Action, as a scheduled cron job, or a pre-packaged container. Here is what FediFetcher can do:
1. It can pull missing remote replies to posts that are already on your server into your server. It can
1. It can pull missing remote replies to posts that are already on your server into your server. Specifically, it can
1. fetch missing replies to posts that users on your instance have already replied to,
2. fetch missing replies to the most recent posts in your home timeline,
3. fetch missing replies to your bookmarks.
4. fetch missing replies to your favourites.
2. It can also backfill profiles on your instance. In particular it can
1. fetch missing recent posts from users that you have recently followed,
2. fetch missing recent posts form users that have recently followed you,
3. fetch missing recent posts form users that have recently sent you a follow request.
1. fetch missing posts from users that have recently appeared in your notifications,
1. fetch missing posts from users that you have recently followed,
2. fetch missing posts form users that have recently followed you,
3. fetch missing posts form users that have recently sent you a follow request.
Each part of this script is fully configurable, and you can completely disable parts that you are not interested in.
FediFetcher will store posts it has already pulled in, as well as profiles it has already backfilled on disk, to prevent re-fetching the same info in subsequent executions.
FediFetcher will store posts and profiles it has already pulled in on disk, to prevent re-fetching the same info in subsequent executions.
**Be aware, that this script may run for a *very* long time.** This is particularly true, the first time this script runs, and/or if you enable all parts of this script. You should ensure that you take steps to prevent multiple overlapping executions of this script, as that will lead to unpleasant results.
**Be aware, that this script may run for a *very* long time.** This is particularly true, the first time this script runs, and/or if you enable all parts of this script. You should ensure that you take steps to prevent multiple overlapping executions of this script, as that will lead to unpleasant results. There are detailed instructions for this below.
For detailed information on the how and why, please read the [FediFetcher for Mastodon page](https://blog.thms.uk/fedifetcher?utm_source=github).
## Supported servers
FediFetcher makes use of the Mastodon API. It'll run against any instance implementing this API, and whilst it was built for Mastodon, it's been [confirmed working against Pleroma](https://fed.xnor.in/objects/6bd47928-704a-4cb8-82d6-87471d1b632f) as well.
FediFetcher will pull in posts and profiles from any servers running the following software: Mastodon, Pleroma, Akkoma, Pixelfed, Hometown, Misskey, Firefish (Calckey), Foundkey, and Lemmy.
## Setup
You can run FediFetcher either as a GitHub Action, as a scheduled cron job on your local machine/server, or from a pre-packed container.
### 1) Get the required access token:
Regardless of how you want to run FediFetcher, you must first get an access token:
#### If you are an Admin on your instance
1. In Mastodon go to Preferences > Development > New Application
1. give it a nice name
2. Enable the required scopes for your options. See below for details, but if you want to use all parts of this script, you'll need these scopes: `read:search`, `read:statuses`, `read:follows`, `read:bookmarks`, and `admin:read:accounts`
1. Give it a nice name
2. Enable the required scopes for your options. You could tick `read` and `admin:read:accounts`, or see below for a list of which scopes are required for which options.
3. Save
4. Copy the value of `Your access token`
### 2.1) Configure and run the GitHub Action
#### If you are not an Admin on your Instance
To run FediFetcher as a GitHub Action:
1. Go to [GetAuth for Mastodon](https://getauth.thms.uk?scopes=read&client_name=FediFetcher)
2. Type in your Mastodon instance's domain
3. Copy the token.
### 2) Configure and run FediFetcher
Run FediFetcher as a GitHub Action, a cron job, or a container:
#### To run FediFetcher as a GitHub Action:
1. Fork this repository
2. Add your access token:
1. Go to Settings > Secrets and Variables > Actions
2. Click New Repository Secret
3. Supply the Name `ACCESS_TOKEN` and provide the Token generated above as Secret
3. Provide the required environment variables, to configure your Action:
1. Go to Settings > Environments
2. Click New Environment
3. Provide the name `Mastodon`
4. Add environment variables to configure your action as described below.
3. Create a file called `config.json` with your [configuration options](#configuration-options) in the repository root. **Do NOT include the Access Token in your `config.json`!**
4. Finally go to the Actions tab and enable the action. The action should now automatically run approximately once every 10 min.
Keep in mind that [the schedule event can be delayed during periods of high loads of GitHub Actions workflow runs](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule).
> **Note**
>
> Keep in mind that [the schedule event can be delayed during periods of high loads of GitHub Actions workflow runs](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule).
### 2.2) Run FediFetcher locally as a cron job
#### To run FediFetcher as a cron job:
If you want to, you can of course also run FediFetcher locally as a cron job:
1. To get started, clone this repository.
1. Clone this repository.
2. Install requirements: `pip install -r requirements.txt`
3. Then simply run this script like so: `python find_posts.py --access-token=<TOKEN> --server=<SERVER>` etc. (Read below, or run `python find_posts.py -h` to get a list of all options)
3. Create a `json` file with [your configuration options](#configuration-options). You may wish to store this in the `./artifacts` directory, as that directory is `.gitignore`d
4. Then simply run this script like so: `python find_posts.py -c=./artifacts/config.json`.
When using a cronjob, we are using file based locking to avoid multiple overlapping executions of the script. The timeout period for the lock can be configured using `--lock-hours`.
If desired, all configuration options can be provided as command line flags, instead of through a JSON file. An [example script](./examples/FediFetcher.sh) can be found in the `examples` folder.
If you are running FediFetcher locally, my recommendation is to run it manually once, before turning on the cron job: The first run will be significantly slower than subsequent runs, and that will help you prevent overlapping during that first run.
When using a cronjob, we are using file based locking to avoid multiple overlapping executions of the script. The timeout period for the lock can be configured using `lock-hours`.
### 2.3) Run FediFetcher from a container
> **Note**
>
> If you are running FediFetcher locally, my recommendation is to run it manually once, before turning on the cron job: The first run will be significantly slower than subsequent runs, and that will help you prevent overlapping during that first run.
#### To run FediFetcher from a container:
FediFetcher is also available in a pre-packaged container, [FediFetcher](https://github.com/nanos/FediFetcher/pkgs/container/fedifetcher) - Thank you [@nikdoof](https://github.com/nikdoof).
1. Pull the container from `ghcr.io`, using Docker or your container tool of choice: `docker pull ghcr.io/nanos/FediFetcher:latest`
2. Run the container, passing the command line arguments like running the script directly: `docker run -it ghcr.io/nanos/FediFetcher:latest --access-token=<TOKEN> --server=<SERVER>`
1. Pull the container from `ghcr.io`, using Docker or your container tool of choice: `docker pull ghcr.io/nanos/fedifetcher:latest`
2. Run the container, passing the configurations options as command line arguments: `docker run -it ghcr.io/nanos/fedifetcher:latest --access-token=<TOKEN> --server=<SERVER>`
The same rules for running this as a cron job apply to running the container: don't overlap any executions.
> **Note**
>
> The same rules for running this as a cron job apply to running the container: don't overlap any executions.
Persistent files are stored in `/app/artifacts` within the container, so you may want to map this to a local folder on your system.
An example Kubernetes CronJob for running the container is included in the [`examples`](https://github.com/nanos/FediFetcher/tree/main/examples) folder.
An [example Kubernetes CronJob](./examples/k8s-cronjob.yaml) for running the container is included in the `examples` folder.
An [example Docker Compose Script](./examples/docker-compose.yaml) for running the container periodically is included in the `examples` folder.
### Configuration options
Please see below for a list of configuration options. Use the 'Environment Variable Name' if you are running FediFetcher has a GitHub Action, otherwise use the 'Command line flag'.
FediFetcher has quite a few configuration options, so here is my quick configuration advice, that should probably work for most people:
| Environment Variable Name | Command line flag | Required? | Notes |
|:---------------------------------------------------|:----------------------------------------------------|-----------|:------|
| -- | `--access-token` | Yes | The access token. If using GitHub action, this needs to be provided as a Secret called `ACCESS_TOKEN` |
|`MASTODON_SERVER`|`--server`|Yes|The domain only of your mastodon server (without `https://` prefix) e.g. `mstdn.thms.uk`. |
| `HOME_TIMELINE_LENGTH` | `--home-timeline-length` | No | Provide to fetch remote replies to posts in the API-Key owner's home timeline. Determines how many posts we'll fetch replies for. (An integer number, e.g. `200`)
| `REPLY_INTERVAL_IN_HOURS` | `--reply-interval-in-hours` | No | Provide to fetch remote replies to posts that have received replies from users on your own instance. Determines how far back in time we'll go to find posts that have received replies. (An integer number, e.g. `24`.) Requires an access token with `admin:read:accounts`
| `USER` | `--user` | See Notes | Required together with `MAX_FOLLOWERS` or `MAX_FOLLOWINGS`: The username of the user whose followers or followings you want to backfill (e.g. `michael` for the user `@michael@thms.uk`).
| `MAX_FOLLOWINGS` | `--max-followings` | No | Provide to backfill profiles for your most recent followings. Determines how many of your last followings you want to backfill. (An integer number, e.g. `80`. Ensure you also provide `USER`).
| `MAX_FOLLOWERS` | `--max-followers` | No | Provide to backfill profiles for your most recent followers. Determines how many of your last followers you want to backfill. (An integer number, e.g. `80`. Ensure you also provide `USER`).
| `MAX_FOLLOW_REQUESTS` | `--max-follow-requests` | No | Provide to backfill profiles for the API key owner's most recent pending follow requests. Determines how many of your last follow requests you want to backfill. (An integer number, e.g. `80`.). Requires an access token with `read:follows` scope.
| `MAX_BOOKMARKS` | `--max-bookmarks` | No | Provide to fetch remote replies to any posts you have bookmarked. Determines how many of your bookmarks you want to get replies to. (An integer number, e.g. `80`.). Requires an access token with `read:bookmarks` scope.
| `HTTP_TIMEOUT` | `--http-timeout` | No | The timeout for any HTTP requests to the Mastodon API in seconds. Defaults to `5`.
| -- | `--lock-hours` | No | Determines after how many hours a lock file should be discarded. Not relevant when running the script as GitHub Action, as concurrency is prevented using a different mechanism.
| `ON_START` | `--on-start` | No | Optionally provide a callback URL that will be pinged when processing is starting. A query parameter `rid={uuid}` will automatically be appended to uniquely identify each execution. This can be used to monitor your script using a service such as healthchecks.io.
| `ON_DONE` | `--on-done` | No | Optionally provide a callback URL that will be called when processing is finished. A query parameter `rid={uuid}` will automatically be appended to uniquely identify each execution. This can be used to monitor your script using a service such as healthchecks.io.
| `ON_FAIL` | `--on-fail` | No | Optionally provide a callback URL that will be called when processing has failed. A query parameter `rid={uuid}` will automatically be appended to uniquely identify each execution. This can be used to monitor your script using a service such as healthchecks.io.
> **Warning**
>
> **Do NOT** include your `access-token` in the `config.json` when running FediFetcher as GitHub Action. When running FediFetcher as GitHub Action **ALWAYS** [set the Access Token as an Action Secret](#to-run-fedifetcher-as-a-github-action).
#### Required Access Token Scopes
```json
{
"access-token": "Your access token",
"server": "your.mastodon.server",
"home-timeline-length": 200,
"max-followings": 80,
"from-notifications": 1
}
```
If you configure FediFetcher this way, it'll fetch missing remote replies to the last 200 posts in your home timeline. It'll additionally backfill profiles of the last 80 people you followed, and of every account who appeared in your notifications during the past hour.
#### Advanced Options
Please find the list of all configuration options, including descriptions, below:
Option | Required? | Notes |
|:----------------------------------------------------|-----------|:------|
|`access-token` | Yes | The access token. If using GitHub action, this needs to be provided as a Secret called `ACCESS_TOKEN`. If running as a cron job or a container, you can supply this option as array, to [fetch posts for multiple users](https://blog.thms.uk/2023/04/muli-user-support-for-fedifetcher) on your instance. |
|`server`|Yes|The domain only of your mastodon server (without `https://` prefix) e.g. `mstdn.thms.uk`. |
|`home-timeline-length` | No | Provide to fetch remote replies to posts in the API-Key owner's home timeline. Determines how many posts we'll fetch replies for. Recommended value: `200`.
| `max-bookmarks` | No | Provide to fetch remote replies to any posts you have bookmarked. Determines how many of your bookmarks you want to get replies to. Recommended value: `80`. Requires an access token with `read:bookmarks` scope.
| `max-favourites` | No | Provide to fetch remote replies to any posts you have favourited. Determines how many of your favourites you want to get replies to. Recommended value: `40`. Requires an access token with `read:favourites` scope.
| `max-followings` | No | Provide to backfill profiles for your most recent followings. Determines how many of your last followings you want to backfill. Recommended value: `80`.
| `max-followers` | No | Provide to backfill profiles for your most recent followers. Determines how many of your last followers you want to backfill. Recommended value: `80`.
| `max-follow-requests` | No | Provide to backfill profiles for the API key owner's most recent pending follow requests. Determines how many of your last follow requests you want to backfill. Recommended value: `80`.
| `from-notifications` | No | Provide to backfill profiles of anyone mentioned in your recent notifications. Determines how many hours of notifications you want to look at. Requires an access token with `read:notifications` scope. Recommended value: `1`, unless you run FediFetcher less than once per hour.
| `reply-interval-in-hours` | No | Provide to fetch remote replies to posts that have received replies from users on your own instance. Determines how far back in time we'll go to find posts that have received replies. You must be administrator on your instance to use this option, and this option is not supported on Pleroma / Akkoma and its forks. Recommend value: `0` (disabled). Requires an access token with `admin:read:accounts`.
|`backfill-with-context` | No | Set to `0` to disable fetching remote replies while backfilling profiles. This is enabled by default, but you can disable it, if it's too slow for you.
|`backfill-mentioned-users` | No | Set to `0` to disable backfilling any mentioned users when fetching the home timeline. This is enabled by default, but you can disable it, if it's too slow for you.
| `remember-users-for-hours` | No | How long between back-filling attempts for non-followed accounts? Defaults to `168`, i.e. one week.
| `remember-hosts-for-days` | No | How long should FediFetcher cache host info for? Defaults to `30`.
| `http-timeout` | No | The timeout for any HTTP requests to the Mastodon API in seconds. Defaults to `5`.
| `lock-hours` | No | Determines after how many hours a lock file should be discarded. Not relevant when running the script as GitHub Action, as concurrency is prevented using a different mechanism. Recommended value: `24`.
| `lock-file` | No | Location for the lock file. If not specified, will use `lock.lock` under the state directory. Not relevant when running the script as GitHub Action.
| `state-dir` | No | Directory storing persistent files, and the default location for lock file. Not relevant when running the script as GitHub Action.
| `on-start` | No | Optionally provide a callback URL that will be pinged when processing is starting. A query parameter `rid={uuid}` will automatically be appended to uniquely identify each execution. This can be used to monitor your script using a service such as healthchecks.io.
| `on-done` | No | Optionally provide a callback URL that will be called when processing is finished. A query parameter `rid={uuid}` will automatically be appended to uniquely identify each execution. This can be used to monitor your script using a service such as healthchecks.io.
| `on-fail` | No | Optionally provide a callback URL that will be called when processing has failed. A query parameter `rid={uuid}` will automatically be appended to uniquely identify each execution. This can be used to monitor your script using a service such as healthchecks.io.
### Multi User support
If you wish to [run FediFetcher for multiple users on your instance](https://blog.thms.uk/2023/04/muli-user-support-for-fedifetcher?utm_source=github), you can supply the `access-token` as an array, with different access tokens for different users. That will allow you to fetch replies and/or backfill profiles for multiple users on your account.
This is only supported when running FediFetcher as cron job, or container. Multi-user support is not available when running FediFetcher as GitHub Action.
### Required Access Token Scopes
- For all actions, your access token must include these scopes:
- `read:search`
- `read:statuses`
- If you are supplying `REPLY_INTERVAL_IN_HOURS` / `--reply-interval-in-hours` you must additionally enable this scope:
- `read:accounts`
- If you are supplying `reply-interval-in-hours` you must additionally enable this scope:
- `admin:read:accounts`
- If you are supplying `MAX_FOLLOW_REQUESTS` / `--max-follow-requests` you must additionally enable this scope:
- If you are supplying `max-follow-requests` you must additionally enable this scope:
- `read:follows`
- If you are supplying `MAX_BOOKMARKS` / `--max-bookmarks` you must additionally enable this scope:
- If you are supplying `max-bookmarks` you must additionally enable this scope:
- `read:bookmarks`
- If you are supplying `max-favourites` you must additionally enable this scope:
- `read:favourites`
- If you are supplying `from-notifications` you must additionally enable this scope:
- `read:notifications`
## Acknowledgments

View file

@ -0,0 +1,33 @@
# This script is a sample script that you can schedule
# to run every 10 minutes from your cron job.
# Supply any other arguments, as you see fit.
# In this script, FediFetcher will fetch remote replies for multiple
# users on your instance
# TOKEN1, TOKEN2, and TOKEN3 belong to 3 different users here.
# Sample schedule:
# */10 * * * * /usr/bin/bash /path/to/FediFetcher.sh
###################### IMPORTANT ######################
# #
# YOU SHOULD RUN THIS SCRIPT MANUALLY AT LEAST ONCE #
# WITH YOUR CHOSEN ARGUMENTS, TO AVOID CONCURRENT #
# EXECUTIONS OF FEDIFETCHER! #
# #
###################### IMPORTANT ######################
cd /path/to/FediFetcher
python3 find_posts.py \
--access-token=TOKEN1 \
--access-token=TOKEN2 \
--access-token=TOKEN3 \
--server=your.server.social \
--home-timeline-length=200 \
--max-followings=80 \
--from-notifications=1 \
--lock-hours=1

25
examples/FediFetcher.sh Normal file
View file

@ -0,0 +1,25 @@
# This script is a sample script that you can schedule
# to run every 10 minutes from your cron job.
# Supply any other arguments, as you see fit.
# Sample schedule:
# */10 * * * * /usr/bin/bash /path/to/FediFetcher.sh
###################### IMPORTANT ######################
# #
# YOU SHOULD RUN THIS SCRIPT MANUALLY AT LEAST ONCE #
# WITH YOUR CHOSEN ARGUMENTS, TO AVOID CONCURRENT #
# EXECUTIONS OF FEDIFETCHER! #
# #
###################### IMPORTANT ######################
cd /path/to/FediFetcher
python find_posts.py \
--access-token=TOKEN \
--server=your.server.social \
--home-timeline-length=200 \
--max-followings=80 \
--from-notifications=1 \
--lock-hours=1

View file

@ -0,0 +1,19 @@
name: fedifetcher
services:
fedifetcher:
stdin_open: true
tty: true
image: ghcr.io/nanos/fedifetcher:latest
command: "--access-token=<TOKEN> --server=<SERVER>"
# Persist our data
volumes:
- ./data:/app/artifacts
# Use the `deploy` option to enable `restart_policy`
deploy:
# Don't go above 1 replica to avoid multiple overlapping executions of the script
replicas: 1
restart_policy:
# The `any` condition means even after successful runs, we'll restart the script
condition: any
# Specify how often the script should run - for example; after 1 hour.
delay: 1h

View file

@ -14,7 +14,7 @@ spec:
apiVersion: batch/v1
kind: CronJob
metadata:
name: FediFetcher
name: fedifetcher
spec:
# Run every 2 hours
schedule: "0 */2 * * *"
@ -30,19 +30,17 @@ spec:
persistentVolumeClaim:
claimName: fedifetcher-pvc
containers:
- name: FediFetcher
image: ghcr.io/nanos/FediFetcher:latest
- name: fedifetcher
image: ghcr.io/nanos/fedifetcher:latest
args:
- --server=your.server.social
- --access-token=TOKEN
- --home-timeline-length
- "200"
- --reply-interval-in-hours
- "24"
- --max-followings
- "80"
- --max-followers
- "80"
- --from-notification
- "4"
volumeMounts:
- name: artifacts
mountPath: /app/artifacts

File diff suppressed because it is too large Load diff

View file

@ -2,7 +2,9 @@ certifi==2022.12.7
charset-normalizer==3.0.1
docutils==0.19
idna==3.4
python-dateutil==2.8.2
requests==2.28.2
six==1.16.0
smmap==5.0.0
urllib3==1.26.14
python-dateutil==2.8.2
defusedxml==0.7.1