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

Due to BC Government procurement restrictions, Docker Desktop is not permitted. However, the following alternatives are approved:

• Docker Engine (with Docker CLI)
• Podman
• Rancher Desktop

Docker Setup

MacWindows

1. brew install docker
2. brew install docker-compose
3. brew install docker-buildx
4. Add symlinks in ~/.docker/cli-plugins
   1. ln -s $HOMEBREW_PREFIX/lib/docker/cli-plugins/docker-buildx docker-buildx
   2. ln -s $HOMEBREW_PREFIX/lib/docker/cli-plugins/docker-compose docker-compose
5. Login to docker
   1. docker login
6. Start VM. Example (using podman):
   1. podman machine init
   2. podman machine start

Refer to these blog posts on how to install Docker without Docker Desktop:

• How to install wsl2 ubuntu + docker + docker-compose
• Mastering Docker on WSL2: A Complete Guide Without Docker Desktop
• Installing Docker, and Docker-Compose, in WSL2/Ubuntu on Windows

Getting Started

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

In the root of the project directory:

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

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

1. Run the sandbox environment

The Makefile uses docker-compose.

For WSL/Linux:

make sandbox

To run in detached mode:

make sandbox SBD=true

For Mac M1/M2

make localmac

To run in detached mode:

make localmac SBD=true

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.