Upgrading from 1.x to 2.x

How to upgrade an existing Zepeed 1.x instance to 2.x — automatic table renames, the Ping Alert Rules → Workflow Rules merge, token abilities, breaking changes, rollback, and verification.

Zepeed 2.x renames the speedtest Alert Rules feature to Workflow Rules (models, REST API endpoints, MCP tools, token abilities, database tables, and the web UI). Your data and configuration are preserved automatically — the migration renames the tables in place and rewrites existing API token abilities, so no manual data move is required.

The separate Ping Alert Rules feature is merged into Workflow Rules by this upgrade — see Ping Alert Rules merged into Workflow Rules below.

TL;DR

1. Back up your database.
2. Deploy the 2.x code (pull the new image / checkout the new release).
3. Run php artisan migrate --force.
4. Run php artisan db:seed --force (optional but recommended — idempotent, re-runs the token-ability rewrite as a safety net).
5. Restart long-running processes so they load the new code:
   • php artisan queue:restart, then restart PHP-FPM as needed, or
   • Docker: recreate the container (the queue workers and scheduler are s6-overlay services that start fresh with the new image).
6. If you build frontend assets yourself (outside the image): bun install --ignore-scripts && bun run build.

What happens automatically

1. Tables are renamed in place (data preserved)

The migration database/migrations/2026_08_12_000001_rename_legacy_alert_rules_to_workflow_rules_table.php renames the tables and their foreign-key column — all rows are kept:

1.x	2.x
alert_rules	workflow_rules
alert_rule_conditions	workflow_rule_conditions
alert_rule_actions	workflow_rule_actions

The FK column alert_rule_id on workflow_rule_conditions and workflow_rule_actions is renamed to workflow_rule_id.

2. Existing API tokens keep working

Stored token abilities are rewritten by the migration (up()), so a plain php artisan migrate is enough:

1.x	2.x
alerts:view	workflow-rules:view
alerts:create	workflow-rules:create
alerts:update	workflow-rules:update
alerts:delete	workflow-rules:delete

WorkflowRulesMigratorSeeder (registered in DatabaseSeeder) rewrites the same abilities and is fully idempotent — running php artisan db:seed --force after migrating is a harmless safety net.

3. Fresh 2.x installs need nothing extra

On a fresh 2.x install the tables are created directly as workflow_*; the rename migration detects the legacy tables are absent and becomes a no-op.

4. Ping Alert Rules are merged into Workflow Rules

The migration database/migrations/2026_08_14_000001_merge_ping_alert_rules_into_workflow_rules.php folds the separate ping alert rules into workflow rules. Ping rules become ordinary workflow rules with event = 'ping' and a ping_target_id:

1.x	2.x
ping_alert_rules	copied into workflow_rules as event = 'ping' rows (UUIDs preserved)
ping_alert_conditions	copied into workflow_rule_conditions (with lookback_minutes)
ping_alert_actions	copied into workflow_rule_actions

workflow_rules gains a nullable ping_target_id FK (cascade on delete) plus a unique (ping_target_id, name) index; workflow_rule_conditions gains a nullable lookback_minutes column. Stored ping-alerts:* token abilities are rewritten to workflow-rules:* in the same migration. After the migration the legacy ping_alert_* tables are dropped.

Breaking changes

Area	1.x	2.x
REST API	/api/v1/alerts, /api/v1/alerts/{id}, /api/v1/alerts/{id}/toggle	/api/v1/workflow-rules, /api/v1/workflow-rules/{id}, /api/v1/workflow-rules/{id}/toggle (old path removed, not aliased)
Token abilities	alerts:*	workflow-rules:* (existing tokens migrated automatically)
MCP tools	ListAlertRules, CreateAlertRule, UpdateAlertRule, DeleteAlertRule, ToggleAlertRule (kebab: list-alert-rules, …)	ListWorkflowRules, CreateWorkflowRule, UpdateWorkflowRule, DeleteWorkflowRule, ToggleWorkflowRule (list-workflow-rules, …)
Web UI	Settings → Alert Rules (/speedtest/settings/alert-rules)	Settings → Workflow Rules (/speedtest/settings/workflow-rules)

Update any external consumers (scripts, dashboards, AI clients) that call the old endpoint, tool, or ability names.

