Migrating from v2 to v3

A. Migration overview

Below is a table summarizing the differences between v2 and v3.

Area	v2	v3
Deployment playbook directory	deployment/v2-ubuntu-24.04	deployment/v3-ubuntu-24.04
Ansible variable prefixes	jophiel_, gabriel_, jerahmeel_	Dropped or renamed
App name, slogan, welcome banner	env/vars.yml	Database (Admin tab → Settings)
Global announcements	judgels-server.yml	Database (Admin tab → Settings)
User session limits	env/vars.yml	Database (Admin tab → Settings)
Account and role management	Admin web interface	Contestant web interface (Admin tab)
User role API fields	jophiel, sandalphon, uriel, jerahmeel	account, problem, contest, training
Grading request queue	gabriel-grading-request	judgels-grading-request
Grading response queues	- sandalphon-grading-response - uriel-grading-response - jerahmeel-grading-response	- judgels-grading-response-problem - judgels-grading-response-contest - judgels-grading-response-training
Database migration tables	DATABASECHANGELOG[LOCK] (Liquibase)	DATABASECHANGELOG[LOCK] (Liquibase), with one new changeset

Unlike the v1 to v2 migration, we can upgrade in place, reusing the same VMs and database. We will do the following:

1. Write down the existing settings that will not be migrated automatically.
2. Deploy Judgels v3 using the new deployment playbooks.
3. Re-enter the settings from step 1 in the web interface.

B. Writing down existing settings

Some settings are moved from config files to the database in v3. They will not be migrated automatically, and will fall back to their default values after the upgrade. We will need to re-enter them later.

Write down the values of the following variables from env/vars.yml:

• app_name
• app_slogan
• app_title
• app_description
• jophiel_session_maxConcurrentSessionsPerUser
• jophiel_session_disableLogout

If you have set any announcements, also write down jophiel.web.announcements from /opt/judgels/server/var/conf/judgels-server.yml in the core VM.

C. Deploying Judgels v3

See the Deployment page for more details. In particular, we will need to:

1. Pull the latest Judgels repository, and link the existing env directory to the v3 deployment directory:

   cd ~/judgels
   git pull
   cd deployment/v3-ubuntu-24.04/ansible
   ln -s ~/judgels-env env
   The hosts.ini file does not need any changes.
2. Rename the following variables in env/vars.yml:
   • jophiel_superadmin_initialPassword → superadmin_initialPassword
   • gabriel_grading_numWorkerThreads → grading_numWorkerThreads
3. Remove the following variables from env/vars.yml, which are no longer used:
   • app_name
   • app_slogan
   • app_title
   • app_description
   • app_footer (the footer is now always "Powered by Judgels")
   • jophiel_session_maxConcurrentSessionsPerUser
   • jophiel_session_disableLogout
4. Set the Judgels version in env/vars.yml:

   app_version: '3.0.0'

Any other variables with the jophiel_, gabriel_, or jerahmeel_ prefix are ignored in v3.

Then, run the deploy playbook:

ansible-playbook -e @env/vars.yml playbooks/deploy.yml

This will deploy the server, client, and graders together, and migrate the database automatically. We don't need to rerun the provision playbook.

D. Restoring settings

Open the contestant web interface and log in as superadmin. Go to the Admin tab, then System → Settings. Re-enter the values that we wrote down in section B:

• App settings: name, slogan, and announcement
• Home settings: banner (from app_title and app_description)
• Session settings: disable logout, and max concurrent sessions per user

E. Verifying

1. Verify that we can log in as superadmin in the admin web interface.
2. Verify that the contestant web interface shows the correct app name and home banner.
3. Submit a solution to a contest problem, and verify that it gets graded.
4. (Optional) We can remove the following unused queues from the RabbitMQ management web interface:
   • gabriel-grading-request
   • sandalphon-grading-response
   • uriel-grading-response
   • jerahmeel-grading-response

At this point, Judgels v3 should be fully operational.