> For the complete documentation index, see [llms.txt](https://mcp.conserver.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mcp.conserver.io/vconic-for-resellers/06-upgrade-guide.md).

# Upgrade Guide

**Audience:** Reseller deployment leads upgrading a customer instance to a newer VCONIC release.

## Reseller lens

Use a stop-the-world upgrade: snapshot, migrate, swap, verify. The procedure is short because each step is non-negotiable.

## Before you start

1. Read the [Release Notes](/vconic-for-resellers/07-release-notes.md) for the target version.
2. Note breaking changes and new required env vars.
3. **Snapshot the database.** Supabase backup (cloud) or `pg_dump` (self-hosted).
4. Record the current version: `curl -I http://<host>:3000/api/v1/health` — capture `X-Version` and `X-Git-Commit`.

## Upgrade procedure

```bash
# 1. Pull the target image (always pin to a semver tag)
docker pull public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:<new-tag>

# 2. Run new migrations BEFORE swapping the running container
docker run --rm \
  -e SUPABASE_DB_URL='postgresql://...' \
  public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:<new-tag> \
  migrate

# 3. Stop the current container
docker stop --time 30 vconic && docker rm vconic

# 4. Start the new image with the same env file
docker run -d --name vconic \
  --env-file /etc/vconic/env \
  -p 3000:3000 \
  public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:<new-tag>

# 5. Smoke-test
curl -I http://localhost:3000/api/v1/health
# Confirm X-Version matches <new-tag>
```

## Smoke-test (do every time)

* `GET /api/v1/health` → 200, `X-Version` matches target
* One `tools/list` MCP call → expected tool catalog
* One `get_vcon` against a known UUID → returns the vCon
* One `search_vcons` with a known filter → returns expected count

If any check fails, roll back immediately (see below) before investigating.

## Rollback

```bash
# 1. Stop the new container
docker stop vconic && docker rm vconic

# 2. Restart the previous image
docker run -d --name vconic \
  --env-file /etc/vconic/env \
  -p 3000:3000 \
  public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:<previous-tag>
```

**Database rollback is harder.** Newly applied migrations are not automatically reversible. If the new build is incompatible with the old code:

1. Stop the new container.
2. Restore the database snapshot taken in step 3 of pre-upgrade.
3. Start the previous image against the restored database.

This is why the pre-upgrade snapshot is non-negotiable.

## Verifying after upgrade

Beyond the smoke-test:

* Check structured logs for new error codes you don't recognize.
* Run `get_database_health_metrics` — flag any recommendations that weren't there before the upgrade.
* Confirm tenant queries still scope correctly (RLS deployments).
* Watch latency dashboards for 24 hours before declaring success.

## See also

* [Release Notes](/vconic-for-resellers/07-release-notes.md)
* [Migration Guide](/reference/migration_guide.md)
* [Changelog](/reference/changelog.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://mcp.conserver.io/vconic-for-resellers/06-upgrade-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.