CI/CD improvements for gateway

.github/workflows/gwy-code-quality.yaml

@@ -0,0 +1,136 @@
+# Workflow to run pre-commit checks, django tests and template validations for the Gateway
+# GitHub Action Workflow validator: https://rhysd.github.io/actionlint/
+name: gateway-checks
+
+on:
+    workflow_dispatch:
+        # To manually trigger the workflow
+        # https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch
+    push:
+        paths:
+            # https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet
+            - gateway/**
+        branches:
+            - main
+            - master
+    pull_request:
+        paths:
+            # https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet
+            - gateway/**
+        branches:
+            - main
+            - master
+        types:
+            # https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request
+            - ready_for_review
+            - synchronize
+
+env:
+    DOCKER_BUILDKIT: 1
+    COMPOSE_DOCKER_CLI_BUILD: 1
+    PYTHON_VERSION: "3.13" # pre-commit and pyright don't seem to work well with 3.14 yet
+
+jobs:
+    # Run pre-commit checks on all files using the project's python version
+    gwy-pre-commit:
+        runs-on: ubuntu-latest
+        env:
+            UV_LINK_MODE: copy
+        steps:
+            - uses: actions/checkout@v4
+
+            # this ubuntu-latest version ships node 18, which was causing issues
+            - uses: actions/setup-node@v6
+              with:
+                  node-version: 24
+
+            - name: Install rust toolchain for the 'blake3' dependency
+              uses: actions-rust-lang/setup-rust-toolchain@v1
+
+            - name: Install uv
+              uses: astral-sh/setup-uv@v5
+              # https://github.com/marketplace/actions/astral-sh-setup-uv
+
+            - name: Install Python
+              working-directory: ./gateway
+              run: uv python install ${{ env.PYTHON_VERSION }}
+
+            - name: Install pre-commit
+              working-directory: ./gateway
+              run: uv tool install -p ${{ env.PYTHON_VERSION }} pre-commit
+
+            - name: Cache pre-commit hooks
+              id: cache-pre-commit
+              uses: actions/cache@v4
+              # https://github.com/actions/cache/blob/main/examples.md#python---pip
+              with:
+                  key: pre-commit-gateway-${{ hashFiles('gateway/.pre-commit-config.yaml') }}
+                  path: ~/.cache/pre-commit/
+
+            - name: Install hooks
+              working-directory: ./gateway
+              run: uv run -p ${{ env.PYTHON_VERSION }} pre-commit install --install-hooks
+
+            - name: Run pre-commit
+              working-directory: ./gateway
+              # make sure default_language_version in .pre-commit-config.yaml
+              # matches the one installed with uv, which is the most recent
+              # stable python version that meets project requirements.
+              run: uv run -p ${{ env.PYTHON_VERSION }} pre-commit run --all-files
+
+    # Run static analysis with pyright
+    # DISABLED due to many false-positives in Django code
+    # gwy-pyright:
+    #     env:
+    #         UV_LINK_MODE: copy
+    #     runs-on: ubuntu-latest
+    #     steps:
+    #         - uses: actions/checkout@v4
+
+    #         - name: Install uv
+    #           uses: astral-sh/setup-uv@v5
+
+    #         - name: Install system dependencies
+    #           run: |
+    #               sudo apt-get update
+    #               sudo apt-get install -y python3-dev libpq-dev
+
+    #         - name: Install packages
+    #           working-directory: ./gateway
+    #           run: uv sync -p ${{ env.PYTHON_VERSION }} --frozen --extra local
+
+    #         - uses: jakebailey/pyright-action@v2
+    #           # https://github.com/jakebailey/pyright-action#options
+    #           with:
+    #               pylance-version: latest-release
+    #               working-directory: ./gateway
+    #               python-path: ./.venv/bin/python
+
+    # Run Django tests
+    gwy-django-tests:
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                # uv will take care of installing other python versions,
+                # so we don't need a python-version matrix here.
+                # This is faster, saving some GH action minutes and dev time.
+                platform: [ubuntu-latest]
+        steps:
+            - uses: actions/checkout@v4
+
+            # - name: Install dependencies
+            #   run: sudo apt update && sudo apt install -y rsync
+
+            - name: Install just on ubuntu
+              if: matrix.platform == 'ubuntu-latest'
+              working-directory: ./gateway
+              run: |
+                  npm install -g rust-just
+
+            - name: Deploy action
+              run: ./scripts/deploy.sh ci
+              working-directory: ./gateway
+
+            - name: Run tests
+              run: just test
+              working-directory: ./gateway

.pre-commit-config.yaml

@@ -45,7 +45,7 @@ repos:
 
     # runs the ruff linter and formatter
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.14.10
+      rev: v0.14.11
       hooks:
           # linter
           - id: ruff-check # runs ruff check --force-exclude

gateway/README.md

@@ -43,20 +43,89 @@ After cloning this repo, follow the steps below:
 
 # for ci:
 ./scripts/deploy.sh ci
+# to force a CI environment, set the environment variable:
+#   export CI=1
+#   just env
 
 # for production:
 ./scripts/deploy.sh production
+# to force a production environment, list the current machine's hostname as production:
+#   cp ./scripts/prod-hostnames.env.example ./scripts/prod-hostnames.env
+#   hostname >> ./scripts/prod-hostnames.env
+#   just env
 ```
 
-Then follow the steps that are [not automated for a first-time setup](./docs/detailed-deploy.md#first-deployment-not-automated).
+> [!IMPORTANT]
+>
+> This deploy script does several tasks, and it's generally safe to run it multiple
+> times. Nonetheless, a production deployment is expected to require manual
+> configuration of items like:
+>
+> + Storage backend to match your hardware and your use case;
+> + Network configuration (reverse proxy, TLS certs, subdomains, etc);
+> + Allowed hosts, email server, and other settings in `django.env`.
+>
+> So, for a production deployment, make sure to check the [detailed deployment
+> instructions](./docs/detailed-deploy.md#production-deploy) after running the script.
 
 This _should_ leave you with the application running using default configurations. If
 that doesn't happen, feel free to open an issue or reach out for help.
 
+1. Access the web interface:
+
+    Open the web interface at [localhost:8000](http://localhost:8000) (`localhost:18000`
+    in production). You can create regular users by signing up there, or:
+
+    You can sign in with the superuser credentials at
+    [localhost:8000/admin](http://localhost:8000/admin) (or
+    `localhost:18000/<admin-path-set-in-django.env>` in production) to access the admin
+    interface.
+
+    > [!TIP]
+    > The superuser credentials are the ones provided in a step above, or during an
+    > interactive execution of the `deploy.sh` script.
+    > If the credentials were lost, you can reset the password with:
+    >
+    > ```bash
+    > just uv run manage.py changepassword <email>
+    > ```
+    >
+    > Or create one:
+    >
+    > ```bash
+    > just uv run manage.py createsuperuser
+    > ```
+
+2. Run the test suite:
+
+    ```bash
+    # run all gateway tests available for the current environment:
+    just test
+    ```
+
+Alternatively, follow the steps that are [not automated for a first-time
+setup](./docs/detailed-deploy.md#first-deployment-not-automated).
+
 ## Just recipes
 
-We are using [Just](https://github.com/casey/just#installation/) as a command runner to
-simplify common tasks. Here's a quick lookup of available commands:
+Next, you might be interested in other available `just` recipes.
+
+```bash
+# print the currently selected environment:
+just env
+
+# stream logs until interrupted, or without following it:
+just logs
+just logs-once
+
+# rebuilds and restarts services, showing logs (press Ctrl+C to exit logs):
+just redeploy
+
+# stop all gateway services:
+just down
+```
+
+Get the full list with:
 
 ```bash
 just --list