Feat 99 setup wizard

.env.dev

@@ -15,6 +15,9 @@ ADMIN_PWD=admincare
 GUEST_EMAIL=guest@guest.com
 GUEST_PWD=guestguest
 
+# Skip first-time setup wizard: create admin from ADMIN_EMAIL / ADMIN_PWD and mark wizard complete (demo / dev pipelines).
+DEV_SKIP_WIZARD=true
+
 # nlp server
 SERVICE_NLP_ENABLED=true
 SERVICE_NLP_URL=http://care.ukp.informatik.tu-darmstadt.de:4853

.env.main

@@ -15,6 +15,9 @@ ADMIN_PWD=admincare
 GUEST_EMAIL=guest@guest.com
 GUEST_PWD=guestguest
 
+# Skip first-time setup wizard: create admin from ADMIN_EMAIL / ADMIN_PWD and mark wizard complete (demo / dev pipelines).
+DEV_SKIP_WIZARD=true
+
 # nlp server
 SERVICE_NLP_ENABLED=true
 SERVICE_NLP_URL=http://care.ukp.informatik.tu-darmstadt.de:4852

Makefile

@@ -11,7 +11,8 @@ default: help
 .PHONY: help
 help:
 	@echo "make help             		 		Show this help message"
-	@echo "make dev             		  		Run in development mode (only unix)"
+	@echo "make dev             		  		Run in development mode, skipping the first-time setup wizard (only unix)"
+	@echo "make dev-wizard         		  		Run dev mode and go through the first-time setup wizard"
 	@echo "make doc 							Build the documentation"
 	@echo "make dev-build       		  		Build the frontend (make dev-build-frontend) and run the backend in development mode"
 	@echo "make dev-backend      		 		Run backend in development mode"
@@ -79,6 +80,10 @@ init: modules db
 
 .PHONY: dev
 dev: frontend/node_modules/.uptodate backend/node_modules/.uptodate
+	cd frontend && npm run frontend-dev & cd backend && DEV_SKIP_WIZARD=true npm run start
+
+.PHONY: dev-wizard
+dev-wizard: frontend/node_modules/.uptodate backend/node_modules/.uptodate
 	cd frontend && npm run frontend-dev & cd backend && npm run start
 
 .PHONY: dev-frontend

backend/db/migrations/20260119185828-create-wizard_step.js

@@ -0,0 +1,56 @@
+'use strict';
+
+/** @type {import('sequelize-cli').Migration} */
+module.exports = {
+    async up(queryInterface, Sequelize) {
+        await queryInterface.createTable('wizard_step', {
+            id: {
+                allowNull: false,
+                autoIncrement: true,
+                primaryKey: true,
+                type: Sequelize.INTEGER,
+            },
+            key: {
+                type: Sequelize.STRING,
+                allowNull: false,
+                unique: true,
+            },
+            order: {
+                type: Sequelize.INTEGER,
+                allowNull: false,
+            },
+            title: {
+                type: Sequelize.STRING,
+                allowNull: false,
+            },
+            description: {
+                type: Sequelize.STRING,
+                allowNull: true,
+            },
+            type: {
+                type: Sequelize.STRING,
+                allowNull: false,
+            },
+            deleted: {
+                type: Sequelize.BOOLEAN,
+                defaultValue: false,
+            },
+            createdAt: {
+                allowNull: false,
+                type: Sequelize.DATE,
+            },
+            updatedAt: {
+                allowNull: false,
+                type: Sequelize.DATE,
+            },
+            deletedAt: {
+                allowNull: true,
+                type: Sequelize.DATE,
+            },
+        });
+    },
+
+    async down(queryInterface, Sequelize) {
+        await queryInterface.dropTable('wizard_step');
+    },
+};

backend/db/migrations/20260119185850-extend-setting-wizard.js