Ping Alert Rules merged into Workflow Rules

Zepeed 2.x also merges the separate Ping Alert Rules feature into Workflow Rules:

Area	Before	After
REST API	/api/v1/ping-alerts, /api/v1/ping-alerts/{id}, /api/v1/ping-alerts/{id}/toggle	/api/v1/workflow-rules (ping rules are event: "ping" + ping_target_id; old path removed, not aliased)
Token abilities	ping-alerts:*	workflow-rules:* (existing tokens migrated automatically)
MCP tools	ListPingAlertRules, CreatePingAlertRule, UpdatePingAlertRule, DeletePingAlertRule, TogglePingAlertRule	the corresponding *WorkflowRule tools accept event: "ping", ping_target_id, ping metrics and lookback_minutes
Web UI	Network → Ping Alert Rules (/speedtest/network/ping-alerts)	Settings → Workflow Rules (/speedtest/settings/workflow-rules) — pick the Ping result recorded event
Tables	ping_alert_rules, ping_alert_conditions, ping_alert_actions	rows copied into workflow_rules (event = 'ping'), workflow_rule_conditions (with lookback_minutes) and workflow_rule_actions; legacy tables dropped

The migration runs automatically on php artisan migrate; existing ping rules and ping-alerts:* token abilities are preserved. New ping condition metrics (latency_avg, latency_max, consecutive_failures) live on WorkflowRuleMetric, and new operators (is_above_or_equal, is_below_or_equal) on WorkflowRuleOperator.

Not renamed (intentionally)

• Prometheus metric names — zepeed_alert_rule_active, zepeed_alert_rule_last_triggered_timestamp, zepeed_ping_alert_rule_active and zepeed_ping_alert_rule_last_triggered_timestamp are a stable external contract for dashboards and are kept unchanged.

Rollback

php artisan migrate:rollback runs each migration’s down(): the rename migration restores the legacy alert_* table/column names and flips workflow-rules:* abilities back to alerts:*; the merge migration recreates the ping_alert_* tables, moves event = 'ping' workflow rules back into them, and drops the ping_target_id / lookback_minutes columns. If you only roll back the migrations while 2.x code is still deployed, the app will be broken — roll back the deployment as a unit.

On MariaDB/MySQL, down() performs the same foreign-key column renames as up() and can hit error 1025 mid-way, leaving a mixed alert_*/workflow_* state. Follow the backup-restore and drop/re-create-FK guidance in Troubleshooting if that happens.

Verification after upgrading

-- Your rules should be intact, just under the new names
SELECT COUNT(*) FROM workflow_rules;
SELECT COUNT(*) FROM workflow_rule_conditions;
SELECT COUNT(*) FROM workflow_rule_actions;

-- Your old ping alert rules should now be workflow rules with event = 'ping'
SELECT COUNT(*) FROM workflow_rules WHERE event = 'ping';

# No legacy tables should remain
#   MySQL / MariaDB:  SHOW TABLES LIKE 'alert\_rule%';
#   PostgreSQL:       \dt alert_rule*
#   SQLite:           SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'alert_rule%';

# The ping_alert_* tables should be gone too
#   MySQL / MariaDB:  SHOW TABLES LIKE 'ping\_alert\_%';
#   SQLite:           SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'ping_alert_%';

# An existing token's abilities should now use the workflow-rules: prefix
php artisan tinker --execute '
  $t = \App\Models\PersonalAccessToken::query()->latest("id")->first();
  dump($t?->abilities);
'

Then trigger a speedtest and a ping test, and confirm your rules fire.

Troubleshooting

• Mailer [...] is not defined after upgrade — a long-running queue worker is still executing pre-upgrade code. Run php artisan queue:restart and recreate the container / restart PHP-FPM.
• MariaDB/MySQL: the rename migration errors with code 1025 — renaming a foreign-key column can hit this on some versions. Test the migration against a copy of your production data first; if it fails, drop and re-create the two foreign keys around the rename (see the migration file for the exact columns).
• The migration fails partway — Schema::rename is not transactional on MySQL/MariaDB. Restore your backup and re-run, or complete the remaining renames manually (the migration is guarded and skips already-renamed tables).