Scaffold an empty application using cookiecutter-webapp-deluxe

.editorconfig

@@ -0,0 +1,14 @@
+# EditorConfig helps developers define and maintain consistent
+# coding styles between different editors and IDEs
+# editorconfig.org
+
+root = true
+
+
+[*]
+
+indent_style = space
+indent_size = 4
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true

.flake8

@@ -0,0 +1,7 @@
+[flake8]
+exclude = .git,__pycache__,**/*.py
+per-file-ignores =
+    ./production.py: F401, F403
+    ./collect.py: F401, F403, E402
+    ./bootstrap.py: C901, E701
+    ./glue.py: F403, F405, E402

.github/workflows/test.yml

@@ -0,0 +1,85 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Unit tests
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - 'develop'
+      - 'main'
+      - 'feature/**'
+      - 'bugfix/**'
+      - 'hotfix/**'
+      - 'release/**'
+
+jobs:
+  build:
+
+    runs-on: ubuntu-20.04
+
+    services:
+      # Label used to access the service container
+      postgres:
+        # Docker Hub image
+        image: postgres
+        # Provide the password for postgres
+        env:
+          POSTGRES_DB: lettercraft
+          POSTGRES_USER: lettercraft_user
+          POSTGRES_PASSWORD: lettercraft_pwd
+        # Set health checks to wait until postgres has started
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          # Maps tcp port 5432 on service container to the host
+          - 5432:5432
+
+    strategy:
+      matrix:
+        python-version: ['3.8']
+        node-version: ['14.x', '16.x']
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v2
+      with:
+        node-version: ${{ matrix.node-version }}
+    - name: Install Python dependencies
+      run: |
+        cd backend
+        python -m pip install --upgrade pip
+        pip install virtualenv
+        pip install -r requirements.txt
+    - name: Lint with flake8
+      run: |
+        pip install flake8
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    - name: Run all tests
+      env:
+        # Provide PostgreSQL environment variables in order to default to TCP connection
+        PGDATABASE: lettercraft
+        PGHOST: localhost
+        PGPORT: ${{ job.services.postgres.ports['5432'] }}
+        PGUSER: lettercraft_user
+        PGPASSWORD: lettercraft_pwd
+      run: |
+        cat bootstrap_ci.txt | python bootstrap.py
+        yarn
+        yarn django migrate
+        yarn static-p
+        find static
+        yarn start-back-p &
+        chromedriver --version
+        yarn test

.gitignore

@@ -0,0 +1,36 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Temporary files
+/static/
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+*.log
+
+# Unit test / coverage reports
+.coverage
+.coverage.*
+.cache
+coverage.xml
+*.cover
+.pytest_cache/
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Node
+node_modules/
+frontend/src/environments/version.ts

.nvmrc

@@ -0,0 +1 @@
+v14.21.2

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, UU Centre for Digital Humanities - Research Software Lab
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,209 @@
+# Lettercraft & Epistolary Performance in Medieval Europe
+
+[![Actions Status](https://github.com/UUDigitalHumanitieslab/lettercraft/workflows/Unit%20tests/badge.svg)](https://github.com/UUDigitalHumanitieslab/lettercraft/actions)
+
+Lettercraft & Epistolary Performance in Medieval Europe
+
+
+## Before you start
+
+You need to install the following software:
+
+ - PostgreSQL >= 10, client, server and C libraries
+ - Python >= 3.8, <= 3.10
+ - virtualenv
+ - WSGI-compatible webserver (deployment only)
+ - [Visual C++ for Python][1] (Windows only)
+ - Node.js >= 14.20.0
+ - Yarn
+ - [WebDriver][2] for at least one browser (only for functional testing)
+
+[1]: https://wiki.python.org/moin/WindowsCompilers
+[2]: https://pypi.org/project/selenium/#drivers
+
+
+## How it works
+
+This project integrates three isolated subprojects, each inside its own subdirectory with its own code, package dependencies and tests:
+
+ - **backend**: the server side web application based on [Django][3] and [DRF][4]
+
+ - **frontend**: the client side web application based on [Angular](https://angular.io)
+
+ - **functional-tests**: the functional test suite based on [Selenium][6] and [pytest][7]
+
+[3]: https://www.djangoproject.com
+[4]: https://www.django-rest-framework.org
+[6]: https://www.selenium.dev/documentation/webdriver/
+[7]: https://docs.pytest.org/en/latest/
+
+Each subproject is configurable from the outside. Integration is achieved using "magic configuration" which is contained inside the root directory together with this README. In this way, the subprojects can stay truly isolated from each other.
+
+If you are reading this README, you'll likely be working with the integrated project as a whole rather than with one of the subprojects in isolation. In this case, this README should be your primary source of information on how to develop or deploy the project. However, we recommend that you also read the "How it works" section in the README of each subproject.
+
+
+## Development
+
+### Quickstart
+
+First time after cloning this project:
+
+```console
+$ python bootstrap.py
+```
+
+Running the application in [development mode][8] (hit ctrl-C to stop):
+
+```console
+$ yarn start
+```
+
+This will run the backend and frontend applications, as well as their unittests, and watch all source files for changes. You can visit the frontend on http://localhost:8000/, the browsable backend API on http://localhost:8000/api/ and the backend admin on http://localhost:8000/admin/. On every change, unittests rerun, frontend code rebuilds and open browser tabs refresh automatically (livereload).
+
+[8]: #development-mode-vs-production-mode
+
+
+### Recommended order of development
+
+For each new feature, we suggested that you work through the steps listed below. This could be called a back-to-front or "bottom up" order. Of course, you may have reasons to choose otherwise. For example, if very precise specifications are provided, you could move step 8 to the front for a more test-driven approach.
+
+Steps 1–5 also include updating the unittests. Only functions should be tested, especially critical and nontrivial ones.
+
+ 1. Backend model changes including migrations.
+ 2. Backend serializer changes and backend admin changes.
+ 3. Backend API endpoint changes.
+ 4. Frontend model changes.
+ 5. Other frontend unit changes (templates, views, routers, FSMs).
+ 6. Frontend integration (globals, event bindings).
+ 7. Run functional tests, repair broken functionality and broken tests.
+ 8. [Add functional tests][9] for the new feature.
+ 9. Update technical documentation.
+
+[9]: functional-tests/README.md#writing-tests
+
+For release branches, we suggest the following checklist.
+
+ 1. Bump the version number in the `package.json` next to this README.
+ 2. Run the functional tests in production mode, fix bugs if necessary.
+ 3. Try using the application in production mode, look for problems that may have escaped the tests.
+ 4. Add regression tests (unit or functional) that detect problems from step 3.
+ 5. Work on the code until new regression tests from step 4 pass.
+ 6. Optionally, repeat steps 2–5 with the application running in a real deployment setup (see [Deployment](#deployment)).
+
+
+### Commands for common tasks
+
+The `package.json` next to this README defines several shortcut commands to help streamline development. In total, there are over 30 commands. Most may be regarded as implementation details of other commands, although each command could be used directly. Below, we discuss the commands that are most likely to be useful to you. For full details, consult the `package.json`.
+
+Install the pinned versions of all package dependencies in all subprojects:
+
+```console
+$ yarn
+```
+
+Run backend and frontend in [production mode][8]:
+
+```console
+$ yarn start-p
+```
+
+Run the functional test suite:
+
+```console
+$ yarn test-func [FUNCTIONAL TEST OPTIONS]
+```
+
+The functional test suite by default assumes that you have the application running locally in production mode (i.e., on port `4200`). See [Configuring the browsers][10] and [Configuring the base address][11] in `functional-tests/README` for options.
+
+[10]: functional-tests/README.md#configuring-the-browsers
+[11]: functional-tests/README.md#configuring-the-base-address
+
+Run *all* tests (mostly useful for continuous integration):
+
+```console
+$ yarn test [FUNCTIONAL TEST OPTIONS]
+```
+
+Run an arbitrary command from within the root of a subproject:
+
+```console
+$ yarn back  [ARBITRARY BACKEND COMMAND HERE]
+$ yarn front [ARBITRARY FRONTEND COMMAND HERE]
+$ yarn func  [ARBITRARY FUNCTIONAL TESTS COMMAND HERE]
+```
+
+For example,
+
+```console
+$ yarn back less README.md
+```
+
+is equivalent to
+
+```console
+$ cd backend
+$ less README.md
+$ cd ..
+```
+
+Run `python manage.py` within the `backend` directory:
+
+```console
+$ yarn django [SUBCOMMAND] [OPTIONS]
+```
+
+`yarn django` is a shorthand for `yarn back python manage.py`. This command is useful for managing database migrations, among other things.
+
+Manage the frontend package dependencies:
+
+```console
+$ yarn fyarn (add|remove|upgrade|...) (PACKAGE ...) [OPTIONS]
+```
+
+
+
+### Notes on Python package dependencies
+
+Both the backend and the functional test suite are Python-based and package versions are pinned using [pip-tools][13] in both subprojects. For ease of development, you most likely want to use the same virtualenv for both and this is also what the `bootstrap.py` assumes.
+
+[13]: https://pypi.org/project/pip-tools/
+
+This comes with a small catch: the subprojects each have their own separate `requirements.txt`. If you run `pip-sync` in one subproject, the dependencies of the other will be uninstalled. In order to avoid this, you run `pip install -r requirements.txt` instead. The `yarn` command does this correctly by default.
+
+Another thing to be aware of, is that `pip-compile` takes the old contents of your `requirements.txt` into account when building the new version based on your `requirements.in`. You can use the following trick to keep the requirements in both projects aligned so the versions of common packages don't conflict:
+
+```console
+$ yarn back pip-compile
+# append contents of backend/requirements.txt to functional-tests/requirements.txt
+$ yarn func pip-compile
+```
+
+
+### Development mode vs production mode
+
+The purpose of development mode is to facilitate live development, as the name implies. The purpose of production mode is to simulate deployment conditions as closely as possible, in order to check whether everything still works under such conditions. A complete overview of the differences is given below.
+
+dimension  |  Development mode  |  Production mode
+-----------|--------------------|-----------------
+command  |  `yarn start`  |  `yarn start-p`
+base address  |  http://localhost:8000  |  http://localhost:4200
+backend server (Django)  |  in charge of everything  |  serves backend only
+frontend server (angular-cli)  |  serves  |  watch and build
+static files  |  served directly by Django's staticfiles app  |  collected by Django, served by gulp-connect
+backend `DEBUG` setting  |  `True`  |  `False`
+backend `ALLOWED_HOSTS`  |  -  |  restricted to `localhost`
+frontend sourcemaps  |  yes  |  no
+frontend optimization  |  no  |  yes
+
+
+## Deployment
+
+Both the backend and frontend applications have a section dedicated to deployment in their own READMEs. You should read these sections entirely before proceeding. All instructions in these sections still apply, though it is good to know that you can use the following shorthand commands from the integrated project root:
+
+```console
+
+# collect static files of both backend and frontend, with overridden settings
+$ yarn django collectstatic --settings SETTINGS --pythonpath path/to/SETTINGS.py
+```
+
+You should build the frontend before collecting all static files.