# Recipe: moving to a new domain

Content is not affected — URLs are generated at render time, not stored. What changes is the configured origin and the redirects that keep the old links alive.

## Before

- [ ] Take a full backup: database and files. See [Backup and restore](../01-getting-started/BACKUP-RESTORE.md).
- [ ] Have DNS and TLS ready on the new domain.
- [ ] Pick a maintenance window; do not migrate mid-traffic.

## Steps

1. **Copy the files** to the new host or the new document root.
2. **Copy the database**, preserving `utf8mb4`. Dump and restore with the charset explicit; a `latin1` round trip silently mangles Arabic.
3. **Update the environment:**

```env
APP_URL=https://new-domain.example
APP_BASE_URL=/          # or the subdirectory
```

`APP_URL` is the trusted origin for password-reset and verification links; they never trust the request `Host` header, so this must be correct before anyone requests a reset.

4. **Update the database credentials** in `config/database.local.php` or `.env` if they changed.
5. **Redirect the old domain** to the new one with `301`, preserving the path:

```apache
RewriteEngine On
RewriteCond %{HTTP_HOST} ^old-domain\.example$ [NC]
RewriteRule ^(.*)$ https://new-domain.example/$1 [R=301,L]
```

Path-preserving redirects keep the value of existing links. A blanket redirect to the new home page discards it.

6. **Run diagnostics** — `php bin/doctor.php` or System → Diagnostics.
7. **Check SEO settings.** Confirm canonicals now carry the new origin and `/sitemap.xml` lists new-domain URLs only.
8. **Update mail.** If the mail domain changed, reconfigure SMTP, re-verify SPF and DKIM, and send the staged test. See [SMTP and email](../03-configuration/SMTP-EMAIL.md).
9. **Update external references:** search console properties, Telegram or webhook targets, and any API client base URLs.

## Verify

- [ ] Home, question, topic, taxonomy and profile pages load on the new domain
- [ ] Old URLs `301` to the same path on the new domain
- [ ] Canonical tags and sitemap entries use the new origin
- [ ] Sign-in works and a password-reset email arrives with a new-domain link
- [ ] The admin panel loads at its configured path
- [ ] Assets load — a missing asset means something hard-coded the old origin

## Keep the old domain

Keep it registered and redirecting for as long as you can afford. Links you do not control will keep pointing at it for years.
