Skip to content

Commit 342cdac

Browse files
aaronlippoldaaronlippold
committed
docs: simplify upgrade guide — lead with gas-and-go flow
Rewrote Quick Start to lead with the simplest path: the new image already has the toolkit, so users just pull + run. No docker cp, no curl, no file injection. Docker Compose: 6 commands (back up, pull, preflight, fix, up, verify). Kubernetes: one-shot pod with --env-from. Bare metal: git pull + bundle exec. Standalone bin/upgrade-check.sh moved to "Can't even connect?" fallback section. Pre-v2.3.6 users get the docker run --env-file path as the upgrade bootstrap. Authored by: Aaron Lippold<lippold@gmail.com>
1 parent 0d2ae27 commit 342cdac

2 files changed

Lines changed: 79 additions & 101 deletions

File tree

‎docs/deployment/docker.md‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -167,18 +167,17 @@ docker compose run --rm web bundle exec rails db:migrate
167167
168168
### Upgrading Between Versions
169169

170-
For major upgrades (e.g., v2.2.x → v2.3.x), run the preflight diagnostic before pulling the new image:
170+
The upgrade toolkit is built into every image from v2.3.6+:
171171

172172
```bash
173-
# Copy the diagnostic into your running container
174-
docker cp lib/tasks/upgrade_preflight.rake $(docker compose ps -q web):/rails/lib/tasks/
175-
docker compose exec web rails upgrade:preflight
176-
177-
# Or use the standalone script (no container modification needed)
178-
./bin/upgrade-check.sh "$DATABASE_URL"
173+
docker compose pull # Get new image
174+
docker compose run --rm web rails upgrade:preflight # Check before upgrading
175+
docker compose run --rm web rails upgrade:fix # Fix any issues
176+
docker compose up -d # Start (runs db:prepare)
177+
docker compose exec web rails upgrade:verify # Confirm success
179178
```
180179

181-
See the full [Upgrade Guide](upgrade-guide) for step-by-step instructions, Aurora RDS notes, and auto-fix for common data issues.
180+
See the full [Upgrade Guide](upgrade-guide) for Aurora RDS notes, Kubernetes/ECS paths, and troubleshooting.
182181

183182
## Monitoring
184183

‎docs/deployment/upgrade-guide.md‎

Lines changed: 72 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,137 +1,116 @@
11
# Vulcan Upgrade Guide
22

3-
## Quick Start (for any version upgrade)
3+
## Quick Start
44

5-
### Step 1: Install the upgrade toolkit
5+
The upgrade toolkit is built into every Vulcan image from v2.3.6+. No file injection, no extra installs — just pull and run.
66

7-
Choose the method that matches your deployment:
8-
9-
#### Bare metal / systemd
7+
### Docker Compose (most common)
108

119
```bash
12-
# Download directly into your Vulcan source tree
13-
cd /path/to/vulcan
14-
curl -fsSL https://raw.githubusercontent.com/mitre/vulcan/master/lib/tasks/upgrade_preflight.rake \
15-
-o lib/tasks/upgrade_preflight.rake
16-
```
10+
# 1. Back up your database
11+
docker compose exec db pg_dump -Fc -U postgres vulcan_postgres_production \
12+
> vulcan_backup_$(date +%Y%m%d).dump
1713

18-
#### Docker Compose
14+
# 2. Pull the new image (or update your image tag in docker-compose.yml)
15+
docker compose pull
1916

20-
```bash
21-
# Copy the rake file into your RUNNING container (no image rebuild needed)
22-
curl -fsSL https://raw.githubusercontent.com/mitre/vulcan/master/lib/tasks/upgrade_preflight.rake \
23-
-o /tmp/upgrade_preflight.rake
24-
docker cp /tmp/upgrade_preflight.rake $(docker compose ps -q web):/rails/lib/tasks/upgrade_preflight.rake
25-
```
17+
# 3. Preflight check (runs the NEW image against your EXISTING database)
18+
docker compose run --rm web rails upgrade:preflight
2619

