Ontwikkelen: Lokaal

Ontwikkelomgeving inrichten via Docker

Notitie

Ik gebruik JetBrain’s PyCharm IDE om lokaal te ontwikkelen. Deze heeft ingebouwde ondersteuning voor Git en Docker, dus het kan zijn dat informatie of stappen hieronder wat afwijken van je eigen situatie.

  • Installeer Docker op je systeem. Bijvoorbeeld voor Ubuntu: https://docs.docker.com/engine/install/ubuntu/ en overweeg rootless: https://docs.docker.com/engine/security/rootless/

  • Kloon DSMR-reader repository van GitHub:

    git clone ... (your fork)
    cd dsmr-reader/
    
  • Symlink benodigde Docker-bestanden (of kopiëer ze):

    # Either symlink
    ln -s dsmrreader/provisioning/container/Containerfile-dev Containerfile
    ln -s dsmrreader/provisioning/container/compose.dev.yml compose.yml
    
    # Or copy
    cp dsmrreader/provisioning/container/Containerfile-dev Containerfile
    cp dsmrreader/provisioning/container/compose.dev.yml compose.yml
    
  • Kopieer Django settings-template:

    cp dsmrreader/provisioning/django/settings.py.template dsmrreader/settings.py
    
  • Open de settings-template dsmrreader/settings.py die je net gekopieerd hebt en vervang:

    from dsmrreader.config.production import *
    
  • Met:

    from dsmrreader.config.development import *
    
  • Probeer Docker (compose):

    # This should build all the containers for local development
    docker-compose up -d
    
  • Zijn de containers gebouwd? Probeer of dit werkt:

    docker exec -it dsmr-app poetry run /usr/src/app/manage.py check
    
    # Expected output: "System check identified no issues (0 silenced)"
    
  • Probeer nu of de tests goed draaien met SQLite:

    ./tools/test-quick.sh
    

Tip

Andere DB-engines kunnen ook getest worden, maar dit doet de CI ook al. De SQLite-engine ondersteunt overigens 99%% van de features die DMSR-reader nodig heeft. Daarnaast draait deze ook in-memory, waardoor de tests weer sneller draaien.

  • Wanneer je PyCharm gebruikt kun je een nieuwe Interpreter toevoegen die Docker Compose gebruikt. Selecteer dsmr-app en stel /opt/venv/bin/python in als interpreter path. Nu zouden alle gebruikte dependencies goed gemapt moeten worden vanuit de container.

Initiele gegevens om mee te ontwikkelen

De beste gegevens om mee te ontwikkelen zijn eerlijk gezegd simpelweg gegevens uit je eigen productieomgeving.

Gevaar

Voorkom dat je (achtergrond)processen draait in je lokale DSMR-reader ontwikkelomgeving, totdat je alle externe diensten hebt ontkoppeld.

Voer simpelweg het volgende uit, na het importeren van een backup uit je eigen productieomgeving:

docker exec -it dsmr-app poetry run /usr/src/app/manage.py development_reset

Dit verwijdert alle API-keys en andere koppelingen naar externe systemen. Tevens wordt de admin-gebruiker gereset naar admin / admin (gebruiker / wachtwoord).

Importeer deze zoals je dat ook zou doen op je RaspberryPi. Kopieer een database-backup naar /var/lib/postgresql op je PC en importeer deze met:

# NOTE: Some what broken when using Docker. But this was the legacy method:
# Create empty database if it does not exist yet.
sudo -u postgres createdb -O dsmrreader dsmrreader

# For .SQL
sudo -u postgres psql dsmrreader -f <PATH-TO-POSTGRESQL-BACKUP.sql>

# For .SQL.GZ
zcat <PATH-TO-POSTGRESQL-BACKUP.sql.gz> | sudo -u postgres psql dsmrreader

Nep datalogger

Tip

Er is een ingebouwd command voor een soort van datalogger die nepdata genereert:

docker exec -it dsmr-app poetry run /usr/src/app/manage.py dsmr_fake_datasource --with-gas --with-electricity-returned

Deze genereert elke seconde willekeurige gegevens in een bepaald patroon en is vaak meer dan afdoende voor simpele testdoeleinden.

Hiermee worden alleen onverwerkte metingen aangemaakt. Je zult ze nog steeds moeten verwerken door het volgende uit te voeren:

docker exec -it dsmr-app poetry run /usr/src/app/manage.py dsmr_backend --run-once

DSMR-reader lokaal draaien

Wanneer je de standaard Docker compose configuratie gebruikt, is de dsmr-app Django Development Server applicatie toegankelijk op: http://localhost:8000/.

Wijzigingen aan Python-bestanden zorgen ervoor dat de Django Development Server zichzelf automatisch herlaadt.

Tests en dekking

DSMR-reader’s testdekking zou zo hoog mogelijk moeten blijven, alhoewel dat niet perse wat zegt over de kwaliteit van de tests. Zoek hier een middenweg in.

De makkelijkste manier om tests te draaien is via de SQLite (in-memory) tests:

docker exec -it dsmr-app poetry run ./tools/quick-test.sh

Om een enkele app binnen DSMR-reader te testen, geef je deze simpelweg als extra argument op:

docker exec -it dsmr-app poetry run ./tools/quick-test.sh dsmr_frontend

De test dekking zou na het draaien van tests zichtbaar moeten zijn in de terminal. Er zijn tevens gedetaileerde HTML-pagina’s beschikbaar in coverage_report/html/index.html, na het draaien van tests. Je kunt deze openen met je browser om de test dekking in detail te zien per bestand en per regel code.

Notitie

Een mogelijk bijeffect van het draaien van tests is dat hiermee ook .PO-bestanden in de docs/ map bijgewerkt worden. Als je daar geen wijzigingen in hebt gedaan, kun je die door de tests gewijzigde bestanden negeren.

Vertalingen

Je kunt de vertalingen (.PO-bestanden) voor de hoofdapplicatie vinden in dsmrreader/locales/. Om ze te hergenereren voer het docker exec -it dsmr-app poetry run ./tools/check-translations.sh script uit, zodat een van de tests de vertalingen opnieuw checkt.

Documentatie bijwerken

De documentatie is onderdeel van het project en kan (automatisch) gegenereerd worden via Sphinx.

Standaard zou de Docker compose file een container moeten maken voor documentatie, per ondersteunde taal.

  • Engelstalig:

    http://127.0.0.1:10000
    
  • Nederlandstalig:

    http://127.0.0.1:10001
    

Wijzigingen die je doorvoert in Pworden direct automatisch bijgewerkt en getoond in je browser, waar Sphinx voor zorgt.

Documentatie vertalen

Vertalingen verlopen via .PO-bestanden met gettext. Hergenereer de .PO-bestanden met:

docker exec -it dsmr-docs bash -c 'poetry run make gettext && poetry run sphinx-intl update --line-width=-1 -p _build/locale -l nl'

De .PO-bestanden in docs/_locale zouden nu opnieuw gegenereerd moeten worden. Je kunt het open-source programma poedit gebruiken om de bestanden te bekijken en te vertalen.