> For the complete documentation index, see [llms.txt](https://docs.tumbler.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tumbler.app/after-first-launch/mirrors-and-migration.md).

# Mirrors and migration

## Who this is for

Providers that manage several locations or are preparing a URL migration without service interruption.

## What you can do

* Configure subscription mirrors.
* Move clients safely to a new domain or path.
* Announce migration through metadata.

## Examples

* Primary URL plus a mirror in another region.
* 301 from the old path to the new path while preserving scheme.
* `meta.mirrors` field with a list of alternatives.

## See also

* [subscription/fetch-url.md](/getting-started/fetch-url.md)
* [operations/reliability-and-timeouts.md](/after-first-launch/reliability-and-timeouts.md)
* [changelog.md](/changelog.md)

## Mirror strategy

* Keep identical content on all mirrors and synchronize `ETag`.
* Provide `meta.mirrors` when you want to give explicit fallback hints to clients.
* Watch certificates: mirrors must have valid TLS and the same header set.

## Step-by-step migration without downtime

1. **Add mirrors.** Publish the new domain/path in `meta.mirrors`, and start serving an identical body with the same `ETag` on both locations. Give clients time (at least 1-2 weeks) to refresh configs and switch to the mirror.
2. **Enable the new endpoint.** Make the new URL primary in your output (for example, in dashboard or documentation), but keep serving the old one with the same content and headers.
3. **Enable redirect.** After verifying that the new endpoint is available, enable 301/308 from the old endpoint to the new one. Preserve scheme/path/query parameters.
4. **Keep compatibility.** Keep the old endpoint or redirect available at least for the client update window. Recommended horizon is at least one automatic client update cycle (usually 3-6 months). Announce the deadline in [changelog.md](/changelog.md).
5. **Disable gradually.** After the compatibility window, remove the redirect and finish the migration, after verifying that all clients have moved to the new URL.

## Smooth migration

* Keep the old URL available with 301 or identical content for at least the client update window.
* Announce migration and deadlines in [changelog.md](/changelog.md).
* Do not change the access scheme (for example, from GET to POST) without a transition period.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tumbler.app/after-first-launch/mirrors-and-migration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.