27-
#### ECS / Kubernetes / any container orchestrator
20+
# 4. Fix any issues it finds
21+
docker compose run --rm web rails upgrade:fix
2822

29-
```bash
30-
# Option A: Exec into the running task/pod and download
31-
kubectl exec -it deploy/vulcan-web -- bash -c \
32-
"curl -fsSL https://raw.githubusercontent.com/mitre/vulcan/master/lib/tasks/upgrade_preflight.rake \
33-
-o lib/tasks/upgrade_preflight.rake"
34-
35-
# Option B: If curl isn't available in the container, copy from local
36-
kubectl cp /tmp/upgrade_preflight.rake vulcan-web-pod:/rails/lib/tasks/upgrade_preflight.rake
37-
38-
# ECS equivalent (using aws cli + ssm exec)
39-
aws ecs execute-command --cluster vulcan --task $TASK_ID --container web \
40-
--command "curl -fsSL https://raw.githubusercontent.com/mitre/vulcan/master/lib/tasks/upgrade_preflight.rake \
41-
-o lib/tasks/upgrade_preflight.rake" --interactive
42-
```
23+
# 5. Start (db:prepare runs automatically via the entrypoint)
24+
docker compose up -d
4325

44-
#### Can't modify the container at all?
26+
# 6. Verify
27+
docker compose exec web rails upgrade:verify
28+
```
4529

46-
Use the standalone diagnostic script — no Rails required, just `psql`:
30+
### Kubernetes / ECS
4731

4832
```bash
49-
# Download and run from any machine that can reach your database
50-
curl -fsSL https://raw.githubusercontent.com/mitre/vulcan/master/bin/upgrade-check.sh \
51-
-o upgrade-check.sh && chmod +x upgrade-check.sh
52-
53-
# Point it at your database
54-
./upgrade-check.sh postgres://user:pass@your-db-host:5432/vulcan_production
33+
# 1. Back up your database (use your standard backup procedure)
34+
35+
# 2. Run preflight as a one-shot pod/task with the NEW image
36+
kubectl run vulcan-preflight --rm -it \
37+
--image=mitre/vulcan:v2.3.6 \
38+
--env-from=secret/vulcan-env \
39+
-- rails upgrade:preflight
40+
41+
# 3. Fix if needed
42+
kubectl run vulcan-fix --rm -it \
43+
--image=mitre/vulcan:v2.3.6 \
44+
--env-from=secret/vulcan-env \
45+
-- rails upgrade:fix
46+
47+
# 4. Deploy the new image (your standard deploy process)
48+
# 5. Verify
49+
kubectl exec -it deploy/vulcan-web -- rails upgrade:verify
5550
```
5651

57-
No gem installs, no Gemfile changes, no image rebuilds. The rake task is one file that uses Rails APIs already in the app. The shell script uses only `psql`.
58-
59-
### Step 2: Back up your database
60-
61-
**Do this before anything else.** Every upgrade path is tested, but your data is unique.
52+
### Bare metal / systemd
6253

6354
```bash
64-
# Vanilla PostgreSQL
55+
# 1. Back up
6556
pg_dump -Fc your_database > vulcan_backup_$(date +%Y%m%d).dump
6657

67-
# Aurora RDS (from a bastion or local machine with psql access)
68-
pg_dump -Fc -h your-cluster.cluster-xxxx.us-east-1.rds.amazonaws.com \
69-
-U vulcan_user -d vulcan_production > vulcan_backup_$(date +%Y%m%d).dump
58+
# 2. Pull new code
59+
cd /path/to/vulcan && git pull
7060

71-
# Docker Compose
72-
docker compose exec db pg_dump -Fc -U postgres vulcan_postgres_production \
73-
> vulcan_backup_$(date +%Y%m%d).dump
61+
# 3. Preflight
62+
bundle exec rails upgrade:preflight
7463

