diff --git a/docs/pages/guides/migration.mdx b/docs/pages/guides/migration.mdx
index dd5ba447c..bbe591394 100644
--- a/docs/pages/guides/migration.mdx
+++ b/docs/pages/guides/migration.mdx
@@ -39,9 +39,15 @@ docker run --rm hookdeck/outpost migrate plan
 Execute the migration (creates new structures, preserves old ones):
 
 ```bash
+# Apply the next pending migration
 docker run --rm -it hookdeck/outpost migrate apply
+
+# Or apply all pending migrations in sequence
+docker run --rm -it hookdeck/outpost migrate apply --all
 ```
 
+The `--all` flag runs each pending migration in version order, automatically verifying each one before proceeding to the next. If any migration fails verification, the process stops immediately.
+
 :::info
 The `-it` flags enable interactive mode for confirmation prompts. Add `--yes` to skip confirmations in automated environments.
 :::
@@ -101,6 +107,58 @@ Cleanup operations require successful verification by default:
 - Prevents accidental data loss
 - Can be overridden with `--force` flag (use with caution)
 
+## Running in Private Environments
+
+Redis is often deployed in private networks (VPCs, internal subnets) that aren't accessible from your local machine. The migration tool needs direct network access to Redis, so you'll need to run it from within the same network.
+
+### Common Approaches
+
+**Run from an existing host in the network:**
+
+If you have SSH access to a host that can reach Redis (e.g., your application server), you can run the migration there:
+
+```bash
+# SSH into a host with Redis access
+ssh your-server
+
+# Run migration using Docker
+docker run --rm -it \
+  -e REDIS_HOST=redis.internal \
+  -e REDIS_PASSWORD=... \
+  hookdeck/outpost:v0.12.0 migrate apply --all
+```
+
+**Kubernetes:**
+
+Run the migration as a one-off pod in the same namespace/cluster:
+
+```bash
+kubectl run outpost-migrate --rm -it --restart=Never \
+  --image=hookdeck/outpost:v0.12.0 \
+  --env="REDIS_HOST=redis.internal" \
+  --env="REDIS_PASSWORD=..." \
+  -- migrate apply --all
+```
+
+**Port forwarding:**
+
+If direct access isn't possible, you can forward the Redis port to your local machine:
+
+```bash
+# Example: SSH tunnel
+ssh -L 6379:redis.internal:6379 bastion-host
+
+# Then run migration locally
+docker run --rm -it \
+  -e REDIS_HOST=host.docker.internal \
+  -e REDIS_PORT=6379 \
+  hookdeck/outpost:v0.12.0 migrate apply --all
+```
+
+:::tip
+Use the same network configuration that Outpost itself uses to connect to Redis. If Outpost can reach Redis, running the migration tool in the same environment will work.
+:::
+
 ## Configuration
 
 The `outpost` CLI tool uses the same configuration as Outpost itself. Configuration can be provided through environment variables, a configuration file (using `--config` flag), or CLI flags (e.g., `--redis-host`, `--redis-password`).
diff --git a/docs/pages/guides/upgrade-v0.12.mdx b/docs/pages/guides/upgrade-v0.12.mdx
index fbd3ec12a..84a4619c7 100644
--- a/docs/pages/guides/upgrade-v0.12.mdx
+++ b/docs/pages/guides/upgrade-v0.12.mdx
@@ -235,11 +235,11 @@ See the [API Reference](/docs/api/tenants#list-tenants) for details.
 ### Migrations Included
 
 - **002_timestamps**: Converts timestamp fields to Unix format for timezone-agnostic sorting
-- **003_entity**: Creates RediSearch indexes for tenant listing
+- **003_entity**: Adds entity field to tenant and destination records for RediSearch filtering
 
 ### Running Migrations
 
-Migrations run automatically at startup. For production environments, manual migration is recommended.
+These migrations require a maintenance window and must be run manually before starting Outpost v0.12.
 
 :::note
 These commands require environment variables for Redis connection (`REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, etc.). You can also use `--config` to pass a config file. See the [Schema Migration Guide](/guides/migration#configuration) for details.
@@ -249,19 +249,16 @@ These commands require environment variables for Redis connection (`REDIS_HOST`,
 # Preview changes
 docker run --rm -e REDIS_HOST=... -e REDIS_PASSWORD=... hookdeck/outpost:v0.12.0 migrate plan
 
-# Apply migrations
+# Apply the next pending migration (one at a time)
 docker run --rm -it -e REDIS_HOST=... -e REDIS_PASSWORD=... hookdeck/outpost:v0.12.0 migrate apply
 
+# Apply all pending migrations in sequence
+docker run --rm -it -e REDIS_HOST=... -e REDIS_PASSWORD=... hookdeck/outpost:v0.12.0 migrate apply --all
+
 # Verify migrations
 docker run --rm -e REDIS_HOST=... -e REDIS_PASSWORD=... hookdeck/outpost:v0.12.0 migrate verify
 ```
 
-For systems with high write throughput, re-run migrations after the initial upgrade:
-
-```bash
-docker run --rm -it -e REDIS_HOST=... -e REDIS_PASSWORD=... hookdeck/outpost:v0.12.0 migrate apply --rerun
-```
-
 :::tip[Migration Tool Reference]
 For detailed information on the migration workflow, safety features, and troubleshooting, see the [Schema Migration Guide](/guides/migration).
 :::
@@ -278,11 +275,11 @@ For detailed information on the migration workflow, safety features, and trouble
    - [ ] Back up Redis data
 
 2. **During upgrade:**
-
+   - [ ] Stop Outpost
+   - [ ] Run migrations: `migrate apply --all`
+   - [ ] Verify migrations completed: `migrate verify`
    - [ ] Set webhook signature environment variables if maintaining backward compatibility
-   - [ ] Run migrations (automatic or manual)
 
 3. **After upgrading:**
-   - [ ] Verify migrations completed: `migrate verify`
-   - [ ] For high-volume systems: `migrate apply --rerun`
+   - [ ] Start Outpost v0.12
    - [ ] Test webhook signature verification