Skip to main content
Version: 4.x

Upgrade

Note

Upgrades may change the database schema. Schema changes rely on Django's migrate tool, which depends on the migrations directories created during installation and on the django_migrations table. Do not delete or modify these directories or the table, otherwise upgrades that change the schema may leave columns missing.

Warning

If you run v2.x.x (see System Settings / About), do not upgrade to v3 or v4 with the upgrade tool; it will break the installation! #419

Upgrading from 3.x to 4.0​

4.0 upgrades the core back-end dependencies (Python 3.8+, Django 4.2, channels 4, paramiko 3.4). The 3.x runtime and Docker image cannot run 4.0 code, so follow these steps:

Docker install​

Do not use manage.py update to go from 3.x to 4.0

manage.py update would pip-install the 4.0 Python dependencies into the 3.x container, and they are lost as soon as the container is recreated. It is only meant for updates between 4.x versions; to go from 3.x to 4.0 switch the image as described below.

  1. Back up the database and the data directory: 
    docker exec spug-db mysqldump -uroot -pspug.cc spug > spug-backup.sql
    cp -r /data/spug /data/spug.bak
  2. Edit docker-compose.yml: change the image of the spug service to openspug/spug-service:4.0 and add SPUG_DOCKER_VERSION=v4.0.1 to its environment (everything else stays the same), then recreate the containers: 
      spug:
        image: openspug/spug-service:4.0
        environment:
          - SPUG_DOCKER_VERSION=v4.0.1
          - MYSQL_DATABASE=spug
          # ... the remaining settings stay unchanged
    cd /data/spug
    docker compose up -d
  3. Inside the container check out v4.0.1, download the matching front-end bundle and apply the schema changes (existing data such as the administrator account and execution templates, as well as your custom settings in overrides.py, are kept): 
    docker exec spug bash -c 'cd /data/spug && git fetch origin --tags && git checkout v4.0.1 && curl -fo /tmp/web.tar.gz https://cdn.spug.cc/spug/web_v4.0.1.tar.gz && rm -rf spug_web/build && tar xf /tmp/web.tar.gz -C spug_web/ && python3 spug_api/manage.py updatedb'
  4. Restart the container, confirm that System Settings / About shows v4.0.1 and force-refresh the browser: 
    docker restart spug
Why docker compose pull alone is not enough

The latest tag on Docker Hub is still 3.3.3, so docker compose pull alone does not give you 4.0. Even with the 4.0 image, the container leaves the existing code in /data/spug/service untouched on start, which is why step 3 switches the code by hand. Without it the 3.x code runs on Django 4.2: the container reports running, but every API request fails.

Manual deployment​

  1. Back up the database.
  2. Install Python 3.8 or later and rebuild the virtual environment: 
    cd /data/spug/spug_api
    git fetch origin --tags && git checkout v4.0.1
    rm -rf venv && python3 -m venv venv
    source venv/bin/activate
    pip install -U pip setuptools
    pip install -r requirements.txt mysqlclient -i https://pypi.tuna.tsinghua.edu.cn/simple/
    python manage.py updatedb
  3. Download the 4.0 front-end bundle https://cdn.spug.cc/spug/web_v4.0.1.tar.gz and extract it into spug_web (it creates the build directory).
  4. Make sure the spug-ws program in supervisor uses tools/start-ws.sh (daphne), then run supervisorctl restart all.

Updating between 4.x versions​

The commands below are only for updates between 4.x versions; to upgrade from 3.x to 4.0 follow the previous section.

Docker install​

# updates to the latest version by default
# spug is the container name, replace it with your container ID if needed

docker exec -i spug python3 /data/spug/spug_api/manage.py update

# restart the container afterwards
docker restart spug

Manual deployment​

# updates to the latest version by default

cd spug_api
source venv/bin/activate
python manage.py update

# restart the services
supervisorctl restart all

manage.py update checks for a new version and shows its release notes. After confirmation it downloads the front-end bundle, checks out the matching tag of the back-end, updates the dependencies and applies schema changes. When the installation is already up to date, a repair update (re-fetching the current version) can be chosen instead.