Skip to content

docs: add self-hosted upgrade and rollback guide - #8890

Open
Cydo73 wants to merge 8 commits into
Flagsmith:mainfrom
Cydo73:docs/self-hosted-upgrade-guide
Open

Cydo73 wants to merge 8 commits into
Flagsmith:mainfrom
Cydo73:docs/self-hosted-upgrade-guide

Conversation

@Cydo73

@Cydo73 Cydo73 commented Nov 5, 2026 •

Copy link
Copy Markdown

Thanks for submitting a PR! Please check the boxes below:

  • I have read the Contributing Guide.
  • I have added information to docs/ if required so people know about the feature.
  • I have filled in the "Changes" section below.
  • I have filled in the "How did you test this code" section below.

Contributes to #7429

Changes

Adds Helm specific upgrade and rollback steps to the existing Upgrades and Rollbacks page, and removes the standalone upgrading page.

What changed

  • New section "Upgrading and Rolling Back with Helm" in upgrades-and-rollbacks.md: before you upgrade, the Helm upgrade command, how migrations run, verifying the upgrade, rolling back, and troubleshooting.
  • A diagram showing the application and database at each stage of an upgrade and rollback.

How I tested
Local kind cluster, default values, chart 0.80.0 (Flagsmith 2.222.0) upgraded to chart 0.85.0 (Flagsmith 2.286.0), then rolled back. I ran the rollback test twice, the second time from a fresh install with a database backup taken first.

Results

  • helm rollback on its own leaves the older application running against the newer schema. The API log shows the ProgrammingError quoted in the page, and the dashboard shows a misleading permissions message.
  • rollbackmigrationsafter is not recognised on 2.286.0. The command available there is rollbackmigrationsappliedafter, which takes the time in ISO format.
  • rollbackmigrationsappliedafter stopped partway both times, at experimentation.0014_drop_ingestion_infrastructure_and_delivery_log, with FieldDoesNotExist: WarehouseDeliveryLog has no field named 'connection'. Migration counts were 526 before the upgrade, 617 after it, and 598 after the failed rollback. After helm rollback the older application still ran and flags could be created. The page tells readers to restore their backup if the command fails partway.

Not tested
Custom values, an external or managed database, the jobs.migrateDb Job, the analytics migration, other version pairs, and downtime during a rolling upgrade.

@Cydo73
Cydo73 requested a review from a team as a code owner November 5, 2026 21:44
@Cydo73
Cydo73 requested review from Holmus and removed request for a team November 5, 2026 21:44
@vercel

vercel Bot commented Nov 5, 2026

Copy link
Copy Markdown

@Cydo73 is attempting to deploy a commit to the Flagsmith Team on Vercel.

A member of the Team first needs to authorize it.

@github-actions github-actions Bot added the docs Documentation updates label Nov 5, 2026
@coderabbitai

coderabbitai Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Explain Change →

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • Resume reviews
  • Trigger review

No actionable comments were generated in the recent review.

Walkthrough

The change adds a self-hosted Helm upgrade and rollback guide. It describes database backup, upgrade settings, migration checks, and deployment verification. It explains that chart rollback does not reverse database migrations and provides a tested database restore procedure. The guide also lists troubleshooting steps, chart 0.85.0 analytics-storage options, and configurations and scenarios that were not tested.

Estimated code review effort: 2 (Simple) | ~8 minutes

Merge Risk: Low · previous review d49da

This guide adds a self-hosted upgrade and rollback procedure. A few documented steps could trip up operators: the backup is staged inside the database pod, the analytics migration is only partly described, the scratch-database cleanup relies on a written warning rather than chained commands, and the task processor may not be restarted after a restore. Review these gaps before merging; the guide marks the affected scenarios as untested.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: 1a193799-d8b1-48e2-a47c-2f59b5acb723
Commits

Reviewing files that changed from the base of the PR and between 225825f and d49da3d.

Files selected for processing: 1

  • docs/docs/deployment-self-hosting/upgrading.md

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 5 remain after this review.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 12

Review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: 21fcfeb9-050b-457d-a11f-3b57776d70c2
Commits

Reviewing files that changed from the base of the PR and between 5051ac2 and a96256c.