@@ -0,0 +1,51 @@
+'use strict';
+
+/** @type {import('sequelize-cli').Migration} */
+module.exports = {
+    async up(queryInterface, Sequelize) {
+        await queryInterface.addColumn('setting', 'showInWizard', {
+            type: Sequelize.BOOLEAN,
+            defaultValue: false,
+        });
+        await queryInterface.addColumn('setting', 'wizardOrder', {
+            type: Sequelize.INTEGER,
+            allowNull: true,
+        });
+        await queryInterface.addColumn('setting', 'requiredInWizard', {
+            type: Sequelize.BOOLEAN,
+            defaultValue: false,
+        });
+        await queryInterface.addColumn('setting', 'wizardStepId', {
+            type: Sequelize.INTEGER,
+            allowNull: true,
+            references: {
+                model: 'wizard_step',
+                key: 'id',
+            },
+            onUpdate: 'CASCADE',
+            onDelete: 'SET NULL',
+        });
+        await queryInterface.addColumn('setting', 'displayName', {
+            type: Sequelize.STRING(256),
+            allowNull: true,
+        });
+        await queryInterface.addColumn('setting', 'displayGroup', {
+            type: Sequelize.STRING(128),
+            allowNull: true,
+        });
+        await queryInterface.addColumn('setting', 'displaySubsection', {
+            type: Sequelize.STRING(128),
+            allowNull: true,
+        });
+    },
+
+    async down(queryInterface, Sequelize) {
+        await queryInterface.removeColumn('setting', 'displaySubsection');
+        await queryInterface.removeColumn('setting', 'displayGroup');
+        await queryInterface.removeColumn('setting', 'displayName');
+        await queryInterface.removeColumn('setting', 'showInWizard');
+        await queryInterface.removeColumn('setting', 'wizardOrder');
+        await queryInterface.removeColumn('setting', 'requiredInWizard');
+        await queryInterface.removeColumn('setting', 'wizardStepId');
+    },
+};

backend/db/migrations/20260119192230-basic-wizard_steps.js

@@ -0,0 +1,22 @@
+'use strict';
+
+/** @type {import('sequelize-cli').Migration} */
+module.exports = {
+    async up(queryInterface, Sequelize) {
+        const now = new Date();
+        await queryInterface.bulkInsert('wizard_step', [
+            { key: 'admin', order: 1, title: 'Admin Account', description: 'Create the administrator account', type: 'admin', deleted: false, createdAt: now, updatedAt: now, deletedAt: null },
+            { key: 'general', order: 2, title: 'General Settings', description: 'Copyright, consent, guest login, external links', type: 'general', deleted: false, createdAt: now, updatedAt: now, deletedAt: null },
+            { key: 'mail', order: 3, title: 'Mail Configuration', description: 'Enable email service and configure SMTP/sendmail', type: 'mail', deleted: false, createdAt: now, updatedAt: now, deletedAt: null },
+            { key: 'registration', order: 4, title: 'User Registration', description: 'What is required at signup', type: 'registration', deleted: false, createdAt: now, updatedAt: now, deletedAt: null },
+            { key: 'moodle', order: 5, title: 'Moodle Settings', description: 'Optional Moodle API settings', type: 'moodle', deleted: false, createdAt: now, updatedAt: now, deletedAt: null },
+            { key: 'summary', order: 6, title: 'Summary', description: 'Review your choices before finishing', type: 'summary', deleted: false, createdAt: now, updatedAt: now, deletedAt: null },
+        ], {});
+    },
+
+    async down(queryInterface, Sequelize) {
+        await queryInterface.bulkDelete('wizard_step', {
+            key: ['admin', 'general', 'mail', 'registration', 'moodle', 'summary'],
+        }, {});
+    },
+};

backend/db/migrations/20260119192356-transform-user-admin.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const { genSalt, genPwdHash } = require('../../utils/auth');
+
+/**
+ * Removes the default admin user created by basic-users so the first admin
+ * must be created via the setup wizard. Runs after basic-configuration; all
+ * configurations owned by the default admin are first reassigned to Bot (userId 2)
+ * to satisfy the configuration.userId FK, then the admin is deleted.
+ * POST /auth/setup-admin reassigns those configurations from Bot to the new admin.
+ *
+ * @type {import('sequelize-cli').Migration}
+ */
+module.exports = {
+    async up(queryInterface, Sequelize) {
+        const rows = await queryInterface.sequelize.query(
+            'SELECT id FROM "user" WHERE "userName" = \'admin\' AND "deleted" = false',
+            { type: queryInterface.sequelize.QueryTypes.SELECT }
+        );
+        const admin = rows && rows[0];
+        if (!admin) {
+            return;
+        }
+        const adminId = admin.id;
+        const BOT_USER_ID = 2;
+
+        await queryInterface.sequelize.query(
+            `UPDATE configuration SET "userId" = :botId, "updatedAt" = :now WHERE "userId" = :adminId`,
+            {
+                replacements: { botId: BOT_USER_ID, adminId, now: new Date() },
+                type: Sequelize.QueryTypes.UPDATE,
+            }
+        );
+
+        await queryInterface.bulkDelete('user_role_matching', { userId: adminId }, {});
+        await queryInterface.bulkDelete('user', { userName: 'admin' }, {});
+    },
+
+    async down(queryInterface, Sequelize) {
+        const salt = genSalt();
+        const passwordHash = await genPwdHash(process.env.ADMIN_PWD || 'admin', salt);
+        const email = process.env.ADMIN_EMAIL || 'admin@localhost';
+        const now = new Date();
+
+        await queryInterface.bulkInsert('user', [{
+            firstName: 'admin',
+            lastName: 'user',
+            userName: 'admin',
+            email: email,
+            passwordHash: passwordHash,
+            salt: salt,
+            acceptStats: true,
+            acceptTerms: true,
+            deleted: false,
+            createdAt: now,
+            updatedAt: now,
+        }], {});
+
+        const userRows = await queryInterface.sequelize.query(
+            'SELECT id FROM "user" WHERE "userName" = \'admin\'',
+            { type: queryInterface.sequelize.QueryTypes.SELECT }
+        );
+        const roleRows = await queryInterface.sequelize.query(
+            'SELECT id FROM "user_role" WHERE name = \'admin\'',
+            { type: queryInterface.sequelize.QueryTypes.SELECT }
+        );
+        const inserted = userRows && userRows[0];
+        const adminRole = roleRows && roleRows[0];
+        if (inserted && adminRole) {
+            await queryInterface.bulkInsert('user_role_matching', [{
+                userId: inserted.id,
+                userRoleId: adminRole.id,
+                deleted: false,
+                createdAt: now,
+                updatedAt: now,
+                deletedAt: null,
+            }], {});
+        }
+    },
+};

