This is an automated email from the ASF dual-hosted git repository. asf-gitbox-commits pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/allura.git
commit 35289fd7a0d814e74ace616600ca28ef46dceba0 Author: Dave Brondsema <[email protected]> AuthorDate: Tue Jun 16 11:58:07 2026 -0400 [#8611] documentation and migration scripts --- Allura/development.ini | 2 +- Allura/docs/getting_started/installation.rst | 14 ++++++ Allura/production-docker-example.ini | 4 ++ CHANGES | 26 +++++++++++ scripts/migrations/035-field-encryption.sh | 22 +++++++++- scripts/migrations/036-field-encryption-cleanup.sh | 51 ++++++++++++++++++++++ 6 files changed, 116 insertions(+), 3 deletions(-) diff --git a/Allura/development.ini b/Allura/development.ini index cb356cc81..a76316620 100644 --- a/Allura/development.ini +++ b/Allura/development.ini @@ -77,7 +77,7 @@ site_name = Allura ; Change these to your website's domain domain = localhost ; Change this to your website's full URL -; Make sure the csp.form_action_url match to the base_url +; Make sure the csp.form_action_urls match to the base_url base_url = http://localhost:8080 ; Change this to configure your image path and redirect link diff --git a/Allura/docs/getting_started/installation.rst b/Allura/docs/getting_started/installation.rst index 8a194e612..b6823ccfc 100644 --- a/Allura/docs/getting_started/installation.rst +++ b/Allura/docs/getting_started/installation.rst @@ -258,6 +258,20 @@ You can use the following command to generate a good key: ~$ python -c 'import secrets; print(secrets.token_hex());' +Set a secret key used for MongoDB field-level encryption. + +.. code-block:: ini + + ming.main.encryption.kms_providers.local.key = <secret-key> + ming.project.encryption.kms_providers.local.key = <secret-key> + ming.task.encryption.kms_providers.local.key = <secret-key> + +Use the same key for all 3 (but different than the beaker key). You can use the following command to generate a good key: + +.. code-block:: bash + + ~$ python -c 'import base64, secrets; print(base64.b64encode(secrets.token_bytes(96)).decode())' + Production-quality web server ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Allura/production-docker-example.ini b/Allura/production-docker-example.ini index 6ee0ddcee..e2f944e08 100644 --- a/Allura/production-docker-example.ini +++ b/Allura/production-docker-example.ini @@ -26,6 +26,10 @@ ; smtp_server ; session.jwt_secret_keys ; session.secure +; csp.form_action_urls +; ming.main.encryption.kms_providers.local.key +; ming.project.encryption.kms_providers.local.key +; ming.task.encryption.kms_providers.local.key ; ; This file inherits settings from docker-dev.ini and development.ini ; You are free to make additional changes/additions to this file for other settings diff --git a/CHANGES b/CHANGES index 62c0fa617..f4c5e7276 100644 --- a/CHANGES +++ b/CHANGES @@ -1,5 +1,31 @@ NEXT RELEASE +Upgrade Instructions + + Stop any running Allura services while upgrading. + + Install updated dependencies by running: + pip install -r requirements.txt --no-deps --upgrade --upgrade-strategy=only-if-needed + + In your .ini file, set csp.form_action_urls to your base URL. + + In your .ini file, enable or disable importers like Trac importer as you see fit (see disable_entry_points lines in development.ini) + + Field-level mongo encryption setup: + Copy the new `ming.*encryption*` lines from development.ini to your own .ini file. + Generate a secret key with: python -c 'import base64, secrets; print(base64.b64encode(secrets.token_bytes(96)).decode())' + Put that secret key in your .ini file in 3 spots: + ming.main.encryption.kms_providers.local.key = ... + ming.project.encryption.kms_providers.local.key = ... + ming.task.encryption.kms_providers.local.key = ... + + Run scripts/migrations/035-field-encryption.sh If using docker, this is the full command (replace your .ini file path): docker compose run -e INI=docker-dev.ini --rm taskd ../scripts/migrations/035-field-encryption.sh + + Run: `paster ensure_index development.ini --clean` in Allura dir. Replace your .ini file path + + After new version of Allura is up and running, delete the plaintext versions of the encrypted fields by running scripts/migrations/036-field-encryption-cleanup.sh + + * [#8583] Add support for Python 3.13 * [#8598] Upgrade Underscore Library diff --git a/scripts/migrations/035-field-encryption.sh b/scripts/migrations/035-field-encryption.sh index be72ed829..0a5d99b6e 100755 --- a/scripts/migrations/035-field-encryption.sh +++ b/scripts/migrations/035-field-encryption.sh @@ -1,3 +1,4 @@ +#!/bin/bash # # Licensed to the Apache Software Foundation (ASF) under one # or more contributor license agreements. See the NOTICE file @@ -17,7 +18,6 @@ # under the License. # -#!/bin/bash set -euo pipefail BASEDIR=$(dirname "$0") @@ -30,4 +30,22 @@ if [ -z "$INI" ]; then read -rp "Enter the path to the Allura INI file (or provide as env var): " INI fi -paster script $INI ../scripts/convert_encrypted_field.py -- --remove-unencrypted forgediscussion.model.forum.Forum monitoring_email +export PYTHONWARNINGS="${PYTHONWARNINGS:-ignore:pkg_resources is deprecated as an API:UserWarning}" + +CMD="paster script $INI ../scripts/convert_encrypted_field.py" + +$CMD forgediscussion.model.forum.Forum monitoring_email && \ +$CMD forgeblog.model.blog.BlogPostSnapshot author.username && \ +$CMD forgeblog.model.blog.BlogPostSnapshot author.display_name && \ +$CMD forgeblog.model.blog.BlogPostSnapshot author.logged_ip && \ +$CMD allura.model.discuss.PostHistory author.username && \ +$CMD allura.model.discuss.PostHistory author.display_name && \ +$CMD allura.model.discuss.PostHistory author.logged_ip && \ +$CMD forgewiki.model.wiki.PageHistory author.username && \ +$CMD forgewiki.model.wiki.PageHistory author.display_name && \ +$CMD forgewiki.model.wiki.PageHistory author.logged_ip && \ +$CMD forgetracker.model.ticket.TicketHistory author.username && \ +$CMD forgetracker.model.ticket.TicketHistory author.display_name && \ +$CMD forgetracker.model.ticket.TicketHistory author.logged_ip && \ +$CMD allura.model.auth.EmailAddress email && \ +$CMD allura.model.auth.User display_name diff --git a/scripts/migrations/036-field-encryption-cleanup.sh b/scripts/migrations/036-field-encryption-cleanup.sh new file mode 100755 index 000000000..42c40a54b --- /dev/null +++ b/scripts/migrations/036-field-encryption-cleanup.sh @@ -0,0 +1,51 @@ +#!/bin/bash +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# + +set -euo pipefail + +BASEDIR=$(dirname "$0") +ALLURA_DIR=$(realpath "$BASEDIR/../../Allura") +cd "$ALLURA_DIR" + +# get INI from environment or prompt for input: +INI=${INI:-} +if [ -z "$INI" ]; then + read -rp "Enter the path to the Allura INI file (or provide as env var): " INI +fi + +export PYTHONWARNINGS="${PYTHONWARNINGS:-ignore:pkg_resources is deprecated as an API:UserWarning}" + +CMD="paster script $INI ../scripts/convert_encrypted_field.py -- --remove-unencrypted" + +$CMD forgediscussion.model.forum.Forum monitoring_email && \ +$CMD forgeblog.model.blog.BlogPostSnapshot author.username && \ +$CMD forgeblog.model.blog.BlogPostSnapshot author.display_name && \ +$CMD forgeblog.model.blog.BlogPostSnapshot author.logged_ip && \ +$CMD allura.model.discuss.PostHistory author.username && \ +$CMD allura.model.discuss.PostHistory author.display_name && \ +$CMD allura.model.discuss.PostHistory author.logged_ip && \ +$CMD forgewiki.model.wiki.PageHistory author.username && \ +$CMD forgewiki.model.wiki.PageHistory author.display_name && \ +$CMD forgewiki.model.wiki.PageHistory author.logged_ip && \ +$CMD forgetracker.model.ticket.TicketHistory author.username && \ +$CMD forgetracker.model.ticket.TicketHistory author.display_name && \ +$CMD forgetracker.model.ticket.TicketHistory author.logged_ip && \ +$CMD allura.model.auth.EmailAddress email && \ +$CMD allura.model.auth.User display_name
