|
|
Lektor Debian Package lives on the Debian gitlab repository: https://salsa.debian.org/debian/lektor
|
|
|
[Lektor][] is a static website generator written in Python, we use it to
|
|
|
generate most of the websites of the Tor Project.
|
|
|
|
|
|
The package is maintained and updated when a new Lektor version comes up.
|
|
|
[Lektor]: https://github.com/lektor/lektor
|
|
|
|
|
|
Lektor needs a small dependency that is also packaged for Debian and lives at: https://salsa.debian.org/debian/python-inifile/
|
|
|
[[_TOC_]]
|
|
|
|
|
|
This is a small python library to handle INI files. |
|
|
# Tutorial
|
|
|
|
|
|
## Build a Lektor project on your machine
|
|
|
|
|
|
See [this page](https://gitlab.torproject.org/tpo/web/wiki/-/wikis/Compiling-a-local-version-of-the-website)
|
|
|
on the Web team wiki.
|
|
|
|
|
|
## Build a basic Lektor website in GitLab CI
|
|
|
|
|
|
To enable automatic builds of a Lektor project in GitLab CI, add this snippet
|
|
|
in `.gitlab.ci-yml`, at the root of the project:
|
|
|
|
|
|
include:
|
|
|
- project: tpo/tpa/ci-templates
|
|
|
file:
|
|
|
- lektor.yml
|
|
|
- pages-deploy.yml
|
|
|
|
|
|
The jobs defined in `lektor.yml` will spawn a container to build the site, and
|
|
|
`pages-deploy.yml` will deploy the build artifacts to GitLab Pages.
|
|
|
|
|
|
See [howto/gitlab](howto/gitlab#publishing-gitlab-pages) for more details on
|
|
|
publishing to GitLab Pages.
|
|
|
|
|
|
# How-to
|
|
|
|
|
|
## Submit a website contribution
|
|
|
|
|
|
### As an occasional contributor
|
|
|
|
|
|
The first step is to [get a GitLab account](howto/gitlab#how-to-get-an-account).
|
|
|
|
|
|
This will allow you to fork the Lektor project in your personal GitLab
|
|
|
namespace, where you can push commits with your changes.
|
|
|
|
|
|
As you do this, GitLab CI will continuously build a copy of the website with
|
|
|
your changes and publish it to GitLab Pages. The location where these Pages are
|
|
|
hosted can be displayed by navigation to the project Settings > Pages.
|
|
|
|
|
|
When you are satisfied, you can submit a Merge Request and one of the website
|
|
|
maintainers will evaluate the proposed changes.
|
|
|
|
|
|
### As a regular contributor
|
|
|
|
|
|
As someone who expects to submit contributions on a regular basis to one of the
|
|
|
Tor Project websites, the first step is to request access. This can be done by
|
|
|
joining the `#tor-www` channel on IRC and asking!
|
|
|
|
|
|
The access level granted for website content contributors is normally
|
|
|
*Developper*. This role grants the ability to push new branches to the GitLab
|
|
|
project and submit Merge Requests to the default `main` branch.
|
|
|
|
|
|
When a Merge Request is created, a CI pipeline status widget will appear under
|
|
|
the description, above the discussion threads. If GitLab CI succeeds building
|
|
|
the branch, it will publish the build artifacts and display a **View app**
|
|
|
button. Clicking the button will navigate to the build result hosted on
|
|
|
`review.torproject.net`.
|
|
|
|
|
|
Once the branch is deleted, after the Merge Request is accepted, for example,
|
|
|
the build artifacts are automatically unpublished.
|
|
|
|
|
|
## Pager playbook
|
|
|
|
|
|
<!-- information about common errors from the monitoring system and -->
|
|
|
<!-- how to deal with them. this should be easy to follow: think of -->
|
|
|
<!-- your future self, in a stressful situation, tired and hungry. -->
|
|
|
|
|
|
## Disaster recovery
|
|
|
|
|
|
<!-- what to do if all goes to hell. e.g. restore from backups? -->
|
|
|
<!-- rebuild from scratch? not necessarily those procedures (e.g. see -->
|
|
|
<!-- "Installation" below but some pointers. -->
|
|
|
|
|
|
# Reference
|
|
|
|
|
|
## Installation
|
|
|
|
|
|
<!-- how to setup the service from scratch -->
|
|
|
|
|
|
## SLA
|
|
|
|
|
|
<!-- this describes an acceptable level of service for this service -->
|
|
|
|
|
|
## Design
|
|
|
|
|
|
### GitLab CI builds
|
|
|
|
|
|
### Deployments
|
|
|
|
|
|
### Review apps
|
|
|
|
|
|
## Issues
|
|
|
|
|
|
<!-- such projects are never over. add a pointer to well-known issues -->
|
|
|
<!-- and show how to report problems. usually a link to the bugtracker -->
|
|
|
|
|
|
There is no issue tracker specifically for this project, [File][] or
|
|
|
[search][] for issues in the [team issue tracker][search].
|
|
|
|
|
|
[File]: https://gitlab.torproject.org/tpo/tpa/team/-/issues/new
|
|
|
[search]: https://gitlab.torproject.org/tpo/tpa/team/-/issues
|
|
|
|
|
|
## Maintainer, users, and upstream
|
|
|
|
|
|
<!-- document who deployed and operates this service, who the users -->
|
|
|
<!-- are, who the upstreams are, if they are still active, -->
|
|
|
<!-- collaborative, how do we keep up to date, -->
|
|
|
|
|
|
## Monitoring and testing
|
|
|
|
|
|
<!-- describe how this service is monitored and how it can be tested -->
|
|
|
<!-- after major changes like IP address changes or upgrades. describe -->
|
|
|
<!-- CI, test suites, linting, how security issues and upgrades are -->
|
|
|
<!-- tracked -->
|
|
|
|
|
|
## Logs and metrics
|
|
|
|
|
|
<!-- where are the logs? how long are they kept? any PII? -->
|
|
|
<!-- what about performance metrics? same questions -->
|
|
|
|
|
|
## Backups
|
|
|
|
|
|
<!-- does this service need anything special in terms of backups? -->
|
|
|
<!-- e.g. locking a database? special recovery procedures? -->
|
|
|
|
|
|
## Other documentation
|
|
|
|
|
|
<!-- references to upstream documentation, if relevant -->
|
|
|
|
|
|
# Discussion
|
|
|
|
|
|
## Overview
|
|
|
|
|
|
<!-- describe the overall project. should include a link to a ticket -->
|
|
|
<!-- that has a launch checklist -->
|
|
|
|
|
|
<!-- if this is an old project being documented, summarize the known -->
|
|
|
<!-- issues with the project. to quote the "audit procedure":
|
|
|
|
|
|
5. When was the last security review done on the project? What was
|
|
|
the outcome? Are there any security issues currently? Should it
|
|
|
have another security review?
|
|
|
|
|
|
6. When was the last risk assessment done? Something that would cover
|
|
|
risks from the data stored, the access required, etc.
|
|
|
|
|
|
7. Are there any in-progress projects? Technical debt cleanup?
|
|
|
Migrations? What state are they in? What's the urgency? What's the
|
|
|
next steps?
|
|
|
|
|
|
8. What urgent things need to be done on this project?
|
|
|
|
|
|
-->
|
|
|
|
|
|
## Goals
|
|
|
|
|
|
<!-- include bugs to be fixed -->
|
|
|
|
|
|
### Must have
|
|
|
|
|
|
### Nice to have
|
|
|
|
|
|
### Non-Goals
|
|
|
|
|
|
## Approvals required
|
|
|
|
|
|
<!-- for example, legal, "vegas", accounting, current maintainer -->
|
|
|
|
|
|
## Proposed Solution
|
|
|
|
|
|
## Cost
|
|
|
|
|
|
## Alternatives considered
|
|
|
|
|
|
<!-- include benchmarks and procedure if relevant --> |