Mastodon setup

On a self-hosted PostQueen you register a Mastodon app on one Mastodon server and give PostQueen its client key and secret. Every Mastodon channel on your install then signs in on that server.

Before you start


Server	One Mastodon server, set in `MASTODON_URL`. Left unset, it is `https://mastodon.social`
Variables	`MASTODON_URL`, `MASTODON_CLIENT_ID`, `MASTODON_CLIENT_SECRET`
Redirect URI	`FRONTEND_URL` + `/integrations/social/mastodon`
Scopes	`write:statuses`, `write:media`, `profile`
Server version	Mastodon 4.3 or later, the first version with the `profile` scope
Review	None

One server per install. A Mastodon app exists only on the server you register it on, so accounts on other servers cannot connect to your install. To use another server, such as https://fosstodon.org, register the app there and set MASTODON_URL to it.

Register the app

Web interface
API call

Open Development

Sign in on the server and open its settings. Choose Development in the settings menu, at /settings/applications, then New application.

Fill in the form

Application name: a name for your install, such as PostQueen.
Application website: optional.
Redirect URI: your address, one per line. See the addresses below.
Scopes: tick write:statuses, write:media and profile, and untick everything else.

Save the application.

Copy the key and secret

Open the new application. Copy the Client key and the Client secret. You do not need Your access token.

Send the app to the server’s /api/v1/apps, with your redirect URI and the three scopes:

curl -X POST https://mastodon.social/api/v1/apps \
  -F "client_name=PostQueen" \
  -F "redirect_uris=https://postqueen.example.com/integrations/social/mastodon" \
  -F "scopes=write:statuses write:media profile"

The answer holds the two values you need:

{
  "client_id": "your client id",
  "client_secret": "your client secret"
}

The redirect URI is the one that matches how you run PostQueen:

https://postqueen.example.com/integrations/social/mastodon

http://localhost:4200/integrations/social/mastodon

http://localhost:4007/integrations/social/mastodon

The redirect URI is where the network sends the browser back after someone approves PostQueen. It is your FRONTEND_URL + /integrations/social/ + the network’s identifier, for example https://postqueen.example.com/integrations/social/pinterest. Most networks need exactly one URI, with no trailing slash. Two exceptions: TikTok Business needs the trailing slash (/integrations/social/tiktok-business/), and a Google web client that also serves Google Business Profile lists both /integrations/social/youtube and /integrations/social/gmb. Channel developer apps lists every network’s ending.

Set the variables

Add the server and the two keys to your environment. MASTODON_URL is the server’s address with https:// and no trailing slash:

MASTODON_URL="https://mastodon.social"
MASTODON_CLIENT_ID="your client key"
MASTODON_CLIENT_SECRET="your client secret"

Recreate the app container so it reads the new variables. A plain docker restart or docker compose restart keeps the old container and its old environment. In the folder that holds docker-compose.yaml, recreate only the postqueen service:

docker compose up -d --no-deps --force-recreate postqueen

The database, Redis and Temporal keep running. Avoid docker compose down for a settings change: on a host that runs other Compose services in the same project, it stops them too. Then open PostQueen, go to Channels, choose Add Channel and pick this network. You are sent to its login to authorize PostQueen, and the channel appears in the Channels list once you accept.

The channel is in the Channels list with its avatar and name.

Add Channel does not check whether your variables are set. A missing or misspelled key shows up as a broken authorization page on the network’s side rather than a helpful message in PostQueen, so if the login page itself looks wrong, check the keys before anything else.

Pick Mastodon, sign in on the server, and approve access. PostQueen does not check which scopes were granted, so a missing one shows up later as a failed post.

Troubleshooting

The server says the redirect URI is not valid for this client

The address PostQueen sent is not one of the app’s redirect URIs. It is exactly your FRONTEND_URL followed by /integrations/social/mastodon. Edit the application in Development and add it.

fetch failed when connecting

PostQueen could not reach the server in MASTODON_URL. From inside the PostQueen container, run curl -I against the server’s address and fix DNS or outbound access until it answers. If the logs show Blocked IP, the server’s name resolves to a private address, which PostQueen’s SSRF guard refuses.

Posts with a picture fail with fetch failed, while text posts go out

Before it uploads a picture to Mastodon, PostQueen downloads it from your own media address. When that name resolves to a private address inside the container, which is common behind a home reverse proxy or split DNS, the SSRF guard refuses the download and the logs show Blocked IP. Make the media address resolve to a public address from inside the container. If every account on your install is trusted, you can instead set DISABLE_SSRF_PROTECTION=true, which turns the guard off for every request. Read its entry in the configuration reference first.

The media was still processing when the post was published, please try again

A file in a later thread part was not processed yet. PostQueen waits for the first post’s media, but not for the media of later parts. Schedule the post again, or move the video to the first post.

Start here

Install

Domain and HTTPS

Configure

Channel developer apps

Operate

Develop

Before you start

Register the app

Set the variables

Troubleshooting

​Before you start

​Register the app

​Set the variables

​Troubleshooting

​Related

Before you start

Register the app

Set the variables

Troubleshooting

Related