Skip to main content

Local Development Guide

This guide covers setting up dependencies for running the People Portal locally.

Cloning the Repositories​

Before starting, clone the essential repositories to your local workspace:

script.bash
# The backend servergit clone https://github.com/candiedoperation/PeoplePortalServer.git# The frontend UIgit clone https://github.com/candiedoperation/PeoplePortalUI.git# The documentation wiki# We encourage you to run this locally and continually document your work as you go!git clone https://github.com/candiedoperation/AppDev-CorpWiki.git

MongoDB Atlas​

For the database, we use MongoDB Atlas. To set it up for local development:

  1. Create an account on MongoDB Atlas.
  2. Create a new project and cluster.
  3. In the Database Access section, create a new user with read/write permissions.
  4. In the Network Access section, add your IP address (or 0.0.0.0/0 for broad access during development).
  5. Copy the connection string and set it as PEOPLEPORTAL_MONGO_URL in your server .env file.

Authentik Setup​

People Portal relies heavily on Authentik for OIDC authentication. You can host an Authentik instance locally using Docker Compose.

Docker Compose​

Create a docker-compose.yml file for Authentik in a local directory configuration of your choosing:

script.yaml
services:  postgresql:    env_file:      - .env    environment:      POSTGRES_DB: ${PG_DB:-authentik}      POSTGRES_PASSWORD: ${PG_PASS:?database password required}      POSTGRES_USER: ${PG_USER:-authentik}    healthcheck:      interval: 30s      retries: 5      start_period: 20s      test:        - CMD-SHELL        - pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}      timeout: 5s    image: docker.io/library/postgres:16-alpine    restart: unless-stopped    volumes:      - database:/var/lib/postgresql/data  server:    command: server    depends_on:      postgresql:        condition: service_healthy    env_file:      - .env    environment:      AUTHENTIK_POSTGRESQL__HOST: postgresql      AUTHENTIK_POSTGRESQL__NAME: ${PG_DB:-authentik}      AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}      AUTHENTIK_POSTGRESQL__USER: ${PG_USER:-authentik}      AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY:?secret key required}    image: ${AUTHENTIK_IMAGE:-ghcr.io/goauthentik/server}:${AUTHENTIK_TAG:-2025.12.1}    ports:      - ${COMPOSE_PORT_HTTP:-9000}:9000      - ${COMPOSE_PORT_HTTPS:-9443}:9443    restart: unless-stopped    volumes:      - ./data:/data      - ./custom-templates:/templates  worker:    command: worker    depends_on:      postgresql:        condition: service_healthy    env_file:      - .env    environment:      AUTHENTIK_POSTGRESQL__HOST: postgresql      AUTHENTIK_POSTGRESQL__NAME: ${PG_DB:-authentik}      AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}      AUTHENTIK_POSTGRESQL__USER: ${PG_USER:-authentik}      AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY:?secret key required}    image: ${AUTHENTIK_IMAGE:-ghcr.io/goauthentik/server}:${AUTHENTIK_TAG:-2025.12.1}    restart: unless-stopped    user: root    volumes:      - /var/run/docker.sock:/var/run/docker.sock      - ./data:/data      - ./certs:/certs      - ./custom-templates:/templatesvolumes:  database:    driver: local

Environment Variables (.env)​

Next to your docker-compose.yml, create a .env file that includes the necessary variables. Ensure you replace the placeholder values securely:

script.env
PG_DB=authentikPG_USER=authentikPG_PASS=your_secure_postgres_passwordAUTHENTIK_SECRET_KEY=your_secure_randomly_generated_secret_keyCOMPOSE_PORT_HTTP=9000COMPOSE_PORT_HTTPS=9443AUTHENTIK_ERROR_REPORTING=true

Run docker compose up -d to start Authentik. Then, navigate to http://localhost:9000/if/flow/initial-setup/ to complete the initial setup and retrieve your initial user details (the default admin user is akadmin).

Authentik Application and Provider Configuration​

Once Authentik is running, configure the Application and Provider to allow People Portal to authenticate users.

  1. Log in to your Authentik instance as akadmin.
  2. Navigate to Applications > Applications.
  3. Click Create with Provider and enter:
    • Name: People Portal
    • Provider Type: OAuth2/OpenID Provider
  4. In the Provider settings configuration:
    • Authorization flow: Select default-provider-authorization-implicit-consent
    • Client Type: Confidential
    • Redirect URIs: http://localhost:3000/api/auth/redirect (Replace 3000 with your backend server's port if running on a different port locally).
  5. Take note of the Client ID and Client Secret. These correspond to the PEOPLEPORTAL_OIDC_CLIENTID and PEOPLEPORTAL_OIDC_CLIENTSECRET environment variables on your People Portal server.

