Skip to main content

Upgrade from v3 to v4

This guide explains how to upgrade a Casdoor v3 deployment to v4 and what to check after the upgrade.


Learning outcomes​

  • Understand what changed between v3 and v4.
  • Choose a v4 release.
  • Upgrade a Docker, Helm, or source deployment.
  • Check the parts of your setup that the new frontend affects.
  • Go back to v3 if you have to.

What you need​

  • A Casdoor v3 deployment
  • A way to back up and restore its database

About v4​

Casdoor v4.0.0 was released on September 1, 2026. It replaces the admin console and the sign-in pages with a new frontend. The backend, the REST API, the database, and conf/app.conf are compatible with v3. Most deployments upgrade by switching the image tag or by rebuilding from source.

v3.164.0 is the last v3 release. Bug fixes and security fixes are published in v4 only.

Areav3v4
Frontend UIAnt Designshadcn/ui and Tailwind CSS
Frontend buildcreate-react-app (craco), JavaScriptVite, TypeScript
Build outputweb/build/static/js, web/build/static/cssweb/build/assets
Frontend sourceweb/web/ (the v3 frontend is kept in web-old/ for reference and is not built)
Backend, API, SDKsNo change needed
DatabaseNew tables and columns are created automatically on startup
conf/app.confaiAssistantUrl was removed and is ignored if still present

Choose a v4 release​

Upgrade to the latest v4 release. If you pin a version, use v4.6.0 or later. The first v4 releases had regressions, which are fixed in the following versions:

ProblemAffectedFixed in
No Docker image was publishedv4.1.0v4.2.0
Sign-in and sign-up page customization (custom HTML, sign-in items, custom CSS) was ignoredv4.0.0 – v4.1.0v4.2.0
Sign-in through an OIDC provider failed with Unknown column 'oidc'v4.0.0 – v4.1.0v4.2.0
Startup failed with MySQL Error 1118 on MySQL 8.0.46, 8.4.9 – 8.4.10 and 9.7.0 – 9.7.2v4.4.0v4.5.0
The UI was always in English instead of following the browser languageup to v4.5.0v4.6.0

v4.5.0 also fixes CVE-2026-5469, CVE-2026-9091, CVE-2026-9093, CVE-2026-9096, CVE-2026-9097, and CVE-2026-9098.

Prepare the upgrade​

  1. Check the version that you run. See Version information.

    curl http://localhost:8000/api/get-version-info
  2. Back up the database. Casdoor adds tables and columns when v4 starts. The backup is your way back to v3.

  3. If you customized a sign-in page with CSS or HTML, take a screenshot of it, so that you can compare the page after the upgrade.

Upgrade Casdoor​

Keep the same app.conf and the same database.

Upgrade a Docker deployment​

  1. Pull the new image:

    docker pull casbin/casdoor:latest
  2. Restart the container with the new image.

With Docker Compose, update image: and run docker compose up -d. With Helm, set the new image tag and run helm upgrade.

Upgrade a source deployment​

Pull the code, rebuild the frontend, and restart the server. The commands are the same as in v3. Node.js 20 and Yarn 1.x are still the required versions.

git pull
cd web && yarn install && yarn build && cd ..
go build && ./casdoor

In development, yarn start still serves the frontend on port 7001.

Check the result​

Static file paths​

The hashed .js and .css files moved from web/build/static/js and web/build/static/css to web/build/assets. Update everything that refers to the old paths:

  • Reverse proxy rules: Rules that cache or rewrite /static/js/ or /static/css/ must use /assets/ instead.
  • CDN: If a CDN hosts the frontend files, run the upload script again after you build v4. See Host the frontend files on a CDN.

Sign-in page customization​

Casdoor v4 applies the custom HTML, the sign-in items, and the theme settings of an application as before.

Review your custom CSS. The pages are no longer built from Ant Design components, so selectors that target Ant Design class names, such as .ant-btn or .ant-input, no longer match anything. Open the sign-in, sign-up, and forgot-password pages of each customized application and adjust the CSS on the UI Customization tab of the application.

Modified frontend code​

If you maintain a fork with changes under web/, those changes don't carry over. The v3 code is in web-old/, so that you can read your old changes next to the new code, but Casdoor builds and serves only web/. Port your changes to the TypeScript sources in web/src.

Applications that use Casdoor​

Nothing changes for your applications. OAuth 2.0, OpenID Connect (OIDC), SAML, CAS, LDAP, and the REST API behave as in v3, and the SDKs don't need an update.

Roll back to v3​

  1. Stop Casdoor.
  2. Restore the database backup.
  3. Start the v3 image or binary that you ran before.

Get help​

If something worked in v3 and doesn't work in v4, open an issue with both version numbers and your database type.

See also​