Files

T

Iain Sproat 4b9f915bd3 docs(docker-compose): documentation to assist database upgrades of docker-compose (#1100 )

Upgrading databases in postgres is not straightforward as the volume is often not compatible. It
requires creating a database backup, deleting the volume, deploying the upgraded version, and then
restoring from backup. This PR provides documentation and scripts to assist with this process.

Co-authored-by: Fabians <fabis94@live.com>

2022-10-12 11:43:59 +01:00

README.md

docs(docker-compose): documentation to assist database upgrades of docker-compose (#1100 )

2022-10-12 11:43:59 +01:00

README.md

Migrations - Postgres

docker-compose

Backing up and restoring postgres data stored in our local development docker volumes when upgrading to new postgres versions.

Using pgadmin

If postgres is already running, you can skip this step. To get it running, please first checkout this repository at the commit or tag used to previously deploy Speckle on docker-compose. For example, using git on the command line to checkout tag 2.8.0:
```
git fetch --all --tags
git checkout tags/2.8.0 -b main
```
If postgres is already running, you can skip this step. Start the dependencies, which include postgres and pgadmin:
```
docker-compose --file ./docker-compose-deps.yml up --detach
```
Verify that they are running:
```
docker ps
```
Open the postgres admin (pgadmin) dashboard. If you have changed the configuration of pgadmin, you can find it by running docker ps and making a note of the address and port it is serving.
The user name and password can be found in ./docker-compose-deps.yml, next to PGADMIN_DEFAULT_EMAIL and PGADMIN_DEFAULT_PASSWORD.
- At the time of writing the email is admin@localhost.com and the password admin.
Click add new server
In the dialog box in the General tab, enter the name docker-compose (or any other value that you wish).
In the dialog box in the Connection tab:
- for the Host name/addresses enter postgres (its the name of the postgres container in the docker-compose config)
- for port, use 5432 (you can check this is port number used for the postgres container in ./docker-compose-deps.yml)
- for database, username, and password use the values in the file assigned to the respective POSTGRES_DB, POSTGRES_USER, and POSTGRES_PASSWORD keys. By default the value of these are all speckle.
Click save
You can now select the database from the browser window (typically found on the left hand side). Expand docker-compose and databases, the right-click on the database you wish to backup.
Choose a filename and start the backup process.
Once the backup is done, make sure you click on the "Click to open file location" button and download the backup to your host machine.
We recommend testing the integrity of the backup at this time. One means of doing this is to install speckle-server on another machine (or modify the name and ports in the file and install a second locally), then upload the backup per the below instructions using pgadmin. Use pgadmin or Speckle to check that the information is present.

Stop the docker-compose dependencies with:

docker-compose -f ./docker-compose-deps.yml down

Find the name of the postgres database volume.
```
docker volume ls
```
⚠️ Delete the postgres database. This is destructive, please ensure that the backup is correct and saved securely before proceeding, see instructions above. ⚠️
```
docker volume rm speckle-server_postgres-data
```
Check out the version of Speckle Server you wish to deploy. For example, using git on the command line to checkout the latest commit or a tagged version:
```
git checkout main
```
```
git checkout tags/2.9.0 -b main
```
Deploy the docker-compose file with the updated postgres version:
```
docker-compose -f ./docker-compose-deps.yml up --detach
```
Open pgadmin and connect to the server, using the instructions above.
Right click databases from the browser window, and click create.
Right click the created database and click restore, selecting your previously stored backup. You will need to upload the backup you previously downloaded back into pgadmin first.
Deploy Speckle server, if necessary, and verify the data is correct.