Development Environment

This document assumes a windows based development environment.

Required Software

mysql or mariadb
- Suggest installing MAMP (https://www.mamp.info/). This also starts apache which isn’t used, but provides phpMyAdmin for high level database Management
visual studio code (https://code.visualstudio.com/)
github desktop (https://desktop.github.com/) - you’ll probably need a github account first
python (https://www.python.org/)

Required account access

github (https://github.com/)

Development System Configuration

create config directory
- get examples from Lou
- create <app>.cfg
- create users.cfg

create and populate python virtual env (https://docs.python.org/3/library/venv.html)

python3 -m venv venv
venv\scripts\activate # or on linux source venv/bin/activate
pip install -r requirements.txt

create and populate databases (MySQL Database Management)
- get sql import files from Lou

Shell file permissions

If a shell file is created in a Windows development environment, it won’t have execute permission when pushed to a Linux target. See http://blog.lesc.se/2011/11/how-to-change-file-premissions-in-git.html

After creating and committing the file, change its permissions in git

git update-index --chmod=+x .\app\src\dbupgrade_and_run.sh

then commit as normal

Docker files

Example docker files can be found at https://github.com/louking/webmodules, with the latest docker-skeleton-vx.x tag

vscode launch.json

For debugging, you’ll need the following in vscode’s launch.json

// https://code.visualstudio.com/docs/containers/docker-compose#_python
{
    "name": "Python: Remote Attach",
    "type": "python",
    "request": "attach",
    "port": 5678,
    "host": "localhost",
    "pathMappings": [
        {
            "localRoot": "${workspaceFolder}/app/src",
            "remoteRoot": "/app"
        }
    ],
    "justMyCode": false
},

Development vs Production via docker compose

Build and start app in development, no debugging

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build -d

Build and start app in development, with debugging

Run

docker compose -f docker-compose.yml -f docker-compose.dev.yml -f docker-compose.debug.yml up --build -d

then start debugger with vscode

Build and start app in Production

docker compose -f docker-compose.yml -f docker-compose.prod.yml up --build -d

Development Workflow

See https://docs.github.com/en/get-started/quickstart/contributing-to-projects

Synopsys:

fork repository on GitHub
clone fork on development workstation
create a branch for a given change
test change in development environment
push change to forked repository
generate a pull request