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

> Easily update Open-SEO to the latest version. Follow our complete guide to pull the latest Git tag, install dependencies, run migrations, and restart your deployment.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: migration-guide
- Published: 2026-08-02

---

**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`](https://github.com/every-app/open-seo/blob/main/release-notes/v0.1.3.md) document what changed and flag any required manual steps.

Run these commands to sync to the newest tag:

```bash
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:

```bash
pnpm install

```

This command reads the updated [`pnpm-lock.yaml`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/scripts/migrate.ts). Run:

```bash
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:

```bash
docker compose build
docker compose up -d

```

The [`docker-compose.yml`](https://github.com/every-app/open-seo/blob/main/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:

```bash
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`](https://github.com/every-app/open-seo/blob/main/release-notes/v0.1.3.md)

## Complete Update Script

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

```bash
#!/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/release-notes/v0.1.3.md) — Release changelog with migration hints
- [`docs/SELF_HOSTING_DOCKER.md`](https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_DOCKER.md) — Full Docker deployment guide
- [`docs/SELF_HOSTING_CLOUDFLARE.md`](https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md) — Cloudflare Workers instructions
- [`src/server/scripts/migrate.ts`](https://github.com/every-app/open-seo/blob/main/src/server/scripts/migrate.ts) — Migration engine implementation
- [`docker-compose.yml`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.