Setup a development environment

This document will guide you on how to setup a local development environment of MicroPowerManager (MPM).

In a local development environment

• the backend is served under http://localhost:8000
• the frontend is served under http://localhost:8001

Preamble

This guide requires a Unix-like environment. Supported platforms include:

1. macOS: Any recent version of macOS (13 Ventura or later)
2. various Linux distributions (Ubuntu, Fedora, Debian)
3. Windows with Windows Subsystem for Linux 2 (WSL2)

For Windows users:

• Please ensure you have WSL2 installed and properly configured before proceeding.
• Please ensure you are running Docker Desktop in WSL2 mode.
• When opening the repository in VS Code ensure to open in WSL2 mode (for example by navigating to the source code in WSL2 terminal and running code .)

For all users:

This document assumes that you have a basic understanding of how to use the command line. You should be familiar with common Unix commands such as cd, ls, mkdir, and how to edit text files using a text editor like VS Code. Before proceeding, ensure you can open a terminal (Terminal app on macOS, terminal emulator on Linux, or WSL2 terminal on Windows) and run basic commands.

Pre-requisites

• A docker container runtime with Docker Compose (for example Docker Desktop). Make sure to configure at least 4GB of memory and 50GB disk (more doesn't hurt either) to the Docker Virtual Machine (VM).
• Working installation of git
• A Text editor (While you can use any text editor you're comfortable with, we recommend VS Code for this project)

Installation

1. git-clone the repository
2. Build and run the Docker containers with docker compose up

Migration on First run

When you run the application for the first time, you need to run the following commands to initialize the databases and load Demo data:

docker exec -it backend-dev bash
php artisan migrate --seed

This command will

• create the central database which is required for MPM to function.
• create the Demo company, it's database and run migrations
• populate the database entities with demo data

To access the local instance of MicroPowerManager open http://localhost:8001/ in a web browser.

Log in to the application using the following credentials:

username: dummy_company_admin@example.com
password: 123123

The dummy protected page password of this company is 123123.

NOTE

If you wish to run MicroPowerManage without the Demo data you can skip --seed and only run php artisan migrate.

Then you can then explore a vanilla MicroPowerManager instance, where you can register new users and tenants.

However, for a better development flow it is generally recommended to load demo data.

Generating transaction data

To generate dummy transaction data you can run

php artisan dummy:create-data 250
php artisan dummy:create-data --type=ticket 25

This commands will create 250 transactions and 25 tickets within the past 30 days respectively. It can be run multiple times to generate more data as required.

Reseting the Demo data

If you wish reset the Demo data setup to the default setup run:

docker exec -it backend-dev bash
php artisan migrate-tenant:drop-demo-company
php artisan migrate:fresh --seed

This can be helpful if

• Your sample setup got very messy and you wish to have a clean data basis for your work
• New Demo data seeders got added in the upstream code base and you wish to run them

Advanced development environment

The above instructions describe how to set up a simple local environment of MPM. This is great for exploring the project both by interacting with the app and potentially some smaller code changes.

However, if you are considering to contribute to MicroPowerManager code base it is recommended to set up some additional steps and tools for developer's convienience.

We describe an example set up that has proven to work well based on VS Code. Configurations for a different editor will work a like.

Linter configuration

The project uses various linters to ensure a consitent code base across the project. The exact linter configuration can be found here: .github/worksflows.

Install the following linter and auto-formatter extensions

• EditorConfig for VS Code
• markdownlint
• PHP CS Fixer
• PHP Intelephense
• markdownlint
• Prettier - Code Formatter

API client

We maintain a handful of API collections to interact with the backend of MPM. You can find the collections in collections folder.

NOTE

Currently, not every API of MPM is covered by a collection. Contributions to increase the coverage are welcome 🙏

• Install Bruno

To interact with APIs that require authorisation

• Select Local Development as environment
• Execute the Login API call

This will save the Authorisation Bearer token into your local variables and use them in consecutive API calls.

SQL editor

When working with the backend part of the code an SQL editor and database manager application can be extremely helpful to visualise and explore the underlying database.

Choose your favorite SQL editor with support for MariaDB (or MySQL). For example

• TablePlus
• Beekeeper Studio
• DBeaver

And configure the following database connection

• Database Type: MariaDB (or MySQL)
• Host: localhost/127.0.0.1
• Port: 3306
• User: root
• Password: Take it from .env
• Database: Leave empty if possible, as we will be interacting with multiple databases. Alternatively configure a seperate connection for each database. For example micro_power_manager and DummyCompany_1.

Vue Developer Tools

For frontend developmenet it can be helpful to use the Vue DevTools.

• Install Vue DevTools in your local browser

Troubleshooting

Docker build errors

Problem: Certain Docker build errors can be related to interfering volumes that were created in previous runs of MPM.

Solution:

If you encounter Docker build errors, try removing orphaned containers by

docker compose down --volumes --remove-orphans
docker-compose build --no-cache
docker-compose up

Containers get killed at runtime

Problem:

The containers builds fine, but when running them via docker compose up some of the containers get killed randomly without throwing an error.

The logs could contain something like this:

frontend-dev | killed

Solution:

Make sure your Docker's Virtual Machine (VM) has enough resources. For example through setting on Docker Desktop.

We recommend the following settings

• CPU: 4 or more
• Memory: 4GB or more
• Disk: 50GB or more