tootapalooza

Python program to fill a mastodon timeline with randomized toots. If you want to see what this creates, have a look at the local timeline on always.grumpy.world.

The idea is to generate some somewhat realistic looking users, posts, interactions, etc. This will help fill up a local timeline and provide test data and a playground in which to try new features. I built this because I want to test a few functions that would look at the raw, underlying database on a mastodon instance. But I need to get some data into that database so that I can see what it looks like.

Setting up a Dev environment

You need:

1. Administrator access to a Mastodon server. Part of this runs the admin CLI tool.
2. Python 3.9 or later

1. Python prep

1. Check out the code.
2. cd to the repository.
3. Build it and install it in your working environment.
   1. python3 -m venv .venv
   2. . .venv/bin/activate
   3. pip install -r requirements.txt
   4. Assuming your current working directory is the root of this repository, install into your build environment with pip install -e .
4. Copy the example.env file to a file named .env in the root of this repo.
5. Edit that .env file to contain all the secrets!

2. Initialise your Mastodon app

This is a one-time thing you do ever. First time you go to run the bot in a new environment where it hasn't run before.

1. Find tootapalooza/__init__.py and edit it
2. Edit the lines to uncomment them and change any values you need to (like app name and server)
3. Run it one time (e.g., python __init__.py). It should just exit, creating the file.
4. Edit the file and comment the lines out again. You just do that once.

3. Getting your fleet of users to run

Follow the instructions for unning the server-util make-users.py. You'll copy that onto your mastodon server, run it once to generate a users.toml file that contains plaintext user names and passwords for your test users, and then copy that file to where you want it to run.

You do that just once.

Then copy the users.toml file to the location where you have checked out tootapalooza.

Running

Install the tootapalooza command into your path so you can invoke it. Run pip install -e .

You need to run this in a location that can make API calls to your mastodon instance. I say it this way because you might have a load balancer, a private network, etc. so that running this ON the mastodon server itself isn't desirable. There is no reason to run this directly on the mastodon server. You can, but there's no compelling reason to do that. It makes API calls over the public Internet.

Assuming everything is up to date, all your files initialised with correct values, you can just run tootapalooza --once users.toml. Every user in your users.toml file will pick a random action and do one random action.

Typical usage

For now, the only thing to do that makes sense is to run it with the --once flag. We will turn it into a daemon soon.

tootapalooza --once users.toml

More info

If you want to see what it does, just add the -d or --debug flag to it.

tootapalooza --once --debug users.toml 

Dry Run

If you give the -n or --dry-run flag, it will still login as various users. But it will not make any changes. For example, it will read the timelines, or it will pick a post that it wants to reply to. But it will not post the reply, and it won't update the read markers on the public timeline.

tootapalooza --dry-run --once --debug users.toml 

Weights and random actions

If you look in the random_interactions() method, you'll see a table of weights. (Example shown below). Those weights are fed into Python's random.choices() function and that's how it picks the actions to take. In the example below, the weights sum to 33. unfollow_random() has a weight of 1, so it has a 1 in 33 (3%) chance of happening. Whereas reply_random_local has a weight of 4, so it has a 4 in 33 (12%) chance of happening. Adjust the weights to get the blend of traffic you want. If you don't want an action to happen at all, set its weight to 0.

interactions = {
    self.reply_random_local:      4,
    self.reply_random_home:       4,
    self.reply_random_public:     4,
    self.follow_random_local:     2,
    self.unfollow_random:         1,
    self.toot_plain_public:       1,
    self.toot_tagged_public:      4,
    self.toot_plain_unlisted:     1,
    self.favourite_random_local:  2,
    self.favourite_random_home:   2,
    self.favourite_random_public: 2,
    self.boost_random_local:      2,
    self.boost_random_home:       2,
    self.boost_random_public:     2,
    self.report_random_local:     0
}

Future plans

I intend to make this a multi-threaded daemom that will sleep a little bit, wake up and do a few random actions, go back to sleep, etc. One thread per user, with a bit of randomness on the sleep times. It will just run in the background, generating test data slowly over time.