Skip to content

Upgrading GitFlic from Version 2.x.x to 3.x.x

Overview

Starting with version 3.0.0, GitFlic has changed its approach to handling LFS and release files. This requires using an additional tool, cli.jar, to ensure proper migration of data from version 2.x.x file system storage to the new mechanism. Without running cli.jar before upgrading, release files and LFS data may display incorrectly in the web interface and become inaccessible.

Additionally, version 3.3.0 introduces changes to Docker registry operations. If you experienced Docker registry issues in earlier versions, follow step 6 in the instructions below.

Key Notes: - Version 3.0.0+ includes cli.jar and gitflic-cli.sh for execution - cli.jar requires access to PostgreSQL and Redis databases used by GitFlic - cli.jar requires access to GitFlic's static files - Always use gitflic-cli.sh to execute cli.jar - Use the same application.properties file as your GitFlic installation

When to Run gitflic-cli.sh <path_to_application.properties>:

  • When upgrading from 2.x.x to 3.0.0+
  • When upgrading from pre-3.3.0 to 3.3.0+

When NOT to Run gitflic-cli.sh:

  • For fresh installations of version 3.3.0+
  • If you've already successfully run the migration tool

Step-by-Step Upgrade Guide

1. Stop GitFlic service (PostgreSQL and Redis must remain running).

2. Execute the migration script: 

./gitflic-cli.sh /path/to/application.properties

3. Wait for startup completion (you'll see initialization logs).

4. Execute release files migration: 

fix releases
Expected logs: 
[Initial log] Counting releases...
[Completion log] Migrated: 24/24 (100%) releases

5. Execute LFS files migration: 

fix lfs
Expected logs: 
[Initial log] Counting projects with LFS...
[Completion log] Fixed: 12/12 (100%) LFS projects

6. Execute Docker manifests migration: 

fix docker manifest
Expected logs: 
[Initial log] Counting Docker images...
[Completion log] Fixed: 4/4 (100%) Docker images

7. Exit with ctrl+c.

Docker Container Upgrade Instructions

1. Stop GitFlic container (ensure Postgres/Redis containers remain running).

2. Extract upgrade package and verify docker/ENV settings.

3. Prepare CLI container: 

docker compose --env-file docker/ENV --file cli/docker/docker-compose.yaml create

4. Access the container: 

docker run -ti --env-file docker/ENV --network docker_git_net --entrypoint=bash docker-fixcli

5. Inside container, run migration: 

./gitflic-cli.sh ./application.properties

6-10. Repeat steps 4-6 from the standard upgrade process.

11. Complete GitFlic upgrade following standard instructions.

After successful upgrade, you may remove temporary containers/images created during migration.

Automatic translation!

This page has been automatically translated. The text may contain inaccuracies.