Files ignored due to path filters: 1

  • docs/docs/diagrams/upgrade-rollback-restore.svg is excluded by !**/*.svg
Files selected for processing: 1

  • docs/docs/deployment-self-hosting/upgrading.md

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

@germangarces

Copy link
Copy Markdown
Member

Thanks a lot, @Cydo73 . Could you take a look at CodeRabbit's comments before I jump in, please?

@Cydo73

Cydo73 commented Nov 10, 2026

Copy link
Copy Markdown
Author

Thanks @germangarces. I'm working through CodeRabbit's comments now. Most are fair and I'll fix them, and I'll retest the changed backup and restore commands before pushing. I'll answer two with my reasons instead of applying them as suggested. I'll ping you once it's updated.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

Additional comments: 1

docs/docs/deployment-self-hosting/upgrading.md-209-209: 1

209-209: Major · Security & Privacy · Heavy lift

Unverified finding
Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.

Restore database-level settings and privileges.

If the original database restricts CONNECT or has database-specific settings, recreating it with createdb loses those attributes. This pg_restore command does not restore them without --create. The replacement can therefore have different access controls or settings after rollback. Preserve and restore those attributes as part of the procedure. (postgresql.org)

Review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: 012f95ae-1f23-4f74-ba7f-1e12659ceefb
Commits

Reviewing files that changed from the base of the PR and between a96256c and d24ee25.

Files selected for processing: 1

  • docs/docs/deployment-self-hosting/upgrading.md

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 2 files

Reply to a comment to ask cubic a question or push back. It learns from your replies.
Click Fix with cubic on a comment, or reply @cubic-dev-ai fix this, and cubic writes the fix.

View guided diff | Re-trigger cubic

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 1 file (changes from recent commits).

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

Review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: 5c8be259-559f-4fc6-9f68-2e9c64edefde
Commits

Reviewing files that changed from the base of the PR and between d24ee25 and ed22924.

Files selected for processing: 1

  • docs/docs/deployment-self-hosting/upgrading.md

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

  • Automated review surfaced no issues in the provided summaries.
  • No files require special attention.

Requires human review: Auto-approval blocked by 3 unresolved issues from previous reviews.

View guided diff | Re-trigger cubic

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 1 file (changes from recent commits).

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

  • Automated review surfaced no issues in the provided summaries.
  • No files require special attention.

Requires human review: Auto-approval blocked by 3 unresolved issues from previous reviews.

View guided diff | Re-trigger cubic

@Cydo73

Cydo73 commented Nov 16, 2026

Copy link
Copy Markdown
Author

@germangarces Thanks for your patience. I’ve pushed a final update that addresses CodeRabbit’s and cubic’s comments, and I’ve replied on each thread. Where I didn’t apply a suggestion as written, I explained why in the thread. The commands were retested on a fresh kind install, and the later changes are wording only. Setups I couldn’t test, such as the task processor, autoscaling and external databases, are marked as not tested on the page. The full test report is linked in the description. Please take another look when you have time.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

  • Automated review surfaced no issues in the provided summaries.
  • No files require special attention.

Requires human review: Auto-approval blocked by 2 unresolved issues from previous reviews.

Re-trigger cubic

@Cydo73

Cydo73 commented Nov 17, 2026

Copy link
Copy Markdown
Author

@germangarces All review comments are now addressed and the threads are resolved, so it’s ready for another look whenever you have time. If there are other gaps in the self-hosting docs that need filling, I’d be glad to help with them. Thank you for your guidance on this.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0 issues found across 3 files (changes from recent commits).

Confidence score: 5/5

  • Automated review surfaced no issues in the provided summaries.
  • No files require special attention.

Requires human review: Auto-approval skipped because this PR is from an external contributor.

Re-trigger cubic

@Cydo73

Cydo73 commented Nov 19, 2026

Copy link
Copy Markdown
Author

Hi @germangarces, thank you for the detailed review. I've pushed an update that covers all of your comments. The Helm steps now live in upgrades-and-rollbacks.md and upgrading.md is gone, the testing notes have moved to the PR description, the backup step is one line with the PostgreSQL link, the chart 0.85.0 section is removed, and the SVG metadata is stripped.

I retested the rollback on a kind cluster, chart 0.80.0 (Flagsmith 2.222.0) to 0.85.0 (2.286.0), and found two things I wanted you to see.

First, the command name. On 2.286.0, rollbackmigrationsafter returns "Unknown command", and Django suggests rollbackmigrationsappliedafter. That is the only rollback command listed by manage.py help. My section uses it, with the time in ISO format. I left the existing lines on the page alone, so they still use the other name. Could you tell me which one is right for which versions?

Second, the command stopped partway. With a UTC time just before the upgrade, it unapplied 19 migrations and then failed at experimentation.0014_drop_ingestion_infrastructure_and_delivery_log with "FieldDoesNotExist: WarehouseDeliveryLog has no field named 'connection'". I got the same result twice, the second time from a fresh install with a backup taken first. The older version still ran afterwards and I could create flags, but the database was only partly rolled back. So I added a line to the page saying to restore the backup if the command fails.

Is this a known limitation for this version pair, or would you like me to open an issue? I only tested this one pair with default values, and I can share the full output.

Ready for another look whenever you have time. Thanks again.

@Cydo73
Cydo73 requested a review from germangarces November 19, 2026 13:13
@germangarces

germangarces commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Hi @Cydo73, thanks for your patience!

First, the command name. On 2.286.0, rollbackmigrationsafter returns "Unknown command", and Django suggests rollbackmigrationsappliedafter. That is the only rollback command listed by manage.py help. My section uses it, with the time in ISO format. I left the existing lines on the page alone, so they still use the other name. Could you tell me which one is right for which versions?

Yeah, sorry. The command is rollbackmigrationsappliedafter.

Second, the command stopped partway. With a UTC time just before the upgrade, it unapplied 19 migrations and then failed at experimentation.0014_drop_ingestion_infrastructure_and_delivery_log with "FieldDoesNotExist: WarehouseDeliveryLog has no field named 'connection'". I got the same result twice, the second time from a fresh install with a backup taken first. The older version still ran afterwards and I could create flags, but the database was only partly rolled back. So I added a line to the page saying to restore the backup if the command fails.

Is this a known limitation for this version pair, or would you like me to open an issue? I only tested this one pair with default values, and I can share the full output.

Actually, it is a known limitation. The issue is fixed in #8750 (release 2.287.0)

Good catch. I forgot about it; We'd appreciate it if you can add it!

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation updates

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants