Upgrading from FlaskBB 2.x¶
FlaskBB 3.0 upgrades a 2.x installation in place. flaskbb db upgrade
migrates the database, including the settings, the groups and the data of the
official plugins, and a config file generated by FlaskBB 2.x keeps working.
Before you start¶
The migrations can’t be reverted. Back up
the database, e.g. with
pg_dumpor a copy of the SQLite file, andyour
flaskbb.cfg.
To go back to 2.x, restore both and reinstall your old FlaskBB version.
FlaskBB 3.0 needs Python 3.12 or newer, which usually means a new virtual environment. Stop FlaskBB and its Celery worker before you migrate.
Plugins written for FlaskBB 2.x only work with 3.0 if they have a release that supports it. Update them, or remove them from the environment before you start FlaskBB 3.0. The settings of a removed plugin stay in the database.
Install FlaskBB 3.0¶
For an installation from a Git checkout, as described in Production & Deployment, check out the new release and sync the environment with the extras you need:
$ git fetch --tags
$ git checkout v3.0.0
$ uv sync --no-dev --extra postgres
The extras are postgres for PostgreSQL, mysql for MySQL, gunicorn
for gunicorn and plugins for the official plugins that aren’t installed by
default. A checkout also has to compile the translations again, the files
FlaskBB 2.x compiled are outdated:
$ uv run flaskbb translations compile
To install FlaskBB from PyPI instead, create a new virtual environment and install it with the same extras, e.g.:
$ pip install "FlaskBB[postgres]"
The portal and conversations plugins are always installed with FlaskBB.
Configuration¶
FlaskBB 3.0 still loads a config file generated by FlaskBB 2.x and translates these settings to their new form:
CELERY_BROKER_URLandCELERY_RESULT_BACKENDare nowbroker_urlandresult_backendinCELERY_CONFIG:CELERY_CONFIG = { "broker_url": "redis://localhost:6379", "result_backend": "redis://localhost:6379", }
CACHE_TYPE = "simple"andCACHE_TYPE = "redis"are now"SimpleCache"and"RedisCache".RATELIMIT_STORAGE_URLwas renamed toRATELIMIT_STORAGE_URI.
The translation is deprecated and will be removed in FlaskBB 4.0, FlaskBB warns about each of these settings until you update it. Other changes:
WHOOSHEE_DIR,WHOOSHEE_MIN_STRING_LENandWHOOSHEE_WRITER_TIMEOUTare no longer used, see Search.TRUSTED_HOSTSis new and defaults toSERVER_NAME.AVATAR_UPLOAD_PATHandATTACHMENT_UPLOAD_PATHare new, see Uploads.The reCAPTCHA keys are managed in the admin panel again. Keys saved in a 2.0 or 2.1 admin panel are picked up by the migration, and
RECAPTCHA_PUBLIC_KEYandRECAPTCHA_PRIVATE_KEYfrom a 2.2 config are still used as long as the admin panel fields are empty.
To start with a new config instead, run flaskbb makeconfig and copy at
least SQLALCHEMY_DATABASE_URI, SECRET_KEY, WTF_CSRF_SECRET_KEY and
your mail and Redis settings from the old one. New secret keys log out every
user and invalidate the password reset and activation links sent before the
upgrade.
postgresql:// database URIs keep working with the psycopg driver of the
postgres extra. The mysql extra installs PyMySQL, which needs a
mysql+pymysql:// URI.
Migrate the database¶
Run the migrations with your config:
$ uv run flaskbb --config flaskbb.cfg db upgrade
This migrates FlaskBB and every enabled plugin. Among other things, it
moves the settings and the plugin settings into the new settings table, keeps their values and adds the settings that are new in 3.0,
turns the permission flags of every group, including your own groups, into roles and permissions,
migrates the private messages of the conversations plugin and
creates the full text search indexes and fills them with the existing topics and posts.
The command creates the app before it migrates, so it may log that a plugin
“stays disabled until its migrations are applied”. db upgrade applies
them, you can ignore that warning here.
After the upgrade¶
Start FlaskBB and its Celery worker again (flaskbb celery worker) and log
in as an administrator. On the first start, FlaskBB adds the new settings of
the enabled plugins.
Plugins¶
Plugins that were enabled in 2.x stay enabled. Plugins that you installed
with 3.0, e.g. through the plugins extra, are disabled until you enable
and install them in the admin panel or with:
$ uv run flaskbb plugins list
$ uv run flaskbb plugins enable like
$ uv run flaskbb plugins install like
See Plugins for more.
Search¶
The Whoosh search was removed, you can delete its whoosh_index directory.
With SEARCH_BACKEND = "sql", the default, FlaskBB searches the database
directly. "postgresql" and "sqlite" use the full text search of the
database. Their indexes were created and filled by db upgrade,
flaskbb reindex rebuilds them.
Uploads¶
Users can upload avatars and attach files to posts now, and avatar links set
in 2.x keep working. Uploads are stored in flaskbb/static/uploads unless
AVATAR_UPLOAD_PATH and ATTACHMENT_UPLOAD_PATH point somewhere else.
FlaskBB has to be able to write there, and the directory belongs in your
backups. If you installed FlaskBB with pip, point both settings outside of the
virtual environment, or the uploads are lost when FlaskBB is reinstalled.
Commands¶
flaskbb upgrade was removed. flaskbb db upgrade and the plugin commands
keep the settings up to date now.
Moving to Docker¶
The container images migrate an existing database before every start, see
Docker Deployment. To move a 2.x PostgreSQL database into the release stack,
create its dump with pg_dump --no-owner, copy SECRET_KEY and
WTF_CSRF_SECRET_KEY from your old config to SECRET_KEY and
CSRF_SECRET_KEY in docker/.env, and restore the dump before FlaskBB
starts:
$ docker compose -f docker/docker-compose.yaml up -d postgres
$ docker compose -f docker/docker-compose.yaml exec -T postgres sh -c \
'psql -U "$POSTGRES_USER" "$POSTGRES_DB"' < flaskbb.sql
$ docker compose -f docker/docker-compose.yaml up -d