Installation and first use

For an existing installation, sign in and start with Prepare a study plan. Installation requires Docker with Compose and Python for the configuration helper.

python3 tools/configure.py
docker compose up --build -d

Open the configured APP_PORT (default http://localhost:8080). The host binding follows compose.yaml; configure host/network access appropriately. First-account setup is available only while no account exists. Add reviewer accounts through Administration before assigning them.

  1. Create a study and its plan.
  2. Create a run and start continuous collection.
  3. Inspect partial results, then pause before saving reviews.

Appearance and review tasks

Use Dark mode in the header to switch between light and dark. The portal follows your system's appearance setting until you choose a theme. Your choice is saved in the current browser and applies across portal pages.

After signing in, open My reviews in the header to find your pending reviews, adjudications and submitted tasks. Select Inspect and review to open a candidate and its evidence. See the review workflow for assignment and review details.

An optional synthetic demonstration creates fictional material without external requests. It is for learning, not a research result. It is never created automatically.

Stop services with docker compose stop; restart with docker compose up -d. Named database volumes survive image rebuilds and normal stops. Do not remove volumes to update the application. Read maintenance and backups before changing persistent services.

For remote access, configure allowed hosts and CSRF origins, protect secrets, and terminate HTTPS with the appropriate proxy/settings. No account, real study or collected dataset belongs in the distributable application image.

Sign-in via Logto

Logto runs as an optional Compose service with its own PostgreSQL volume. First configure a separate LOGTO_POSTGRES_PASSWORD in .env using openssl rand -hex 32. Start the test inbox before the identity service.

docker compose up -d --wait mailpit
docker compose up -d --wait logto

Mailpit listens at http://localhost:8025. Open the Logto Console at http://localhost:13002 and create its initial console administrator. When working from another machine, forward these two loopback ports over SSH. Leave the console and inbox bound to loopback.

The public issuer is https://vavazao.quixada.ufc.br/oidc. Install the site's configuration from deploy/nginx/vavazao.quixada.ufc.br.conf and validate it on the host. The site uses the Let's Encrypt files for that domain and proxies the sign-in service to loopback port 13001.

sudo install -m 0644 deploy/nginx/vavazao.quixada.ufc.br.conf /etc/nginx/sites-available/vavazao.quixada.ufc.br.conf
sudo ln -s /etc/nginx/sites-available/vavazao.quixada.ufc.br.conf /etc/nginx/sites-enabled/vavazao.quixada.ufc.br.conf
sudo nginx -t
sudo systemctl restart nginx
curl -fsS https://vavazao.quixada.ufc.br/oidc/.well-known/openid-configuration

Complete the application and sign-in configuration in the Logto Console.

  1. Go to Applications → My apps → Create application. In the framework picker, choose Create app without framework, then select Traditional Web and name it IRTF to IETF Research Kit. A client created under Third-party apps requires separate permissions for the OIDC scopes requested by the portal. Register https://irtf2ietf.quixada.ufc.br/login/oidc/callback/ as the redirect URI. For a workstation-only test, register the exact local portal URL plus /login/oidc/callback/.
  2. Add the SMTP email connector. In Parameter configuration, set Host to mailpit, Port to 1025, Auth to {"type":"login"}, and From Email to IRTF to IETF Research Kit <research-kit@example.invalid>. Leave Secure off for Mailpit. Omit the username and password. The Console discards an empty Auth object when saving, so include the login type. Run python3 tools/logto_smtp_config.py | python3 -c 'import json, sys; print(json.dumps(json.load(sys.stdin)["templates"], indent=2))' and paste the resulting array into Templates. The generator's --logo-url option sets the absolute PNG image URL if the portal is hosted elsewhere.
  3. Under Sign-in & account → Sign-up and sign-in, enable email and verification code for sign-in and sign-up. Under Sign-in & account → Branding, use https://irtf2ietf.quixada.ufc.br/static/portal/research-kit-email-logo.png as the company logo and #173d47 as the light brand color. Paste the contents of deploy/logto/sign-in.css into Custom CSS → CSS overrides, save, then check Live Preview. Enable an authenticator app or passkey for privileged sign-in.
  4. Set LOGTO_CLIENT_ID and LOGTO_CLIENT_SECRET in the portal's .env. Set SMTP_HOST=mailpit and SMTP_PORT=1025 for Django test mail. Run docker compose up --build -d web to apply the portal migrations and load the configuration.

Use Sign in with email for an existing account or Sign up to open registration directly in Logto. The portal checks the account's role and requests MFA from Logto for administrators and managers before opening a privileged session. Existing users who need account recovery or migration can sign in with their current password at /login/legacy/, then choose Link sign-in and verify their email in Logto. The link keeps their user record, username and assignments. New OIDC accounts can sign in and receive assignments through the existing distribution workflow. In Django Administration, use membership in Managers to grant creation of studies and keep Admin access with Django superusers. The migration adds existing study owners to Managers.

Mailpit captures codes even when the recipient is a Gmail address. For delivery to Gmail, configure a real SMTP relay in both Logto and Django using an authorized sender and the relay's TLS settings. The email template uses inline styles and keeps the portal name and code visible when remote images are disabled.

The Compose controller also refills automatic review queues and sends new-task notices. Set SMTP_HOST=mailpit and SMTP_PORT=1025 to test Django's notices locally. Set PORTAL_PUBLIC_URL to the HTTPS address reviewers use so email links open My reviews.