Skip to content

Latest commit

 

History

History
156 lines (112 loc) · 6.96 KB

HACKING.md

File metadata and controls

156 lines (112 loc) · 6.96 KB

HACKING.md

About gpx.skolbacken.com

A simple tool for converting .gpx files to text for upload to artportalen.se. It works like this:

  1. The user uploads a .gpx file that is processed and returned as a table.
  2. The user can edit and select which rows to include. The application can highlight misspelled and mal-formatted entries and provide corrections from a dictionary.
  3. The user can copy the result to clipboard as plain text by pressing a friendly button.

Tech stash overview:

  • FastAPI - like regular APIs but also fast
  • jinja2 - {{ funny_description|censor_words }}
  • Hatchling - package build system
  • htmx - the wheel reinvented for the last time, again
  • Pico css - unintrusive css framework
  • Fontawesome icons - the path of least resistance

Deployment

This repo builds a docker image that is manually deployed on Google Cloud Run.

Table of Contents

Quickstart: scripts/patience.sh

Convenience script that builds and runs the container.

REQUIRES docker

ARGUMENTS engine: optional path to container runtime. (Default is "docker")

$ scripts/patience.sh [path/to/engine]

Installation

REQUIRES python >= 3.10, pip

You can install the gpx2artdata module and its dependencies using the pip.

$ pip install .

If you want to install the api environment, specify the server optional dependency group.

NOTE This does not install the actual application, which lives in main.py

$ pip install .[server]

For development, please use the [dev] group and pass the -e flag to make the installation ediatable-in-place.

TIP Use a virtual environment like a sane person.

$ pip install -e .[dev]

There are some optional libraries in the build dependency group. Install this if you need to work with the assets, for example regenerate the tutorial videos with the scripts/build-assets.sh script.

$ pip install .[build]

Develop

REQUIRES python > 3.10, pip

Use scripts/dev-setup.sh to set up a local development environment.

IMPORTANT The script preserves any configuration done in local.env but unconditionally torches your .venv folder.

  1. Install build dependencies into a new virtual environment:

    $ scripts/dev-setup.sh

  2. Use venv:

    $ source .venv/bin/activate

  3. Run a development server:

    a. Use fastapi-cli:

    (.venv)
$ ./dev-server.sh

    b. Invoke uvicorn from the main python script. I find this easier to debug.

    (.venv) 
$ python main.py

Runtime environment

NOTE The containerized server will run in production mode by default. For building and testing locally without a https proxy, set $PRODUCTION=False.

See local.env.example for example values.

  • $PRODUCTION Disables the documentation endpoints and ensures that all generated URLs are https://
  • $WEBSITE_HOSTNAME Used for showing link to new URL
  • $PROTOCOL (optional) Defaults to https in production mode, but http is used by dev-server.sh
  • $STATIC_URL (optional) Set to fully qualified URL if the static/ endpoint is served from a different location. This is also needed to ensure https under various proxy setups.
  • $BUILD_VERSION displays in page footer

JavaScript and frontend parts

WARNING The main.js component is developed ad-hoc by an absolute amateur. Several conflicting best practices are pursued simultaneously. There is no toolchain. Good luck.

This application relies on htmx for asynchronous requests and DOM patching. There really isn't that much to it. See main.py: is_htmx().

Generating dictionary.js

REQUIRES API key to Artdata - Taxon List Service

NOTE Do not expect scripts/update-dictionary.sh to work, it is outdated.

static/dictionary.js contains a list used for auto-suggesting taxon names and spell checking. It is provided mostly as a guideline to help users correct obvious mistakes, there is no guarantee that the output will work at artportalen.se.

Functions for fetching and filtering taxon data are in scripts/species_list.py. Some manual labour will be needed if you want to produce a new dictionary file.

Versioning

INFO This package uses Semantic Versioning.

ARGUMENTS scripts/bump-version.sh accepts either a full version string like 1.5.2, or one of the keywords major, minor and patch. If a second argument is provided it will be used as a description for the new version tag.

Versioning is provided by hatch. Use scripts/bump-version.sh to generate the CHANGELOG.md.

Test

There is a simple sanity check in the tests folder.

Build

REQUIRES docker or podman (untested).

ARGUMENTS env_file, path to a .env file. Default is local.env

Use scripts/build.sh to build a container image. See local.env.example and Runtime environment for configuration options.

  • NOTE The default entrypoint (server.sh) runs the server with --proxy-headers. The reason is this.

Deploy

REQUIRES gcloud (Google Cloud platform CLI) and authentication

ENVIRONMENT Copy gcloud.env.example to gcloud.env and edit to match your life situation.

This repo is configured to build and push a docker image to the Google Cloud/Artifact registry with a minimal amount of Google lock-in bullshit.

Use scripts/gcloud-push.sh to build and push the image. Configuring the required Google Cloud Artifact registry is beyond the scope of this guide. I found this article helpful.

NOTES on gcloud-push.sh

  • Aborts if the repo is not clean-ish.
  • If the script is run with any argument it will just build the container. IDK just so you know.

License

gpx2artdata is distributed under the terms of the MIT license.