-
Notifications
You must be signed in to change notification settings - Fork 40
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add migration doc for the parsec-server
Co-authored-by: Marcos Medrano <786907+mmmarcos@users.noreply.github.com> Co-authored-by: Vincent Michel <vxgmichel@gmail.com>
- Loading branch information
1 parent
5bd29e2
commit 4fd94a7
Showing
3 changed files
with
112 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -14,3 +14,4 @@ Administrator Guide | |
stats_server | ||
stats_organization | ||
hosting/index | ||
migration/index |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,109 @@ | ||
.. Parsec Cloud (https://parsec.cloud) Copyright (c) BUSL-1.1 2016-present Scille SAS | ||
.. _doc_adminguide_server_migration: | ||
|
||
.. cspell:words linenos literalinclude | ||
======================= | ||
Parsec Server migration | ||
======================= | ||
|
||
This guide covers the migration procedure for the `Parsec`_ server (also called `parsec-backend`). | ||
|
||
.. note:: | ||
|
||
We consider that you are using the same infrastructure configuration as in the :ref:`Parsec Server installation guide <doc_adminguide_hosting>`. | ||
Adapt this guide to your own situation. | ||
|
||
.. _Parsec: https://parsec.cloud | ||
|
||
Updating to a newer version | ||
*************************** | ||
|
||
.. warning:: | ||
|
||
Before updating to a newer version, make sure to back up the database, | ||
in case you need to roll back the update. | ||
|
||
In this guide, we will migrate ``parsec-backend`` from version ``v2.15.0`` to ``v2.16.0``. | ||
|
||
.. _update_docker_image_tag: | ||
|
||
1. Update the ``parsec-backend``'s docker image tag of in docker-compose file (``parsec-server.docker.yaml``): | ||
|
||
.. code-block:: yaml | ||
:linenos: | ||
:emphasize-lines: 5 | ||
services: | ||
# ... | ||
parsec-backend: | ||
image: ghcr.io/scille/parsec-cloud/parsec-backend-server:v2.15.0 | ||
# ... | ||
You need to change the used tag (at line **5**) to ``v2.16.0``. | ||
|
||
2. List the pending migrations to be applied: | ||
|
||
.. code-block:: bash | ||
docker compose -f parsec-server.docker.yaml run parsec-backend migrate --dry-run | ||
The output should look like this: | ||
|
||
.. code-block:: | ||
0001_initial.sql (already applied) | ||
0002_add_migration_table.sql (already applied) | ||
0003_human_handle.sql (already applied) | ||
0004_invite.sql (already applied) | ||
0005_redacted_certificates.sql (already applied) | ||
0006_outsider_enabled.sql (already applied) | ||
0007_users_limit.sql (already applied) | ||
0008_apiv1_removal.sql (already applied) | ||
0009_add_realm_user_change_table.sql (already applied) | ||
0010_add_pki_certificate_table.sql (already applied) | ||
0011_add_sequester_tables.sql (already applied) | ||
0012_add_sequester_webhook.sql (already applied) | ||
0013_add_shamir_recovery.sql ✔ | ||
0014_add_realm_archiving.sql ✔ | ||
.. note:: | ||
|
||
This output is provided as an example. Don't expect it to match your output. | ||
|
||
The lines ending with ``already applied`` are migrations already present on the database | ||
whereas the one ending with ``✔`` are migrations to be applied. | ||
|
||
3. Apply the database migration: | ||
|
||
.. code-block:: bash | ||
docker compose -f parsec-server.docker.yaml run parsec-backend migrate | ||
.. _restart_parsec_backend_container: | ||
|
||
4. Restart the ``parsec-backend`` container: | ||
|
||
.. code-block:: bash | ||
docker compose -f parsec-server.docker.yaml restart parsec-backend | ||
Rollback to a previous version | ||
****************************** | ||
|
||
.. warning:: | ||
|
||
Rollback is currently limited in Parsec. | ||
The only possible way to rollback is to use the previous database backup. | ||
So you will lose the delta of backup vs current database. | ||
|
||
To roll back to a previous version, let's say we want to downgrade ``parsec-backend`` from version ``v2.16.0`` to ``v2.15.0``. | ||
|
||
1. Downgrade the ``parsec-backend``'s docker image tag in the docker-compose file (``parsec-server.docker.yaml``). | ||
Like in :ref:`Update the parsec-backend tag <update_docker_image_tag>` change the tag ``v2.16.0`` to ``v2.15.0``. | ||
|
||
2. Replace the current database with the backup on the Postgres database. | ||
|
||
3. :ref:`Restart the parsec-backend container<restart_parsec_backend_container>` |