Donate is implemented using Django, version 4.2.13 at the time of
writing (2024-08-22). A relatively small number of dependencies are
documented in the [pyproject.toml](https://gitlab.torproject.org/tpo/web/donate-neo/-/blob/465041dfd92e0ec09613c897f32e54a76f7e4f80/pyproject.toml#L8-21) file and the [latest
poetry.lock](https://gitlab.torproject.org/tpo/web/donate-neo/-/blob/main/poetry.lock?ref_type=heads) file contains actual versions currently deployed.
Poetry is used to manage dependencies and builds. The frontend CSS /
JS code is managed with NVM. The [README file](https://gitlab.torproject.org/tpo/web/donate-neo/-/tree/main?ref_type=heads) has more information
about the development setup.
## Related services
## Related services
<!-- dependent services (e.g. authenticates against LDAP, or requires -->
See mainly the [CiviCRM server](service/crm).
<!-- git pushes) -->
## Issues
## Issues
There is no issue tracker specifically for this the donate-review runner.
[File][] or [search][] for issues in the donate-neo repository.
[File][] or [search][] for issues in the donate-neo repository.
<!-- who the upstreams are, if they are still active, -->
Django should probably be considered the upstream here. [According to
<!-- collaborative, how do we keep up to date, support channels, see -->
Wikipedia](https://en.wikipedia.org/wiki/Django_(web_framework)), "is a free and open-source, Python-based web framework
<!-- also the "Issues" section above -->
that runs on a web server. It follows the model–template–views (MTV)
architectural pattern. It is maintained by the Django Software
Foundation (DSF), an independent organization established in the US as
a 501(c)(3) non-profit. Some well-known sites that use Django include
Instagram, Mozilla, Disqus, Bitbucket, Nextdoor and Clubhouse."
LTS releases are supported for "typically 3 years", see [their release
process](https://docs.djangoproject.com/en/5.1/internals/release-process/) for more background.
Support mostly happens over the [communnity section](https://www.djangoproject.com/community/) of the main
website, and through Discord, a forum, and GitHub issues.
## Monitoring and metrics
## Monitoring and metrics
...
@@ -157,45 +246,55 @@ Anyone contributing to [tpo/web/donate-neo][].
...
@@ -157,45 +246,55 @@ Anyone contributing to [tpo/web/donate-neo][].
<!-- how the service can be tested, for example after major changes -->
<!-- how the service can be tested, for example after major changes -->
<!-- like IP address changes or upgrades. describe CI, test suites, linting -->
<!-- like IP address changes or upgrades. describe CI, test suites, linting -->
TODO: how do we run the test suite or test that things are still working after an upgrade? (@stephen) also cross-ref with @mattlav's checklist
## Logs
## Logs
The review app logs may be accessed using the `podman logs <container>` command
The logs may be accessed using the `podman logs <container>` command,
as the `gitlab-runner` user.
as the `gitlab-runner` user for review apps.
## Backups
## Backups
This service has no special backup needs. All the donate-neo instances are
This service has no special backup needs. In particular, all of the
ephemeral, and a new system can be bootstrapped solely from puppet.
donate-review instances are ephemeral, and a new system can be
bootstrapped solely from puppet.
## Other documentation
## Other documentation
<!-- references to upstream documentation, if relevant -->
*[Django documentation](https://docs.djangoproject.com/), [direct link to 4.1](https://docs.djangoproject.com/en/4.1/)
*[CiviCRM internal docs](service/crm)
# Discussion
# Discussion
<!-- the "discussion" section is where you put any longer conversation -->
<!-- about the project that you will not need in a casual -->
<!-- review. history of the project, why it was done the way it was -->
<!-- (as opposed to how), alternatives, and other proposals are -->
<!-- relevant here. -->
<!-- this at least partly overlaps with the TPA-RFC process (see -->
<!-- policy.md), but in general should defer to proposals when -->
<!-- available -->
## Overview
## Overview
donate-review was created as part of tpo/web/donate-neo#6,
donate-review was created as part of [tpo/web/donate-neo#6,](https://gitlab.torproject.org/tpo/web/donate-neo/-/issues/6,)
tpo/tpa/team#41108 and refactored as part of tpo/web/donate-neo#21.
[tpo/tpa/team#41108](https://gitlab.torproject.org/tpo/tpa/team/-/issues/41108) and refactored as part of [tpo/web/donate-neo#21.](https://gitlab.torproject.org/tpo/web/donate-neo/-/issues/21.)
Donate-review's purpose is to provide a review app deploy target for
Donate-review's purpose is to provide a review app deploy target for
tpo/web/donate-neo. Most of the other tpo/web sites are static lektor sites,
[donate-neo][]. Most of the other tpo/web sites are static lektor
and can be easily deployed to a review app target as simple static sites
sites, and can be easily deployed to a review app target as simple
fronted by Apache. But because donate-neo is a django application, it needs a
static sites fronted by Apache. But because donate-neo is a Django
specially-created deploy target for review apps.
application, it needs a specially-created deploy target for review
apps.
## Security and risk assessment
## Security and risk assessment
### django
Django has a relatively good security record and a good security
team. Our challenge will be mainly to keep it up to date.
### production site
The production server is separate from the review apps to isolate it
from the GitLab attack surface. It was felt that doing full
"continuous deployment" was dangerous, and we require manual
deployments and reviews before GitLab-generated code can be deployed
in that sensitive environment.
### donate-review
donate-review is a shell executor, which means each CI job is executed with no
donate-review is a shell executor, which means each CI job is executed with no
real sandboxing or containerization. There was an attempt to set up the runner
real sandboxing or containerization. There was an attempt to set up the runner
using systemd-nspawn, but it was taking too long and we
using systemd-nspawn, but it was taking too long and we
...
@@ -211,14 +310,30 @@ ensure no untrusted party is allowed to gain this privilege.
...
@@ -211,14 +310,30 @@ ensure no untrusted party is allowed to gain this privilege.
## Technical debt and next steps
## Technical debt and next steps
### Dependencies chase
The `renovate-cron` project should be used on the donate-neo codebase
to ensure timely upgrades to the staging and production
deployments. See [tpo/web/donate-neo#46](https://gitlab.torproject.org/tpo/web/donate-neo/-/issues/46). The [upgrades](#upgrades) section
should be fixed when that is done.
### Django upgrades
We are running Django 4, released in April 2023, an LTS release
supported until April 2026. The upgrade to Django 5 will carefully
require reviewing release notes for deprecations and removals, see
[how to upgrade](https://docs.djangoproject.com/en/5.1/howto/upgrade-version/) for details.
### donate-review
The next step here is to make the donate-review service fully generic to allow
The next step here is to make the donate-review service fully generic to allow
other web projects with special runtime requirements to deploy review apps in
other web projects with special runtime requirements to deploy review apps in
the same manner.
the same manner.
## Proposed Solution
## Proposed Solution
<!-- Link to RFC -->
No formal proposal was established to build this service.
## Other alternatives
## Other alternatives
<!-- include benchmarks and procedure if relevant -->
None discussed so far, but see [tpo/web/donate-neo#20](https://gitlab.torproject.org/tpo/web/donate-neo/-/issues/20).