75-
# ECS / Kubernetes (exec into the db container or use a bastion)
76-
kubectl exec -it deploy/vulcan-db -- pg_dump -Fc -U postgres vulcan_production \
77-
> vulcan_backup_$(date +%Y%m%d).dump
64+
# 4. Fix
65+
bundle exec rails upgrade:fix
66+
67+
# 5. Upgrade
68+
bundle exec rails db:prepare
69+
70+
# 6. Verify
71+
bundle exec rails upgrade:verify
7872
```
7973

80-
### Step 3: Run the preflight check
74+
### Can't even connect? (quick diagnostic)
75+
76+
If the new container won't start at all, use the standalone script from any machine with `psql`:
8177

8278
```bash
83-
# Bare metal / systemd
84-
bundle exec rails upgrade:preflight
79+
curl -fsSL https://raw.githubusercontent.com/mitre/vulcan/master/bin/upgrade-check.sh -o upgrade-check.sh
80+
chmod +x upgrade-check.sh
81+
./upgrade-check.sh "postgres://user:pass@your-db-host:5432/vulcan_production?sslmode=require"
82+
```
8583

86-
# Docker Compose
87-
docker compose exec web rails upgrade:preflight
84+
No Rails, no Ruby, no container — just raw database diagnostics.
8885

89-
# Docker (new image against existing database)
90-
docker run --rm --env-file .env vulcan:new-version rails upgrade:preflight
86+
### What the tools do
9187

92-
# ECS / Kubernetes
93-
kubectl exec -it deploy/vulcan-web -- rails upgrade:preflight
94-
```
88+
| Command | When | What |
89+
|---|---|---|
90+
| `rails upgrade:preflight` | Before upgrade | Checks connectivity, SSL, schema, orphaned data, config (read-only) |
91+
| `rails upgrade:fix` | Before upgrade | Fixes orphaned records, counter caches, missing dirs (safe writes) |
92+
| `rails upgrade:verify` | After upgrade | Validates schema, models, routes, assets, admin user |
93+
| `bin/upgrade-check.sh` | Can't start container | Raw psql diagnostic — tests connection, SSL, encoding |
9594

9695
The preflight reports:
9796
- ✓ = good
9897
- ⚠ = warning (review, but won't block)
9998
- ✗ = blocker (must fix before upgrading)
10099

101-
### Step 4: Fix any issues
102-
103-
```bash
104-
# Auto-fix safe issues (orphaned records, counter caches, missing dirs)
105-
bundle exec rails upgrade:fix
106-
107-
# Or in Docker
108-
docker compose exec web rails upgrade:fix
109-
```
110-
111-
The fix task only runs **safe operations** — it will NOT:
112-
- Delete data without telling you exactly what and how many rows
113-
- Modify schema (that's what db:prepare does)
114-
- Change configuration (it tells you what to set)
115-
116-
For connection issues (the most common upgrade blocker), the fix task prints the exact environment variables you need to set.
100+
### Upgrading from pre-v2.3.6 (toolkit not in image)
117101

118-
### Step 5: Run the upgrade
102+
If your CURRENT image doesn't have the toolkit yet, run the preflight from the NEW image:
119103

120104
```bash
121-
# This runs pending migrations (safe — preflight already validated)
122-
bundle exec rails db:prepare
105+
# Pull the new image but don't start it yet
106+
docker pull mitre/vulcan:v2.3.6
123107

124-
# Docker: the entrypoint does this automatically on container start
125-
docker compose up
108+
# Run preflight from the new image against your existing database
109+
docker run --rm --env-file .env mitre/vulcan:v2.3.6 rails upgrade:preflight
110+
docker run --rm --env-file .env mitre/vulcan:v2.3.6 rails upgrade:fix
126111
```
127112

128-
### Step 6: Verify
129-
130-
```bash
131-
bundle exec rails upgrade:verify
132-
# or
133-
docker compose exec web rails upgrade:verify
134-
```
113+
The `--env-file .env` passes your existing database credentials to the new container.
135114

136115
---
137116

0 commit comments

Comments
 (0)