========= Upgrading ========= .. contents:: :local: :backlinks: none :depth: 2 .. _safe_upgrade_docker: Recommended upgrade procedure ============================= .. warning:: We strongly recommend that you have a staging Fleio installation and that you test upgrades in your staging environment before upgrading your Fleio production installation. You are entitled to one development/staging license for each license that you purchase. This document lists Fleio versions that require simple manual steps. When upgrading, you do not have to upgrade to each individually released version, you can jump versions. However, we recommend that you upgrade to each Fleio version that requires manual steps. Validate that your installation is working correctly after each upgrade, then perform the next upgrade. If your installation has :ref:`custom code that changes the standard Fleio Docker images`, new versions of Fleio may not be compatible with your custom code. Before upgrading your Fleio production installation, use a staging Fleio installation and validate that your customizations are working with new Fleio versions. The database is automatically backed by the ``fleio upgrade`` script. Backups are placed in ``/home/fleio/backup/``. The Fleio upgrade script waits for running tasks to complete since version 2022.09, and performs an automatic backup since version 2022.10. To safely upgrade to a version older than 2022.09, see previous documentation versions. For how to use the ``fleio upgrade`` command, see next section, :ref:`how-to-upgrade-docker`. .. _how-to-upgrade-docker: How to upgrade Fleio ==================== .. warning:: When upgrading Fleio, we always recommend you to follow the :ref:`safe_upgrade_docker` procedure. .. note:: By convention, Fleio versions ending in *.0* are BETA versions and are not recommended for production. Fleio versions ending in *.1*, *.2*, etc., are stable versions and are recommended for production. For example, *2023.08.0* and *2023.09.0* are BETA versions, while *2023.08.1* and *2023.09.1* are stable versions. You can list available newer stable versions by running: .. code-block:: bash fleio updates If you want to include beta versions in the list, use the ``--include-beta`` (or ``-b``) flag: .. code-block:: bash fleio updates --include-beta fleio upgrade --include-beta To upgrade Fleio to the latest stable version run: .. code-block:: bash fleio upgrade If you want to upgrade to a specified version, you need to pass the Fleio version as argument. To check what versions are available, run: .. code-block:: bash fleio updates --include-beta Creating fleio_utils_run ... done Current version: 2021.01.2 Available updates: 2021.03.1 2021.03.0 2021.02.1 2021.02.0 Then you upgrade to the specified Fleio version: .. code-block:: bash fleio upgrade 2023.09.1 .. _upgrade-2024.04: Upgrading to 2024.04 ==================== Warnings about `version` being obsolete in `docker-compose.override.yml` files may appear when upgrading so you should remove ``version: "3.7"`` line from `/home/fleio/compose/docker-compose.override.yml` file. .. _upgrade-2024.03: Upgrading to 2024.03 ==================== Instance pricing rules now support filters and modifiers based on instance "image_id" attribute. For instances created before Fleio version 2024.03, a one-time ``fleio sync --instances`` must be run after the upgrade for the new billing attribute to work. Instances created after the upgrade will automatically work and require no action. .. _upgrade-2024.01: Upgrading to 2024.01 ==================== If you are using custom themes, you must build them again following the updated documentation: :doc:`/developer/frontend-customization`. Angular was updated in Fleio 2024.01 so the new versions to be used are ``@angular/cli@17.0.7`` and ``@angular/material@17.0.4``. Also note the generated theme location will look like this: ``project/dist/project/browser/styles-xxxxxxxx.css``. All other steps are the same. Support for Ubuntu 18.04 was dropped since Ubuntu 18.04 is end of life. If you are still using Ubuntu 18.04 and you want to upgrade to 2024.01 from a version older than 2023.11 you will need to upgrade first to 2023.11 and then to 2024.01. Fleio was tested with Stripe API version ``2023-10-16`` and we recommend you to use this version in your Stripe account. .. _upgrade-2023.12: Upgrading to 2023.12 ==================== Service unsuspend API endpoint changed from `staffapi/billing/services/SERVICE_ID/resume` to `staffapi/billing/services/SERVICE_ID/unsuspend`. If you are using fleio-whmcs plugin, you must update it to v3.0.0. .. _upgrade-2023.11: Upgrading to 2023.11 ==================== If you are using load balancers, you must ensure that ``load-balancer_admin`` and ``creator`` roles are selected in **Default role names** dropdown on :ref:`OpenStack settings - Defaults` tab. .. _upgrade-2023.09: Upgrading to 2023.09 ==================== If you have created a custom frontend theme, you need to rebuild it using latest Angular versions according to the 2023.09 note in :ref:`add-new-themes-2023-03`. .. _upgrade-from-2023.08: Upgrading FROM 2023.08 ====================== Due to a bug, if you are upgrading from 2023.08.1 you must specify the version you are upgrading to. ``fleio upgrade`` or ``fleio upgrade --include-beta`` will not work if your currently installed version is 2023.08.1. Upgrade is working if you specify version, e.g.: .. code-block:: bash # you must specify version on upgrade if your currently installed version is 2023.08.1 fleio upgrade 2023.09.1 .. _upgrade-2023.05: Upgrading to 2023.05 ==================== "Notification templates" was renamed to "Message templates". You may need to update any references you used in your custom code: * feature `settings.notifications.templates` was renamed to `settings.message_templates`, you need to update it if you have added the override in ``settings.py`` in the past * `DEFAULT_NOTIFICATION_TEMPLATE_LANGUAGE_CODE` setting was renamed to `DEFAULT_MESSAGE_TEMPLATE_LANGUAGE_CODE`, update ``settings.py`` if you are using it there * API endpoint changed from `backend_url/staffapi/notification_templates` to `backend_url/staffapi/message_templates` * if you have overridden the staff menu in ``settings.py``, you need to update the entry as follows (entry label, feature name, frontend route and permission name changed): .. code-block:: python MenuItem(label=_('Message templates'), icon='notifications', feature='settings.message_templates', angular_route='settings/message-templates', related_permission='messagetemplates.list'), ``Text input`` configurable option widget type was removed and any configurable options with this widget will be removed during upgrade process - all data associated with these options will be lost. .. _upgrade-2023.03: Upgrading to 2023.03 ==================== If you have created a custom frontend theme, you need to update the theme code according to :ref:`frontend-custom`. .. _upgrade-2023.02: Upgrading to 2023.02 ==================== If you have created a custom frontend theme, you need to update the theme code according to :ref:`2023.02-or-newer`. .. _upgrade-2022.12: Upgrading to 2022.12 ==================== If you have customized the password complexity requirements in your :ref:`settings.py file`, you need to update those customization according to the latest format from :ref:`password-settings`. Pay attention to the ``... .format(...)`` part that was removed. .. _upgrade-2022.11: Upgrading to 2022.11 ==================== Before upgrading to 2022.11 --------------------------- Install Docker Compose plugin (V2) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ On some systems, it may be required to manually install Docker Compose V2. To do this, run one of the following commands. On Debian/Ubuntu run: .. code-block:: bash # for Debian and Ubuntu: sudo apt-get install docker-compose-plugin On RHEL/CentOS/Rocky Linux/AlmaLinux run: .. code-block:: bash # for RHEL/CentOS/Rocky Linux/AlmaLinux: sudo yum install docker-compose-plugin Add Docker Compose pull_policy ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you are using ``docker-compose.override.yml`` to build custom images you need to add ``pull_policy: never`` to the service definition before upgrading. For some examples of using ``pull_policy`` in ``docker-compose.override.yml``, see :ref:`change-docker-files`. After upgrade to 2022.11 ------------------------ Sync OpenStack ^^^^^^^^^^^^^^ After upgrading to 2022.11 you must perform a :ref:`manual-sync`, since new "region" fields were added in the Fleio database to volume availability zones (AZ) and router AZ. Until you sync, the volume creation form and the router creation form will miss the AZ fields. Remove docker-compose (v1) ^^^^^^^^^^^^^^^^^^^^^^^^^^ Starting with 2022.11 release we only use Docker Compose V2 (https://docs.docker.com/compose/), which supports the compose command as part of the Docker CLI. Thus, we have replaced ``docker-compose`` commands with ``docker compose``. If you're using the ``docker-compose`` command internally, you should switch to Docker Compose plugin (``docker compose`` command). Because Compose V1 (``docker-compose``) is now deprecated, we also strongly recommend that you remove related files: .. code-block:: bash sudo rm -rf /usr/bin/docker-compose \ /usr/local/bin/docker-compose \ /etc/bash_completion.d/docker-compose With the new Docker Compose plugin you will notice that container names do not use underscore (``_``) as separator anymore but the hyphen-minus (``-``) character (e.g. ``fleio_backend_1`` becomes ``fleio-backend-1``). Update incomingmail container name in mail server aliases ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you are using the support ticketing system feature, and you have mail server aliases define on the host, you need to update the container name in the aliases file from ``fleio_incomingmail_1`` to ``fleio-incomingmail-1``. For instructions to update the mail server aliases file, see See :ref:`ticket-mail-pipe`. .. _upgrade-2022.10: Upgrading to 2022.10 ==================== In the 2022.10 release we configured Fleio logger to send emails to admins in case an error is logged. In order for this to work for existing installation you need to add ADMINS setting to settings.py (see https://docs.djangoproject.com/en/4.1/ref/settings/#admins). Also, we have added a fix for an issue with ``update_exchange_rates_task_at_midnight`` schedule. If you intend to use this task we suggest you use corrected schedule for it as defined in the comment below: .. code-block:: python 'update_exchange_rates_task_at_midnight': { 'task': 'Update exchange rates task', 'schedule': crontab(hour='0', minute='0') }, ``docker-compose.utils.yml`` file was also removed. ``utils`` container is now defined in ``docker-compose.yml`` file. If you have any customizations to utils container in ``docker-compose.utils.override.yml`` file you should move those to ``docker-compose.override.yml`` file. .. _upgrade-2022.09: Upgrading to 2022.09 ==================== In the 2022.09 release we have added a fix for multiple problems with the processing incoming email when emojis where used in the ticket subject or body. The fix must be applied on your ``settings.py`` file, as it's related to the database options. In order to edit the settings.py file, please run ``fleio edit settings.py`` and look for the ``DATABASES`` dictionary: .. code-block:: python DATABASES = { 'default': { 'ENGINE': 'django.db.backends.mysql', 'NAME': 'fleio', 'USER': 'root', 'PASSWORD': '', 'HOST': 'localhost', 'PORT': '3306', 'CONN_MAX_AGE': 500, 'OPTIONS': { 'init_command': "SET sql_mode='STRICT_ALL_TABLES'", }, }, } In the ``OPTIONS`` part, you need to add the ``charset``: .. code-block:: python ... 'OPTIONS': { 'charset': 'utf8mb4', 'init_command': "SET sql_mode='STRICT_ALL_TABLES'", }, ... In the 2022.09 release we also introduced a new periodic task, which will clear the expired Django sessions / Fleio tokens. If you've overwritten the ``CELERY_BEAT_SCHEDULE`` dictionary (in order to change how often a periodic task runs), then you will have to update it, in your settings.py file. The new ``CELERY_BEAT_SCHEDULE`` should be the following: .. code-block:: python CELERY_BEAT_SCHEDULE = { 'process_clients_task_every_15_minutes': { 'task': 'Process clients task', 'schedule': crontab(minute='*/15') }, 'collect_traffic_data_task_every_15_minutes': { 'task': 'Collect traffic data task', 'schedule': crontab(minute='*/15') }, 'update_exchange_rates_task_at_midnight': { 'task': 'Update exchange rates task', 'schedule': crontab() }, 'process_scheduled_backups_task_every_15_minutes': { 'task': 'Process scheduled backups task', 'schedule': crontab(minute='*/15') }, 'sync_hypervisors_task_every_60_minutes': { 'task': 'Hypervisors background synchronization', 'schedule': crontab(minute='*/60') }, 'clear_expired_sessions_every_12_hours': { 'task': 'Clear expired sessions task', 'schedule': crontab(hour='*/12') }, } In 2022.09 release we also merged end-user's ``openstack/billing/history`` API into ``openstack/billing`` and staff's ``billing/usage-history`` API into ``billing/usage`` API. If you've made any changes, or you have any scripts that pull information using these APIs, you will have to adapt them. .. _upgrade-2022.04: Upgrading to 2022.04 ==================== In the 2022.04 release we have upgraded the Fleio backend dependencies. With this upgrade, we also moved to django 4.0, where ``PASSWORD_RESET_TIMEOUT_DAYS`` setting was removed. If you're aware that you changed the ``PASSWORD_RESET_TIMEOUT_DAYS`` time by redefining the variable in your settings.py, then you need to remove it and use the ``PASSWORD_RESET_TIMEOUT`` variable. Note that the new variable uses seconds while the old one used days. If you're using the ``CSRF_TRUSTED_ORIGINS`` setting, then you will need to also include the scheme (``http://`` or ``https://``) .. _upgrade-2021.12.0: Upgrading to 2021.12 ==================== In the 2021.12 release we have changed the ``utils`` menu option to ``utilities``. If you redefined the Fleio menu in settings.py, you will have to rename all ``utils/xxx`` angular_route parameters to ``utilities/xxx``. .. _upgrade-2021.11: Upgrading to 2021.11 ==================== In the 2021.11.0 release we have removed the "state" parameter from the MenuItem classes in their definition of menu in ``settings.py``. If you redefined the Fleio menu in settings.py, you will have to remove all traces of the 'state' parameter. For example, Networks menu changed from: .. code-block:: python MenuItem(label=_('Networks'), state='openstackNetworks', icon='networks', feature='openstack.networks', angular_route='openstack/networks', related_permission='networks.list'), to .. code-block:: python MenuItem(label=_('Networks'), icon='networks', feature='openstack.networks', angular_route='openstack/networks', related_permission='networks.list'), Another thing that was removed in the 2021.11.0 release is "minTTL" frontend setting. In order to configure a minimum TTL you need to add the following variable in the settings.py: .. code-block:: python DNS_ENDUSER_MIN_TTL = 300 Replace ``300`` with the desired value. In 2021.11.0 we also added a new dark theme. For existing installations, you will have to manually add the theme in the enduser and staff panels, by running the following commands: .. code-block:: bash fleio edit enduser.config.json fleio edit staff.config.json fleio edit reseller.config.json Then, in the ``availableThemes`` list, add "dark": .. code-block:: python "availableThemes": [ "spring", "navy", "dusk", "dark" ], .. _upgrade-2021.10: Upgrading to 2021.10 ==================== In the 2021.10 release we have added new filters and modifiers. If you're upgrading from a previous Fleio version, then you will not be able to configure them until you will add the new filters and modifiers into Fleio. First, you will have to enable django admin. Please see :ref:`enable_django_admin`. Next step is to access the django admin, which should be available at {{ your configured frontend url }}/backend/admin If you are asked to log in, then you will have to use your administrator credentials. Navigate to Billing app -> billing resources -> Instance and in the ``definition`` field, replace all its contents with the one from below (has_boot_volume is the new entry that was added). .. code-block:: python { "attributes": [ { "type": "string", "name": "availability_zone" }, { "type": "string", "name": "instance_type" }, { "type": "string", "name": "display_name" }, { "type": "datetime", "name": "launched_at" }, { "type": "string", "name": "state" }, { "type": "integer", "name": "vcpus" }, { "type": "integer", "name": "root_gb", "value_size": "g" }, { "value_size": "m", "name": "memory_mb", "type": "integer" }, { "type": "string", "name": "os_type" }, { "type": "string", "name": "instance_id" }, { "type": "string", "name": "tenant_id" }, { "type": "string", "name": "host" }, { "type": "string", "name": "has_boot_volume" }, { "type": "integer", "name": "ephemeral_gb", "value_size": "g" }, { "type": "string", "name": "region" } ] } Save and navigate to Billing app -> billing resources -> Volume and in the ``definition`` field replace the contents with the following (related_instance_flavor new entry was added): .. code-block:: python { "attributes": [ { "value_size": "g", "type": "integer", "name": "size" }, { "type": "string", "name": "availability_zone" }, { "type": "datetime", "name": "created_at" }, { "type": "string", "name": "volume_type" }, { "type": "string", "name": "related_instance_flavor" }, { "type": "string", "name": "display_name" }, { "type": "string", "name": "region" } ] } Pre 2021.01 =========== .. _upgrade-2020-12-1: Upgrading to 2020.12.1 ---------------------- .. important:: This method only works when you have Fleio installed using system packages. We recommend you to migrate to Docker (see :doc:`/operating/migrate-to-docker`) as soon as possible. In 2020.12.1 we have added the enduser panel in Angular and support for Swift object store. In order to enable Swift object store you need enable the Angular enduser panel. You will need to add the following lines in the Nginx configuration: .. code-block:: bash location /new { alias /var/webapps/fleio/frontend/enduser/; expires -1; try_files $uri $uri/ /../enduser/index.html; } Finally, do not forget to reload nginx using the following cli commands: .. code-block:: bash nginx -t systemctl reload nginx .. _upgrade-2020-11-1: Upgrading to 2020.11.1 ---------------------- .. important:: This method only works when you have Fleio installed using system packages. We recommend you to migrate to Docker (see :doc:`/operating/migrate-to-docker`) as soon as possible. With the 2020.11.1 upgrade we have implemented a new log level called FLEIO ACTIVITY, and we have redesigned the general logging. Before upgrading to the 2020.11.1 version you will have to check ``/var/webapps/fleio/fleiosettings/settings.py`` to be sure that you have no custom logging setting added. You can do that by running the following command: .. code-block:: bash grep LOGGING /var/webapps/fleio/fleiosettings/settings.py If you have any results, you will need to comment or remove those lines. After that you can proceed with the "Recommended upgrade procedure" when upgrading system packages. See older documentation versions for the DEB/RPM system packages safe upgrade procedure. However, if you already upgraded, and you received an error related to Logging, you can just do the steps from above and then run the update commands again. .. _upgrade-2020-07-1: Upgrading to 2020.07.1 ---------------------- .. important:: This method only works when you have Fleio installed using system packages. We recommend you to migrate to Docker (see :doc:`/operating/migrate-to-docker`) as soon as possible. New nginx configuration ^^^^^^^^^^^^^^^^^^^^^^^ In 2020.07.1 we have added the Tickets plugin in Angular. In order to properly work you need to add the following tinymce configuration in the Nginx configuration: .. code-block:: python location /tinymce { alias /var/webapps/fleio/frontend/staff/tinymce/; break; } Finally, do not forget to reload nginx using the following cli commands: .. code-block:: bash nginx -t systemctl reload nginx .. _upgrade-2020-05: Upgrading to 2020.05.0 ---------------------- .. important:: This method only works when you have Fleio installed using system packages. We recommend you to migrate to Docker (see :doc:`/operating/migrate-to-docker`) as soon as possible. To upgrade to version 2020.05.0 on Ubuntu 16 and Ubuntu 18 first you will need to run: .. code-block:: bash apt-get dist-upgrade fleio-backend fleio-frontend This is necessary due to a new dependency (patch) that was introduced in 2020.05 release. The regular ``apt-get upgrade fleio-backend fleio-frontend`` command will not install the dependency, and you might get in a state that fleio-frontend is not automatically upgraded. To upgrade to version 2020.05.0 on Centos you need to run: .. code-block:: bash yum install fleio-backend fleio-frontend Besides this, the following additional steps are required. We are migrating the Fleio frontend from the legacy AngularJS framework to Angular. For a smooth migration we are gradually rewriting and releasing pages from the staff panel in Angular. After the staff panel is successfully migrated to Angular we will do the same for the end-user panel. This is expected to take several months. The new Angular pages are temporarily located under the ``/newstaff`` URL, while the previous pages remain for now under ``/staff`` URL. New nginx settings ^^^^^^^^^^^^^^^^^^ By default, some of the staff panel menu options already point to ``/newstaff`` links, while the pages that are not yet migrated to Angular will still link to a ``/staff`` URL. For instance, one of the first pages migrated to Angular is **Settings** > **Configurations**, and it links to ``/newstaff/settings/configurations``. This requires that you add a new entry to your nginx conf, which is usually located at for Ubuntu at ``/etc/nginx/sites-enabled/{ your domain }.conf`` and for CentOS at ``/etc/nginx/conf.d/{ your domain }.conf.`` Add this entry in the ``server`` configuration after the ``/staff`` location. .. code-block:: bash # identify the following section and leave it unchanged location /staff { alias /var/webapps/fleio/frontend/site/staff/; expires -1; try_files $uri $uri/ /staff/index.html; } # insert below the following lines location /newstaff { alias /var/webapps/fleio/frontend/staff/; expires -1; try_files $uri $uri/ /../staff/index.html; } Reload nginx to apply the change: .. code-block:: bash systemctl reload nginx If you have enabled the reseller feature an additional change is required in the nginx config. Replace this section: .. code-block:: bash # identify these section and delete it location /reseller { root /var/webapps/fleio/frontend/site/; expires -1; try_files $uri $uri/ /reseller/index.html; } Replace with: .. code-block:: bash # the new reseller directives location /reseller { alias /var/webapps/fleio/frontend/reseller/; expires -1; try_files $uri $uri/ /../reseller/index.html; } Reload nginx to apply the change: .. code-block:: bash systemctl reload nginx New menu definition ^^^^^^^^^^^^^^^^^^^ If you previously changed the menu in ``constants.js`` file, see https://fleio.com/docs/2022.04.1/configuring/frontend-settings.html#new-menu-definition-1