> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postqueen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mastodon setup

> Register the Mastodon application and give PostQueen its keys

On your own instance you register the Mastodon client yourself and put its keys in your environment.

Mastodon client registration does not happen in a web interface. You talk to the API directly, and `curl` is the shortest way to register a new client:

Optionally check that you have `jq` installed on your system. You can normally install this with brew, apt-get, yum or chocolatey. If you do not have `jq` installed, you can remove it from the command below.

<Info>
  The examples on this page use `https://mastodon.social` as the default Mastodon instance. If you are setting up PostQueen to connect to a different self-hosted Mastodon instance (e.g., `https://fosstodon.org`), you must replace `https://mastodon.social` with your instance's URL in the `curl` command below. You will also need to ensure the `MASTODON_URL` environment variable in your application's `.env` file (or equivalent configuration for Docker, etc.) is set to your custom instance's URL.
</Info>

<Steps>
  <Step title="Register your client">
    <Snippet file="oauth2redirect.mdx" />

    **Your Mastodon OAuth2 Redirect URI:**

    * Production: `https://postqueen.example.com/integrations/social/mastodon`
    * Local development: `http://localhost:4200/integrations/social/mastodon`
    * Docker: `http://localhost:4007/integrations/social/mastodon`

    Run the following curl command in a terminal to get the Mastodon client id and client secret.

    ```bash theme={"system"}
    curl -X POST -sS https://mastodon.social/api/v1/apps -F "client_name=YourAppName" -F "redirect_uris=http://localhost:4200/integrations/social/mastodon" -F "scopes=write:statuses write:media profile" | jq
    ```

    This will give you output that looks something like this;

    ```json theme={"system"}
    {
      "id": "1234567890",
      "redirect_uris": [
        "http://localhost:4200/integrations/social/mastodon"
      ],
      ...
      "client_id": "your_client_id",
      "client_secret": "your_client_secret"
    }
    ```
  </Step>

  <Step title="Add credentials to your environment">
    Make a note of your `client_id` and `client_secret` and add them to your `.env` file.

    ```env theme={"system"}
    MASTODON_CLIENT_ID="shown in the output from the above command"
    MASTODON_CLIENT_SECRET="shown in the output from the above command"
    MASTODON_URL="https://mastodon.social" # Change this if connecting to a different instance
    ```
  </Step>

  <Step title="Start PostQueen">
    Stop PostQueen if it is running, and then start it using the .env file with the Mastodon details. Click through the new channel setup and you should be asked to login on Mastodon.
  </Step>
</Steps>

<Check>
  The channel is in the left sidebar with its avatar and name. That is the whole confirmation: if it is in the list, she can post to it.
</Check>

## Troubleshooting

### "Failed to fetch" / "fetch failed" when connecting

The PostQueen backend needs network access to reach your Mastodon instance. If the connect call fails at this stage, the backend container could not resolve or reach the `MASTODON_URL` host.

**Fix**

1. From inside the backend container, run `curl -I https://mastodon.example.com/`. If that fails, fix DNS/egress before retrying.
2. If you are behind a corporate proxy, set `HTTPS_PROXY` on the backend.
3. Confirm `MASTODON_URL` exactly matches your instance (protocol included, no trailing slash issues).

## Next steps

<CardGroup cols={2}>
  <Card title="What she can post to Mastodon" icon="https://mintcdn.com/forceplay/LL5FipRv-7nhg1To/images/channels/mastodon.svg?fit=max&auto=format&n=LL5FipRv-7nhg1To&q=85&s=cc7df05ba8014f2b2d8e6270659ded0e" href="/providers/mastodon" width="64" height="64" data-path="images/channels/mastodon.svg">
    Limits, post types and settings
  </Card>

  <Card title="Configuration reference" icon="list" href="/configuration/reference">
    Every variable she reads
  </Card>

  <Card title="Connect errors" icon="plug-circle-xmark" href="/troubleshooting/oauth-connect">
    Invalid state, invalid\_grant and the rest
  </Card>

  <Card title="Another channel" icon="plug" href="/providers/overview">
    Every network, and what each one asks for
  </Card>
</CardGroup>