Skip to content

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

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

Cydo73 wants to merge 7 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 a new page, "Upgrading and rolling back", to the self hosting docs. It covers:

  • what to do before an upgrade: release notes, the current Helm revision and a database backup
  • the upgrade command, and how migrations run (the migrate-db init container by default, and where to read its logs)
  • verifying the upgrade
  • why helm rollback does not revert the database, and a restore procedure that worked in testing
  • a troubleshooting table
  • the removal of the bundled InfluxDB in chart 0.85.0

How did you test this code?

I ran every command on a local kind cluster, upgrading chart 0.80.0 (Flagsmith 2.222.0) to chart 0.85.0 (Flagsmith
2.286.0) with default values and the PostgreSQL instance deployed by the chart. I took a pg_dump backup, upgraded (91
migrations applied), rolled back with helm rollback (Flagsmith 2.222.0 then failed with a missing table error), and
restored the backup, after which 2.222.0 worked again with the original data.

I ran npx prettier --check on the page and npm run build

Full write up with logs and screenshots: https://cydo73.github.io/Flagsmith-on-kubernetes/

Not tested: custom values, an external or managed database, the jobs.migrateDb Job, the analytics migration job,
other version pairs, and downtime during the upgrade. Happy to rerun any of these.

Tested: I retested the revised backup, verification, upgrade with --reset-then-reuse-values, rollback and restore commands on a fresh kind install.

@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.

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