Migrating from v3 to v4

Draft

v4 is not released yet. This guide is a draft and will grow as v4 changes land.

A. Migration overview

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

Area	v3	v4
User registration (on/off, reCAPTCHA, activation email)	`judgels-server.yml` (`userRegistration_*` variables)	Database (Admin tab → Settings → Training); needs training on
User password reset (on/off, request and reset emails)	`judgels-server.yml` (`userResetPassword_*` variables)	Database (Admin tab → Settings → Training); needs training on
User account API (registration, activation, password reset)	`/api/v2/user-account/...`	`/api/v4/account/registration/...` and `/api/v4/account/password/...`
User registration web config API field	`useRecaptcha`	`recaptchaEnabled`
Training (courses, problems, submissions)	On when `app_mode` is `TLX`	On when `training_enabled` is `true`
Ratings	On when `app_mode` is `TLX`	On when `rating_enabled` is `true`
Google Analytics tracking ID	`judgels-client.js` (`googleAnalytics_trackingId` variable)	Database (Admin tab → Settings)
Google sign-in client ID	`judgels-server.yml` and `judgels-client.js`	`judgels-server.yml` only
`judgels-client.js`	App mode, Google sign-in, Google Analytics and the API URL	The API URL only
User registration web config API (`/api/v2/users/registration/web/config`)	Separate endpoint	Removed; the reCAPTCHA site key is in the user web config

As with the v2 to v3 migration, we can upgrade in place, reusing the same VMs and database.

B. Deploying Judgels v4

Pull the latest Judgels repository:
```
cd ~/judgels
git pull
```
Keep the userRegistration_* and userResetPassword_* variables in env/vars.yml for now. On its first start, v4 copies them into the database (see section C).
Keep the googleAnalytics_trackingId variable in env/vars.yml for now. On its first start, v4 copies it into the database (see section E).
In env/vars.yml, replace app_mode with the training and rating flags (see section D). If app_mode was TLX:
```
training_enabled: true
rating_enabled: true
```
If app_mode was unset or JUDGELS, remove it; both flags default to false.
Set the Judgels version in env/vars.yml:
```
app_version: '4.0.0'
```

Then, run the deploy playbook:

cd deployment/v3-ubuntu-24.04/ansible
ansible-playbook -e @env/vars.yml playbooks/deploy.yml

C. User registration and password reset settings

User registration and password reset are now part of training. They work only when training_enabled is true (see section D). A contest-only deployment has no self-service accounts: admins create the users, and the Register, "Forgot your password?" and My account pages are hidden.

They are now turned on and configured in the Admin tab, under System → Settings → Training, instead of in judgels-server.yml. The Training tab shows only when training is on. The mailer and recaptcha config stay in judgels-server.yml, because they hold secrets, and are needed only for these features.

On its first start, v4 copies the old values into the database, so nothing needs to be re-entered:

If userRegistration_enabled is true, the registration settings are copied: enabled, reCAPTCHA (from userRegistration_useRecaptcha), and the activation email template.
If userResetPassword_enabled is true, the password reset settings are copied: enabled, and the request and reset email templates.
A feature that is turned off in the config is not copied, and stays off.
Settings that already exist in the database are never overwritten, so later restarts do not undo changes made in the Admin tab.

After the upgrade, the Admin tab is the only place to change these settings. The userRegistration_* and userResetPassword_* variables are deprecated, and will be removed in the release after v4.0. Once v4 has started once, they can be removed from env/vars.yml.

Saving these settings in the Admin tab is rejected when:

registration or password reset is turned on, but no mailer is configured;
reCAPTCHA is turned on, but no recaptcha is configured;
the activation email body or the password reset request email body does not contain {{emailCode}};
training is turned off.

The endpoints moved from /api/v2/user-account/... to /api/v4/account/registration/... and /api/v4/account/password/..., and are served only when training is on. The client that ships with v4 uses the new paths.

D. Training and rating flags

v3 had two modes: JUDGELS and TLX. Training and ratings were on only in TLX mode. v4 has no modes; each feature has its own flag instead:

training_enabled turns on training: courses, the problem and submission lists, the training admin pages and role, and the submission history on profiles.
rating_enabled turns on ratings: the Ranking page, the top ratings on the home page, the Ratings admin page, and rating contests.

Both default to false. app_mode is no longer read, so a TLX deployment that only bumps app_version loses training and ratings after the upgrade.

The flags are read only by the server, which passes them to the client. judgels-client.js no longer has a mode or any training config.

Without Ansible, make the same change by hand:

In judgels-server.yml, remove judgels.app, and move the top-level training block, with its aws, submission and stats, under judgels. Then set the flags in the training and rating blocks there. The server no longer starts if judgels.app or a top-level training is still there.
```
judgels:
  training:
    enabled: true
    # aws, submission and stats as before

  rating:
    enabled: true
```
In judgels-client.js, remove mode.

E. Client config

judgels-client.js now holds only the URL of the server API. The client gets everything else from the server:

Training and rating flags: see section D.
Google sign-in: the client ID is read from auth_google_clientId in judgels-server.yml, as before; it is no longer also written into judgels-client.js.
Google Analytics: the tracking ID is now set in the Admin tab, under System → Settings → General. On its first start, v4 copies googleAnalytics_trackingId into the database, unless a tracking ID was already saved there. The variable is deprecated, and will be removed in the release after v4.0; once v4 has started once, it can be removed from env/vars.yml.

Without Ansible, cut judgels-client.js down to apiUrl by hand, and, to keep Google Analytics, add the tracking ID to judgels-server.yml before the first start:

judgels:
  googleAnalytics:
    trackingId: G-XXXXXXXXXX

Leftover keys in judgels-client.js are ignored.

F. Verifying

Log in as superadmin, and go to the Admin tab, then System → Settings → Training. Verify that the Account registration and Account password reset sections match the old config. The Training tab shows only when training_enabled is true.
Log out. Verify that the Register link and the "Forgot your password?" link show only when their feature is turned on.
If registration is turned on, register a new user, and verify that the activation email arrives.
If Google Analytics was configured, verify that its tracking ID shows in the App section of System → Settings → General.
If Google sign-in was configured, verify that the Google sign-in button shows on the login page.
Verify that the Courses, Problems and Submissions menus show only when training_enabled is true, and the Ranking menu only when rating_enabled is true.

At this point, Judgels v4 should be fully operational.

Migrating from v3 to v4

A. Migration overview​

B. Deploying Judgels v4​

C. User registration and password reset settings​

D. Training and rating flags​

E. Client config​

F. Verifying​