backend/db/migrations/20260119194252-transform-setting-wizard.js

@@ -0,0 +1,81 @@
+'use strict';
+
+/**
+ * Wizard settings per step requiredInWizard: true only where the setting must be filled.
+ */
+const WIZARD_SETTINGS = [
+    // general
+    { key: 'app.config.copyright', wizardStep: 'general', wizardOrder: 1, requiredInWizard: true },
+    { key: 'app.config.consent.enabled', wizardStep: 'general', wizardOrder: 2, requiredInWizard: false },
+    { key: 'app.login.guest', wizardStep: 'general', wizardOrder: 3, requiredInWizard: false },
+    { key: 'app.login.forgotPassword', wizardStep: 'general', wizardOrder: 4, requiredInWizard: false },
+    { key: 'app.landing.showDocs', wizardStep: 'general', wizardOrder: 6, requiredInWizard: false },
+    { key: 'app.landing.linkDocs', wizardStep: 'general', wizardOrder: 7, requiredInWizard: true },
+    { key: 'app.landing.showProject', wizardStep: 'general', wizardOrder: 8, requiredInWizard: false },
+    { key: 'app.landing.linkProject', wizardStep: 'general', wizardOrder: 9, requiredInWizard: false },
+    { key: 'app.landing.showFeedback', wizardStep: 'general', wizardOrder: 10, requiredInWizard: false },
+    { key: 'app.landing.linkFeedback', wizardStep: 'general', wizardOrder: 11, requiredInWizard: false },
+    // mail
+    { key: 'system.mailService.enabled', wizardStep: 'mail', wizardOrder: 12, requiredInWizard: false },
+    { key: 'system.mailService.sendMail.enabled', wizardStep: 'mail', wizardOrder: 13, requiredInWizard: false },
+    { key: 'system.mailService.sendMail.path', wizardStep: 'mail', wizardOrder: 14, requiredInWizard: false },
+    { key: 'system.mailService.senderAddress', wizardStep: 'mail', wizardOrder: 15, requiredInWizard: false },
+    { key: 'system.mailService.smtp.enabled', wizardStep: 'mail', wizardOrder: 16, requiredInWizard: false },
+    { key: 'system.mailService.smtp.host', wizardStep: 'mail', wizardOrder: 17, requiredInWizard: false },
+    { key: 'system.mailService.smtp.port', wizardStep: 'mail', wizardOrder: 18, requiredInWizard: false },
+    { key: 'system.mailService.smtp.secure', wizardStep: 'mail', wizardOrder: 19, requiredInWizard: false },
+    { key: 'system.mailService.smtp.auth.enabled', wizardStep: 'mail', wizardOrder: 20, requiredInWizard: false },
+    { key: 'system.mailService.smtp.auth.user', wizardStep: 'mail', wizardOrder: 21, requiredInWizard: false },
+    { key: 'system.mailService.smtp.auth.pass', wizardStep: 'mail', wizardOrder: 22, requiredInWizard: false },
+    { key: 'system.baseUrl', wizardStep: 'mail', wizardOrder: 23, requiredInWizard: false },
+    { key: 'app.register.emailVerification', wizardStep: 'mail', wizardOrder: 24, requiredInWizard: false },
+    // app.login.forgotPassword already in general; in mail step it's a toggle in UI, same key
+    // registration
+    { key: 'app.register.enabled', wizardStep: 'registration', wizardOrder: 25, requiredInWizard: false },
+    { key: 'app.register.requestName', wizardStep: 'registration', wizardOrder: 26, requiredInWizard: false },
+    { key: 'app.register.requestStats', wizardStep: 'registration', wizardOrder: 27, requiredInWizard: false },
+    { key: 'app.register.requestData', wizardStep: 'registration', wizardOrder: 28, requiredInWizard: false },
+    { key: 'app.register.acceptStats.default', wizardStep: 'registration', wizardOrder: 29, requiredInWizard: false },
+    { key: 'app.register.acceptDataSharing.default', wizardStep: 'registration', wizardOrder: 30, requiredInWizard: false },
+    { key: 'app.register.terms', wizardStep: 'general', wizardOrder: 5, requiredInWizard: false },
+    // Optional Moodle (wizardStep moodle keeps Settings > Moodle grouping; shown on General screen in SetupWizard)
+    { key: 'rpc.moodleAPI.apiUrl', wizardStep: 'moodle', wizardOrder: 31, requiredInWizard: false },
+    { key: 'rpc.moodleAPI.apiKey', wizardStep: 'moodle', wizardOrder: 32, requiredInWizard: false },
+    { key: 'rpc.moodleAPI.courseID', wizardStep: 'moodle', wizardOrder: 33, requiredInWizard: false },
+    { key: 'rpc.moodleAPI.showInput.apiUrl', wizardStep: 'moodle', wizardOrder: 34, requiredInWizard: false },
+    { key: 'rpc.moodleAPI.showInput.apiKey', wizardStep: 'moodle', wizardOrder: 35, requiredInWizard: false },
+    { key: 'rpc.moodleAPI.showInput.courseID', wizardStep: 'moodle', wizardOrder: 36, requiredInWizard: false },
+];
+
+/** @type {import('sequelize-cli').Migration} */
+module.exports = {
+    async up(queryInterface, Sequelize) {
+        for (const { key, wizardStep, wizardOrder, requiredInWizard } of WIZARD_SETTINGS) {
+            await queryInterface.sequelize.query(
+                `UPDATE setting
+                 SET "showInWizard" = true,
+                     "wizardStepId" = (SELECT id FROM wizard_step WHERE key = :wizardStep),
+                     "wizardOrder" = :wizardOrder,
+                     "requiredInWizard" = :requiredInWizard,
+                     "updatedAt" = :now
+                 WHERE key = :key`,
+                {
+                    replacements: { key, wizardStep, wizardOrder, requiredInWizard, now: new Date() },
+                    type: Sequelize.QueryTypes.UPDATE,
+                }
+            );
+        }
+    },
+
+    async down(queryInterface, Sequelize) {
+        for (const { key } of WIZARD_SETTINGS) {
+            await queryInterface.sequelize.query(
+                `UPDATE setting SET "showInWizard" = false, "wizardStepId" = NULL, "wizardOrder" = NULL, "requiredInWizard" = false, "updatedAt" = :now WHERE key = :key`,
+                {
+                    replacements: { key, now: new Date() },
+                    type: Sequelize.QueryTypes.UPDATE,
+                }
+            );
+        }
+    },
+};

