# How to use a different domain name for Pleroma and the users it serves

Pleroma users are primarily identified by a `user@example.org` handle, and you might want this identifier to be the same as your email or jabber account, for instance.
However, in this case, you are almost certainly serving some web content on `https://example.org` already, and you might want to use another domain (say `pleroma.example.org`) for Pleroma itself.

Pleroma supports that, but it might be tricky to set up, and any error might prevent you from federating with other instances.

*If you are already running Pleroma on `example.org`, it is no longer possible to move it to `pleroma.example.org`.*

## Account identifiers

It is important to understand that for federation purposes, a user in Pleroma has two unique identifiers associated:

- A webfinger `acct:` URI, used for discovery and as a verifiable global name for the user across Pleroma instances. In our example, our account's acct: URI is `acct:user@example.org`
- An author/actor URI, used in every other aspect of federation. This is the way in which users are identified in ActivityPub, the underlying protocol used for federation with other Pleroma instances.
In our case, it is `https://pleroma.example.org/users/user`.

Both account identifiers are unique and required for Pleroma. An important risk if you set up your Pleroma instance incorrectly is to create two users (with different acct: URIs) with conflicting author/actor URIs.

## WebFinger

As said earlier, each Pleroma user has an `acct`: URI, which is used for discovery and authentication. When you add @user@example.org, a webfinger query is performed. This is done in two steps:

1. Querying `https://example.org/.well-known/host-meta` (where the domain of the URL matches the domain part of the `acct`: URI) to get information on how to perform the query.
This file will indeed contain a URL template of the form `https://example.org/.well-known/webfinger?resource={uri}` that will be used in the second step.
2. Fill the returned template with the `acct`: URI to be queried and perform the query: `https://example.org/.well-known/webfinger?resource=acct:user@example.org`

## Configuring your Pleroma instance

**_DO NOT ATTEMPT TO CONFIGURE YOUR INSTANCE THIS WAY IF YOU DID NOT UNDERSTAND THE ABOVE_**


### Configuring WebFinger domain

Now, you have Pleroma running at `https://pleroma.example.org` as well as a website at `https://example.org`. If you recall how webfinger queries work, the first step is to query `https://example.org/.well-known/host-meta`, which will contain an URL template.

Therefore, the easiest way to configure `example.org` is to redirect `/.well-known/host-meta` to `pleroma.example.org`.

With nginx, it would be as simple as adding:

```nginx
location = /.well-known/host-meta {
       return 301 https://pleroma.example.org$request_uri;
}
```

in example.org's server block.

### Limitations

Some BEs and FEs may still use AP id instead of account subject to present user handles in UI.

### Warnings

Change `host` in `Pleroma.Web.Endpoint` and `domain` in `Pleroma.Web.WebFinger` with caution, it will likely result in 
local accounts being duplicated on remote instances, which will affect federation and users reachability.

Webfinger results are generally cached by server implementations and may only be requested once (on first account encounter)
or with set rate limit depending on the implementation.
