# Using multiple domains {#using-multiple-domains}


While in many cases you will just have one short domain, and you'll want all your short URLs to be served from it, there are some cases in which you may want to have multiple short domains served from the same Shlink instance.

If that's the case, you need to understand how Shlink will behave when managing your short URLs or any of them is visited.



> [!WARNING]
> **Important!**
>
> In this page you will learn how a single Shlink instance behaves when served behind more than one domain.
>
> However, it's still <b>up to you</b> to properly configure the DNS and web server, so that all the domains point to
> the proper "place", and the requests end up in Shlink. Shlink will never be able to do this on its own.
>
>   If you want to learn more about this aspect, go to 
>   [External configuration](https://sourcey-shlink.pages.dev/documentation/advanced/multiple-domains/index.md#external-configuration).




## Management {#management}


When you create a short URL (either from the CLI or the REST API), it is possible to optionally provide a `domain` param. If you don't pass it, the short URL will be created for the default domain (the one provided during Shlink's installation or in the `DEFAULT_DOMAIN` env var).

However, if you pass it, the short URL will be "linked" to that domain.

> Note that, if the default domain is passed here, Shlink will ignore it and will behave as if no `domain` param was provided.

The main benefit of being able to pass the domain is that Shlink will allow the same custom slug to be used in multiple short URLs, as long as the domain is different (like `example.com/my-compaign`, `another.com/my-compaign` and `foo.com/my-compaign`).

Then, each short URL will be tracked separately and you will be able to define specific tags and metadata for each one of them.

However, this has a side effect. When you try to interact with an existing short URL (editing tags, editing meta, resolving it or deleting it), either from the REST API or the CLI, you will have to provide the domain appropriately.

Let's imagine this situation. Shlink's default domain is `example.com`, and you have the next short URLs:

- `https://example.com/abc123`: a regular short URL where no domain was provided.
- `https://example.com/my-campaign`: a regular short URL where no domain was provided, but it has a custom slug.
- `https://another.com/my-campaign`: a short URL where the `another.com` domain was provided, and it also has a custom slug.
- `https://another.com/def456`: a short URL where the `another.com` domain was provided.

These are some of the results you will get when trying to interact with them, depending on the params you provide:

- Providing just the `abc123` short code: the first URL will be matched.
- Providing just the `my-campaign` short code: the second URL will be matched, since you did not specify a domain, therefor, Shlink looks for the one with the short code/slug `my-campaign` which is also linked to default domain (or not linked to any domain, to be more precise).
- Providing the `my-campaign` short code and the `another.com` domain: The third one will be matched.
- Providing just the `def456` short code: Shlink will fail/not find any short URL, since there's none with the short code `def456` linked to default domain.
- Providing the `def456` short code and the `another.com` domain: The fourth short URL will be matched.
- Providing any short code and the `foo.com` domain: Again, no short URL will be found, as there's none linked to `foo.com` domain.


## Visits {#visits}


Before adding support for multiple domains, you could point as many domains as you wanted to Shlink, and they would have always worked for existing short codes/slugs.

In order to keep backwards compatibility, Shlink's behavior when a short URL is visited is slightly different, getting to fallback in some cases.

Let's continue with previous example, and also consider we have three domains that will resolve to our Shlink instance, which are `example.com`, `another.com` and `foo.com`.

With that in mind, this is how Shlink will behave when the next short URLs are visited:

- `https://another.com/abc123`: There was no short URL specifically defined for domain `another.com` and short code `abc123`, but it exists for default domain (`example.com`), so it will fall back to it and redirect to where `example.com/abc123` is configured to redirect.
- `https://example.com/def456`: The fall back does not happen from default domain to specific ones, only the other way around (like in previous case). Because of that, this one will result in a not-found URL, even though the `def456` short code exists for `another.com` domain.
- `https://foo.com/abc123`: This will also fall back to `example.com/abc123`, like in the first case.
- `https://another.com/non-existing`: The combination of `another.com` domain with the `non-existing` slug does not exist, so Shlink will try to fall back to the same but for default domain (`example.com`). However, since that combination does not exist either, it will result in a not-found URL.
- Any other short URL visited exactly as it was configured will, of course, resolve as expected.


## Special redirects {#special-redirects}


Starting with Shlink v2.8.0, it is possible to configure special redirects on a per-domain basis. [Read the docs](https://sourcey-shlink.pages.dev/documentation/advanced/special-redirects/index.md#per-domain-redirects) to get more information.


## External configuration {#external-configuration}


Now that you know how Shlink behaves on a multi-domain context, you also need to perform a couple of extra steps outside Shlink itself.

Not performing these steps will result in requests never reaching Shlink or miss important information.

- **Configure the DNS**: You probably did this for the default domain, and it needs to be done for every extra domain you plan Shlink to handle.

  DNS management is different for every provider, but a good way to start is by searching for "configure DNS" followed by your DNS provider name on the search engine of your choice.

- **Configure your server's virtual host**: If you are serving Shlink with a classic web server or behind a reverse proxy, you have probably configured you virtual hosts at some point.

  Those virtual hosts need to handle all the default and non-default domains. This is how it's done for the most used web servers here:

  - Nginx: Use the [`server_name`](https://nginx.org/en/docs/http/server_names.html) followed by all the domains, separated by spaces.

  ```
  server_name example.com another.com foo.com
  ```
  - Apache: Use the [`ServerName`](https://httpd.apache.org/docs/2.4/mod/core.html#servername) directive for the main domain, and then add as many [`ServerAlias`](https://httpd.apache.org/docs/2.4/mod/core.html#serveralias) as you need, until you completed all the domains.

  ```
  ServerName example.com
  ServerAlias another.com
  ServerAlias foo.com
  ```
  - Caddy: Use the [`bind`](https://caddyserver.com/docs/caddyfile/directives/bind) directive followed by all the domains, separated by spaces.

  ```
  bind example.com another.com foo.com
  ```

- **Make sure the domain is passed when using a reverse proxy**: If you don't configure your reverse proxy to pass the domain down, Shlink won't be able what was the actual domain used when visiting a short URL, resulting in 404s or incorrect visits stats.

  Because fo that, follow the [Using a reverse proxy](https://sourcey-shlink.pages.dev/documentation/advanced/exposing-through-reverse-proxy/index.md) documentation.

  In any case, these are the important instructions for the most used web servers:

  - Nginx: Use the `proxy_set_header` directive to pass the `Host` header, combined with the `$host` variable.

  ```
  proxy_set_header Host $host;
  ```
  - Apache: Set the `ProxyPreserveHost` option to `On`.

  ```
  ProxyPreserveHost On
  ```
  - Caddy: Use the `header_up` directive to pass the `Host` header, combined with the `{upstream_hostport}` placeholder.

  ```
  header_up Host {upstream_hostport}
  ```