Migrating from v1 to v2

note

There was no actual "v1" version as we only started properly versioning Judgels starting from v2.

We consider that you are on "v1" if you deployed individual legacy microservices: jophiel, sandalphon, uriel etc. instead of the newer judgels-server monolith.

A. Migration overview

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

Area	v1	v2
Ansible playbook env files	- dist/hosts - dist/env.yml	- env/hosts.ini - env/vars.yml
Services	jophiel, sandalphon, uriel, jerahmeel	judgels-server
Services	gabriel	judgels-grader
Services	raphael	judgels-client
Data storage	/judgels/{jophiel,sandalphon,uriel,jerahmeel}/var/data	/opt/judgels/server/var/data
Database migration tables	-jophiel_DATABASECHANGELOG[LOCK] (Liquibase) -uriel_DATABASECHANGELOG[LOCK] (Liquibase) -jerahmeel_DATABASECHANGELOG[LOCK] (Liquibase) -play_evolutions (Play framework)	DATABASECHANGELOG[LOCK] (Liquibase)

To be on the safer side, we will do the following:

1. Stop all services from the old Judgels v1 deployment.
2. Spin up new VMs and then deploy a completely fresh v2 version.
3. Migrate the database and data from the old deployment to the new one.

B. Dumping existing database

First, stop all backend Judgels services from the existing v1 deployment (jophiel, sandalphon, uriel, [jerahmeel]).

We will dump the existing judgels database from the old VM, and later we will restore it to the new VM. We can use mysqldump utility to do so:

mysqldump -u judgels -p judgels | gzip > judgels.sql.gz

Enter the judgels database password when asked.

C. Deploying Judgels v2

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

• Point the old domain(s) to the new core VM IP.
• Adapt the configuration values from the old dist/env.yml to the new env/vars.yml. Notice that there are some config key changes.

IMPORTANT: we will also need to skip automatic database migration for this deployment. Comment out the judgels-server-migrate role from the playbooks/deploy.yml playbook as follows:

- hosts: core
  gather_facts: false
  roles:
    - name: mysql-install
    - name: phpmyadmin-deploy
    - name: rabbitmq-deploy
    # - name: judgels-server-migrate
    - name: judgels-server-deploy
    - name: judgels-client-deploy
    - name: nginx-certbot-deploy

...

Deploy Judgels v2 at this point.

D. Restoring database

After the Judgels v2 deployment is up, judgels-server will crash because the database is still empty. The next step is to restore the data from the old database to the new database.

1. Copy the database dump judgels.sql.gz to the new core VM (e.g. via scp).
2. Restore the database:

   gunzip < judgels.sql.gz | mysql -u judgels -p judgels
   Enter the new judgels database password when asked.
3. Run this command to mark the database as fully migrated:

   docker exec -it judgels-server ./init.sh db fast-forward
4. (Optional) We can remove the following tables, which are unused in v2:
   • {jophiel,uriel,jerahmeel}_DATABASECHANGELOG
   • {jophiel,uriel,jerahmeel}_DATABASECHANGELOGLOCK
   • play_evolutions
   • jophiel_legacy_session
5. (Optional) We can also remove the following legacy tables (if they still exist):
   • uriel_contest_group
   • uriel_contest_group_contest
   • uriel_contest_group_scoreboard
   • jerahmeel_stats_user_chapter
   • jerahmeel_stats_user_course
   • jerahmeel_stats_user_problem_set

E. Migrating data

Deep copy* all data from the following to the new core VM's /opt/judgels/server/var/data:

• /judgels/jophiel/var/data from old VM containing Jophiel
• /judgels/sandalphon/var/data from old VM containing Sandalphon
• /judgels/uriel/var/data from old VM containing Uriel
• /judgels/jerahmeel/var/data from old VM containing Jerahmeel

*In particular, /opt/judgels/server/var/data/submissions should contain the combined files from /judgels/{sandalphon,uriel,jerahmeel}/var/data/submissions.

F. Restarting server

Restart the stopped judgels-server:

docker start judgels-server

At this point, Judgels v2 should be fully operational.