Updating to a New Version

When a new version of Seedly Sites ships, you do not git pull. Your copy is a clean download with no vendor remote. Instead you apply the new code with the update helper, which keeps your settings and customizations, then run any database migrations the new version needs.

Before You Start#

• Download the new version and unzip it somewhere outside your current install, such as your Downloads folder. The update helper does not fetch anything; it copies from that folder, and it asks for the folder's path (or give it up front with --from /path/to/the-new-folder). Do not unzip it on top of your install.

• Back up Postgres. A version bump can include a database migration. Take a dump first (Backups).

• Read the release notes. Know your current version and the target version, and look for anything called out as manual. The Changelog lists what changed.

Step 1: Preview the Update#

The update helper supports a dry run so you can see what it would change without touching anything:

npx pnpm run update -- --dry-run

Read the plan. The helper preserves your environment files, your git history, and files you customized, and overlays the new product code.

Step 2: Apply the Update#

npx pnpm run update

Then reinstall dependencies, since the update may have changed them:

npx pnpm install

The helper lists the files it copied and the files it kept. A kept file is one you changed, and the helper never overwrites it, so your work survives. The new version may also have changed that file. SEEDLY-CHANGELOG.md in the new download names the files each change touched, so you can decide whether to bring a change into your copy. Until you do, a kept file works exactly as it did before.

Step 3: Run Database Migrations#

A Postgres-backed platform can require schema changes that a code overlay alone does not apply. Your cms service runs its migrations every time it starts, before the server boots, so the redeploy in Step 4 applies them. The update helper also surfaces a migration checklist. To apply them ahead of the redeploy, run them inside Railway, where your database is reachable (this needs the Railway CLI installed and linked):

railway ssh -s cms -- pnpm --filter @seedly-sites/cms migrate

Do not run the bare npx pnpm --filter @seedly-sites/cms migrate from your project folder. Your Railway database has no public address, so that command cannot reach it and stops with a DATABASE_URL error.

Migrations run against your production database, so treat this like any production action: back up first, and read what it will do. If the release notes list a specific order, follow it exactly.

If a migration fails, the cms deploy goes red and the new version never starts, while your previous version usually keeps serving, so a healthy-looking dashboard does not mean the update worked. Read the deploy log for the first line beginning [migrate] FAILED:, then follow "When a migration fails" in SETUP/operations/updating-to-a-new-version.md. If the admin errors about the database after an update, first check that the cms service's Custom Start Command (Settings > Deploy on Railway) is empty: a value there replaces the start step that runs the migrations.

The migration guide now ships inside your download, so when a release changes the database you have the instructions in front of you rather than needing to go online for them.

Step 4: Redeploy the Services#

1. Commit the updated code on a branch, open a pull request, and merge to main. Railway rebuilds the cms and pagebuilder services from main.
2. Watch the cms service come back healthy.
3. Client sites do not auto-update. A code update rebuilds no tenant. Deploy any site whose live output should reflect the new version (Deploying). When a release changes how published pages render, its release notes say so, and each site changes only when you next deploy it, so you can deploy one, look at it, and then do the rest.
4. Run npx pnpm run setup:scheduler once the cms service is back up. On your first update to 2.0.0 or later, this is the step that hands the scheduled jobs from GitHub to your CMS. Until you run it, both run them: GitHub keeps spending your Actions minutes and the automatic backup runs twice. On later updates it re-checks that the updated CMS still runs them. Keep Railway's App Sleeping setting off on the cms service and keep the service at a single replica, because a sleeping CMS runs no jobs and every extra replica runs them again.

Step 5: Verify#

Open /operator/setup on your live CMS; that page reads the real production environment. The command-line alternative, from your project folder with the Railway CLI linked, is:

railway run -s cms -- node scripts/setup/setup-check.mjs --target=prod

A plain local setup:check grades your local sandbox, not your live setup, even with --target=prod. There is also a deeper check that confirms your database matches the running code, which is the fastest way to catch a deploy that went green with a table missing. It needs your CRON_SECRET, and Step 7 of SETUP/operations/updating-to-a-new-version.md shows how to run it.

Confirm READY, then spot-check the admin and one or two live sites.

Never Do These#

• Never run provision against an already-live instance. Provisioning is fresh-instance only and refuses a non-fresh one for good reason.
• Never rotate the platform's session-signing secret as part of an update unless the release notes say to; it signs everyone out and invalidates signed tokens.
• Never apply a migration to production without a current backup in hand.