How to Update Open‑SEO to the Latest Version: Complete Upgrade Guide

Update Open‑SEO by pulling the latest Git tag, running pnpm install and pnpm run migrate, then rebuilding and restarting your Docker containers or deploying to Cloudflare Workers.

Keeping your Open‑SEO installation current ensures you receive the latest features, performance improvements, and security patches. The every-app/open-seo repository uses semantic versioning with Git tags, making upgrades predictable across both Docker‑based and Cloudflare Workers deployments.

Prerequisites Before Updating

Before starting the update process, ensure you have:

• A local clone of the every-app/open-seo repository
• pnpm installed (the project's default package manager)
• Docker and Docker Compose (for self‑hosted deployments), or
• Cloudflare Workers CLI configured (for serverless deployments)

Verify your current version by checking the footer of your running instance or running git describe --tags in your repository root.

Step 1: Fetch and Checkout the Latest Release

Open‑SEO versions are tagged in Git using semantic versioning (e.g., v0.1.3). The release notes in release-notes/v0.1.3.md document what changed and flag any required manual steps.

Run these commands to sync to the newest tag:

git fetch --tags
latest_tag=$(git describe --tags `git rev-list --tags --max-count=1`)
git checkout $latest_tag

This brings your working directory to the exact commit of the latest release. The git rev-list command finds the most recent tag chronologically, ensuring you don't accidentally check out an older maintenance release.

Step 2: Update Dependencies

Open‑SEO is organized as a pnpm monorepo. After checking out the new tag, refresh all Node.js packages:

pnpm install

This command reads the updated pnpm-lock.yaml and installs any newly added or upgraded dependencies. The lockfile changes between releases to pin exact versions, so skipping this step will cause runtime errors.

Step 3: Apply Database Migrations

Schema changes are applied automatically via the migration system in src/server/scripts/migrate.ts. Run:

pnpm run migrate

The migration scripts detect your database type (SQLite for local development, PostgreSQL for production) and execute the appropriate DDL changes. According to the source code, migrations are idempotent—you can safely rerun them if interrupted.

Step 4: Rebuild and Restart Services

The update path diverges based on your hosting method.

Docker‑Based Deployments

Rebuild the container image with the fresh codebase and updated dependencies:

docker compose build
docker compose up -d

The docker-compose.yml at the repository root defines the services. The build step compiles the application inside a clean container, ensuring no stale node_modules persist. The -d flag restarts services in detached mode.

Cloudflare Workers Deployments

For serverless hosting, deploy the updated bundle directly:

pnpm run deploy:cloudflare

This command packages the server‑side code and pushes it to your Cloudflare Workers account. The deployment is atomic—traffic switches to the new version only after the upload succeeds.

Step 5: Verify the Update

Confirm the upgrade succeeded with these checks:

1. Version number – Open your instance URL and check the footer displays the new tag (e.g., v0.1.3)
2. Health endpoint – Run curl http://localhost:3000/api/health and expect {"status":"ok"}
3. Feature functionality – Test any new capabilities mentioned in release-notes/v0.1.3.md

Complete Update Script

For automation, combine all steps into a single shell script:

#!/bin/bash
set -e

echo "Fetching latest Open‑SEO release..."
git fetch --tags
latest_tag=$(git describe --tags `git rev-list --tags --max-count=1`)
git checkout "$latest_tag"

echo "Installing dependencies..."
pnpm install

echo "Running database migrations..."
pnpm run migrate

echo "Rebuilding and restarting..."
docker compose build
docker compose up -d

echo "Open‑SEO updated to $latest_tag"
echo "Verify at: http://localhost:3000/api/health"

Troubleshooting Common Update Issues

Symptom	Cause	Solution
pnpm install fails with lockfile errors	Conflicting lockfile from previous branch	Run git checkout HEAD -- pnpm-lock.yaml && pnpm install
Migration errors on startup	Schema drift from interrupted prior migration	Check src/server/scripts/migrate.ts logs and manually reset if needed
Container fails to start after rebuild	Cached Docker layers with old dependencies	Run docker compose build --no-cache
Cloudflare deployment hangs	Authentication token expired	Re-run npx wrangler login before deploying

Key Files and Resources

• release-notes/v0.1.3.md — Release changelog with migration hints
• docs/SELF_HOSTING_DOCKER.md — Full Docker deployment guide
• docs/SELF_HOSTING_CLOUDFLARE.md — Cloudflare Workers instructions
• src/server/scripts/migrate.ts — Migration engine implementation
• docker-compose.yml — Service orchestration configuration

Summary

• Pull the latest Git tag using git fetch --tags and git checkout to the most recent release
• Install dependencies with pnpm install to sync the lockfile
• Migrate the database schema automatically with pnpm run migrate
• Rebuild Docker images with docker compose build && docker compose up -d or deploy to Cloudflare with pnpm run deploy:cloudflare
• Verify via the health endpoint and UI footer version number

Frequently Asked Questions

How do I check which Open‑SEO version I'm currently running?

Run git describe --tags in your repository clone, or open your running instance and check the version number displayed in the footer. The API health endpoint also returns version metadata at /api/health.

Can I skip database migrations if only minor version changed?

No. Open‑SEO migrations are designed to be safe and idempotent. The src/server/scripts/migrate.ts engine detects already‑applied changes and skips them automatically. Skipping the step risks schema mismatches that crash the application.

What happens if the update fails halfway through?

Your data remains safe because migrations run inside transactions. For Docker deployments, the old containers continue running until docker compose up -d succeeds. If stuck, check docker compose logs, fix the underlying issue, and rerun the build step. For Cloudflare, failed deployments don't affect production traffic.

Is automatic updating supported?

Not natively. Open‑SEO requires manual Git operations and container rebuilds to ensure you review release notes (release-notes/v0.1.3.md) and handle any breaking changes. However, you can schedule the complete update script via cron or your orchestration platform after testing in a staging environment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}