Sandbox Environment

The development sandbox serves as an isolated environment for local development and testing, separate from the live system. This setup grants full control over local data and mock interfaces.

Pre-requisites

• Docker Desktop must be installed and running on your machine.
  • For Windows, WSL2 is required.
  • For macOS (Intel or Apple Silicon), ensure Docker Desktop is configured to use the appropriate architecture.

Getting Started

1. Switch to sandbox folder

cd sandbox

1. Create three directories to mount volumns for mongodb,postgres and mailpit.

mkdir -p ./mnt/mongodb
mkdir -p ./mnt/postgres
mkdir -p ./mnt/mailpit

If you have data version conflict errors due to existing mount volumes, please delete the directories and recreate them.

1. Set environment variable MACHINE_HOST_IP to your ip address using the command

For WSL/Linux:

export MACHINE_HOST_IP=$(hostname -I | awk '{print $1}')

or For Mac M1/M2:

export MACHINE_HOST_IP=$(ipconfig getifaddr en0)

1. To create the sandbox environment, utilize local Docker container instances with docker-compose:

For WSL/Linux:

docker-compose up --build [-d]

or For Mac M1/M2:

docker-compose -f docker-compose.yml -f docker-compose-arm64.yml up --build [-d]

You can add the -d flag to run the containers in daemon mode.

Ensure that neither MongoDB nor Mongosh is installed on your local machine, as they may interfere with the database schema managed by Prisma, which connects to the MongoDB Docker container. If you have either installed, you can remove them by following the instruction provided in this link: uninstall mongodb and mongosh

Services

Within the local Docker container environment, 10 services are available:

1. Keycloak Handles user authentication for the application via browser-based login.

2. Keycloak Provision Provisions the local Keycloak realm, clients, and users.

3. PostgreSQL Serves as the database for Keycloak.

4. MongoDB Serves as the database for the local application; you can use MongoDB Compass to explore the local database.

5. Microsoft 365 Mock A mock server for Microsoft Graph API endpoints.

6. CHES Mock Simulates the Common Hosted Email Service (CHES) for local email delivery and testing.

7. NATS Acts as the message broker for communication with the Provisioner.

8. NATS Provision A mock Provisioner service for handling provisioning requests.

9. WeasyPrint Server Converts HTML and CSS content into downloadable PDF documents.

10. Mailpit A lightweight email testing tool that captures and inspects outgoing emails.

    • See Mailpit GitHub Repository for more details.

For complete service definitions, refer to the docker-compose.yml file.

Access Details

• Keycloak (HTTP): http://localhost:8080
• Keycloak (HTTPS): https://localhost:8443
• Keycloak Realm: platform-services
• Keycloak Client ID: pltsvc
• Keycloak Client Secret: testsecret
• MongoDB URL: mongodb://localhost:27017
• Microsoft 365 Proxy URL: http://localhost:8000
• CHES Mock URL: http://localhost:3025
• Mailpit URL: http://localhost:8025

Mock user details can be found in the mock-users.json file. Passwords are derived by converting user email addresses to lowercase.