Docker Compose configuration for running WebProtege.

cp .env.example .env
docker compose up -d

Then open http://webprotege-local.edu in your browser, click Register to create an account, and sign in.

First time? You need to add webprotege-local.edu to your hosts file before this will work. See Configure Local Host Resolution below.

The Docker daemon must be running. Verify with:

docker info

If this fails, start Docker through Docker Desktop or your system's service manager.

WebProtege uses a custom hostname for cookie handling and Keycloak authentication flows. Add this line to your system's hosts file:

127.0.0.1  webprotege-local.edu

Hosts file location:

• Linux/macOS: /etc/hosts (edit with sudo nano /etc/hosts)
• Windows: C:\Windows\System32\drivers\etc\hosts (edit as Administrator)

Self-hosted deployments using their own domain can skip this step and set SERVER_HOST in .env to their public hostname instead.

Copy the example environment file:

cp .env.example .env

The defaults are suitable for local development. Self-hosted deployments should edit .env and change SERVER_HOST to the public hostname.

See .env.example for documentation of each variable.

Start all services:

docker compose up -d

Keycloak will automatically import the WebProtege realm, configure the protocol mappers, and set up redirect URIs on first boot. This is handled by the webprotege-keycloak image's entrypoint script — no manual Keycloak setup is required.

To follow startup progress:

docker compose logs -f webprotege-keycloak

Look for [entrypoint] Realm configuration complete. to confirm the realm is ready. Press Ctrl+C to stop following logs.

Open your browser and go to:

http://webprotege-local.edu

Use the custom domain (not localhost) to ensure proper cookie handling and authentication flow between WebProtege and Keycloak.

1. Click Register on the login page
2. Fill out the registration form (email, password, name)
3. Click Register

After registration, sign in with your email and password.

Successful login indicators:

• Redirect to the WebProtege home page
• Your name appears in the top navigation
• You see options to create or access ontology projects

On a fresh install, no user has administrative access. The first registered user must be granted the SystemAdmin role in Keycloak before WebProtege's admin features (creating projects, managing users, editing application settings) become available.

This is a one-time manual step per install. A config-driven alternative is tracked in webprotege-authorization-service#36.

1. Sign in to the Keycloak admin console at:

   http://webprotege-local.edu/keycloak/admin/
   

   Use the credentials from KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD in your .env file. Change these from the defaults before any deployment that is reachable beyond your local machine.

2. In the left sidebar, switch the realm dropdown from master to webprotege.

3. Navigate to Clients → webprotege → Roles → SystemAdmin → Users in role (or Assign users, depending on Keycloak version).

4. Assign the role to the user account you registered earlier.

5. Sign out of WebProtege and sign back in — the new role is picked up from the fresh JWT. You now have full admin access.

By default, only users with an explicit ProjectCreator role assignment can create new projects. To let any signed-in user create projects:

1. In WebProtege, navigate to Application Settings (admin menu).
2. Enable Empty project creation allowed.
3. Save.

The stack includes the following services:

Stop all services (preserves data):

docker compose down

Stop and delete all data (full reset):

docker compose down -v

Reset Keycloak only (forces realm re-import on next start):

docker compose down
docker volume rm webprotege-deploy_keycloak-h2-directory
docker compose up -d

To verify the webprotege_username mapper is working correctly, check the backend logs after signing in:

docker compose logs webprotege-backend-service | grep "from user"

The userId should show the webprotege_username value (e.g., johardi), not the email address.

Port conflicts: If a port is already in use, check which service uses that port in the table above and modify the host port mapping in docker-compose.yml.

Permission errors: Ensure your user has permissions to modify the hosts file and run Docker commands.

Service startup failures: Check logs for a specific service:

docker compose logs <service-name>

Authentication issues: Verify that SERVER_HOST in .env matches your hosts file entry. Check the Keycloak entrypoint logs:

docker compose logs webprotege-keycloak | grep "\[entrypoint\]"

WebProtege requires an SMTP server for the migrated user password reset flow. In development, Mailpit is included in docker-compose.yml and catches all outgoing email. Access the Mailpit inbox at http://webprotege-local.edu:8025.

The SMTP settings are defined in the Keycloak realm JSON (webprotege.json) under smtpServer.