backend/db/migrations/20260223130010-basic-setting-app_setup.js

@@ -0,0 +1,42 @@
+'use strict';
+
+/** @type {import('sequelize-cli').Migration} */
+module.exports = {
+    async up(queryInterface, Sequelize) {
+        const now = new Date();
+        await queryInterface.bulkInsert('setting', [
+            {
+                key: 'app.setup.wizardCompleted',
+                value: 'false',
+                type: 'boolean',
+                description: 'Internal setup wizard completion state.',
+                onlyAdmin: true,
+                showInWizard: false,
+                requiredInWizard: false,
+                deleted: false,
+                createdAt: now,
+                updatedAt: now,
+                deletedAt: null,
+            },
+            {
+                key: 'app.setup.wizardCurrentStep',
+                value: '0',
+                type: 'integer',
+                description: 'Internal setup wizard current step.',
+                onlyAdmin: true,
+                showInWizard: false,
+                requiredInWizard: false,
+                deleted: false,
+                createdAt: now,
+                updatedAt: now,
+                deletedAt: null,
+            },
+        ], {});
+    },
+
+    async down(queryInterface, Sequelize) {
+        await queryInterface.bulkDelete('setting', {
+            key: ['app.setup.wizardCompleted', 'app.setup.wizardCurrentStep'],
+        }, {});
+    },
+};