Defining the people_portal Scope​

For People Portal to work, ensure the openid, profile, email, and a custom people_portal scope are configured in your OpenID Provider.

To create the custom people_portal scope in Authentik:

  1. Navigate to Customization > Property Mappings.
  2. Click Create and select Scope Mapping (Map an OAuth Scope to User Properties).
  3. Enter the following variables:
    • Name: People Portal Scope
    • Scope Name: people_portal
  4. Use the following Python code for the filtering expression:
    script.python
    return {    "pk": request.user.pk,    "is_superuser": request.user.is_superuser,    "attributes": request.user.attributes}
  5. Click Create.
  6. Go back to your People Portal Provider settings, under Advanced Protocol Settings, and add this new scope along with openid, profile, and email.

(For further details, refer to the OpenID Provider Configuration and Environment Variables docs).

Gitea Setup​

Gitea is utilized for localized source version control integrated within People Portal. You can easily get it running via another Docker Compose file:

script.yaml
version: "3"networks:  gitea:    external: falseservices:  server:    image: gitea/gitea:1.21.0    container_name: gitea    environment:      - USER_UID=1000      - USER_GID=1000      - GITEA__database__DB_TYPE=sqlite3    restart: always    networks:      - gitea    volumes:      - ./gitea:/data      - /etc/timezone:/etc/timezone:ro      - /etc/localtime:/etc/localtime:ro    ports:      - "10000:3000"      - "222:22"

Launch the stack with docker compose up -d and navigate to http://localhost:10000 to finish the web initial configuration. Because it uses an SQLite setup for local dev, an external database instance isn't required.

Once configured, generate an administrator token within Gitea and map it to PEOPLEPORTAL_GITEA_TOKEN, keeping PEOPLEPORTAL_GITEA_ENDPOINT appropriately set to your web URL http://localhost:10000 or comparable port.

Running the Applications Locally​

The People Portal is split into two repositories: the backend server (PeoplePortalServer) and the frontend UI (PeoplePortalUI).

1. People Portal Server (Backend)​

The backend handles all business logic, database connections, and authentication workflows.

Environment Variables​

Ensure the .env file in the root of the PeoplePortalServer repository contains all the necessary variables. For a complete list, see the Environment Variables guide.

Here is an example .env configuration combining what we've set up above for local testing:

script.env
# Application BasePEOPLEPORTAL_BASE_URL=http://localhost:3000PEOPLEPORTAL_TOKEN_SECRET=your_secure_local_token_secretPORT=3000# MongoDBPEOPLEPORTAL_MONGO_URL=mongodb+srv://<user>:<password>@<cluster-url>/<dbname>?retryWrites=true&w=majority# Authentik OIDCPEOPLEPORTAL_OIDC_DSCVURL=http://localhost:9000/application/o/people-portal/.well-known/openid-configurationPEOPLEPORTAL_OIDC_CLIENTID=your_authentik_client_idPEOPLEPORTAL_OIDC_CLIENTSECRET=your_authentik_client_secret# Authentik Admin ClientPEOPLEPORTAL_AUTHENTIK_ENDPOINT=http://localhost:9000PEOPLEPORTAL_AUTHENTIK_TOKEN=your_authentik_service_account_token# GiteaPEOPLEPORTAL_GITEA_ENDPOINT=http://localhost:10000PEOPLEPORTAL_GITEA_TOKEN=your_gitea_admin_token# Node TLS (Only strictly necessary if connecting to instances with self-signed certs)# NODE_TLS_REJECT_UNAUTHORIZED=0

Starting the Server​

With your .env configured inside the backend repo, install the dependencies and start the local development server:

script.bash
cd PeoplePortalServer# Install dependenciesnpm install# Start the development servernpm run dev

The backend server should now be live at http://localhost:3000.

2. People Portal UI (Frontend)​

The frontend is built with Vite and React. In local development, the UI server will automatically proxy /api requests to your running backend (http://localhost:3000).

Starting the UI​

No separate .env file is required for local UI development.

script.bash
cd PeoplePortalUI# Install dependenciesnpm install# Start the Vite development UInpm run dev

The UI will typically start on http://localhost:5173. Open this URL in your web browser to view your local People Portal. With both running, the frontend will be able to utilize your backend context and dependencies!

Copyright © 2026 Atheesh Thirumalairajan