This is an automated email from the ASF dual-hosted git repository.
akm pushed a commit to branch clarify-instructions-557
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git
The following commit(s) were added to refs/heads/clarify-instructions-557 by
this push:
new 698f699 Fixes #557
698f699 is described below
commit 698f6992ff255ef03753bbf3440a2a81a0ec1637
Author: Andrew K. Musselman <[email protected]>
AuthorDate: Tue Jan 20 12:30:20 2026 -0800
Fixes #557
---
BUILD.md | 247 +++++++++++++++++++++++++++++++++++++++++
CONTRIBUTING.md | 153 +++++++++++++++++++++++++
DEVELOPMENT.md | 217 ++++++++++++++++++++++++++++++++++++
GOVERNANCE.md | 46 ++++++++
README.md | 58 ++++++++--
SUPPORT.md | 55 +++++++++
atr/docs/how-to-contribute.md | 116 ++++++++-----------
atr/docs/running-the-server.md | 120 ++++++++++----------
8 files changed, 871 insertions(+), 141 deletions(-)
diff --git a/BUILD.md b/BUILD.md
new file mode 100644
index 0000000..b6c237e
--- /dev/null
+++ b/BUILD.md
@@ -0,0 +1,247 @@
+# Build Guide
+
+This guide covers building ATR and its components. For development setup, see
[DEVELOPMENT.md](DEVELOPMENT.md).
+
+## Prerequisites
+
+- **Docker or Podman** - For container builds
+- **uv** - Python package manager
+- **make** - POSIX-compliant make utility
+- **cmark** - CommonMark processor (for documentation)
+- **Python 3.13** - Required runtime
+
+Install on Alpine Linux:
+```shell
+apk add cmark curl git make mkcert@testing
+curl -LsSf https://astral.sh/uv/install.sh | env
UV_INSTALL_DIR="/usr/local/bin" sh
+uv python install 3.13
+```
+
+Install on macOS (Homebrew):
+```shell
+brew install cmark mkcert
+curl -LsSf https://astral.sh/uv/install.sh | sh
+rehash
+uv python install 3.13
+```
+
+## Container Build
+
+### Build the Alpine Container
+
+```shell
+make build-alpine
+# or simply
+make build
+```
+
+This runs `scripts/build` to create the `tooling-trusted-release` container
image using `Dockerfile.alpine`.
+
+### Run the Container
+
+```shell
+make certs-local # Generate certificates first
+make run-alpine
+```
+
+### Docker Compose
+
+For development with auto-reload:
+
+```shell
+mkdir -p state
+docker compose up --build
+```
+
+The compose configuration:
+- Mounts `atr/` for live code changes
+- Enables test mode (`ALLOW_TESTS=1`)
+- Exposes port 8080
+
+## Documentation Build
+
+### Build All Documentation
+
+```shell
+make docs
+```
+
+This command:
+1. Validates the table of contents structure
+2. Generates navigation links between pages
+3. Converts Markdown to HTML using cmark
+4. Post-processes HTML files
+
+### Build Without Validation
+
+```shell
+make build-docs
+```
+
+### How Documentation Build Works
+
+The documentation system uses `scripts/docs_build.py` to automatically
generate navigation from the table of contents in `atr/docs/index.md`. When you
reorganize documentation, just edit the table of contents and run `make docs`
to update all navigation links.
+
+For details, see [Build
Processes](https://release-test.apache.org/docs/build-processes).
+
+## Python Dependencies
+
+### Install All Dependencies
+
+```shell
+uv sync --frozen --all-groups
+```
+
+### Install Production Dependencies Only
+
+```shell
+uv sync --frozen --no-dev
+```
+
+### Update Dependencies
+
+```shell
+make update-deps
+```
+
+This updates `uv.lock` and runs `pre-commit autoupdate`.
+
+## TLS Certificates
+
+### For Local Development (mkcert)
+
+```shell
+make certs-local
+```
+
+Creates certificates in `state/hypercorn/secrets/` using mkcert.
+
+### Self-Signed Certificates
+
+```shell
+make certs
+```
+
+Generates self-signed certificates using `scripts/generate-certificates`.
+
+## Frontend Assets
+
+### Build Bootstrap
+
+```shell
+make build-bootstrap
+```
+
+### Bump Bootstrap Version
+
+```shell
+make bump-bootstrap BOOTSTRAP_VERSION=5.3.4
+```
+
+### Build TypeScript
+
+```shell
+make build-ts
+```
+
+## Test Builds
+
+### Build Playwright Container
+
+```shell
+make build-playwright
+```
+
+### Run Playwright Tests
+
+```shell
+make run-playwright # Fast tests
+make run-playwright-slow # All tests with cleanup
+```
+
+Or use Docker Compose:
+
+```shell
+sh tests/run-playwright.sh
+```
+
+### Run End-to-End Tests
+
+```shell
+sh tests/run-e2e.sh
+```
+
+## Make Targets Reference
+
+### Build Targets
+
+| Target | Description |
+|--------|-------------|
+| `build` | Alias for `build-alpine` |
+| `build-alpine` | Build the Alpine-based container |
+| `build-bootstrap` | Build Bootstrap assets |
+| `build-docs` | Build documentation without validation |
+| `build-playwright` | Build Playwright test container |
+| `build-ts` | Compile TypeScript |
+
+### Run Targets
+
+| Target | Description |
+|--------|-------------|
+| `serve` | Run server with standard config |
+| `serve-local` | Run server with debug and test mode |
+| `run-alpine` | Run the Alpine container |
+| `run-playwright` | Run Playwright tests (fast) |
+| `run-playwright-slow` | Run Playwright tests (full) |
+
+### Dependency Targets
+
+| Target | Description |
+|--------|-------------|
+| `sync` | Install production dependencies |
+| `sync-all` | Install all dependencies including dev |
+| `update-deps` | Update and lock dependencies |
+
+### Code Quality Targets
+
+| Target | Description |
+|--------|-------------|
+| `check` | Run all pre-commit checks |
+| `check-light` | Run lightweight checks |
+| `check-heavy` | Run comprehensive checks |
+| `check-extra` | Run interface ordering checks |
+
+### Utility Targets
+
+| Target | Description |
+|--------|-------------|
+| `certs` | Generate self-signed certificates |
+| `certs-local` | Generate mkcert certificates |
+| `docs` | Build and validate documentation |
+| `generate-version` | Generate version.py |
+| `commit` | Add, commit, pull, push workflow |
+| `ipython` | Start IPython shell with project |
+
+## Configuration Variables
+
+The Makefile supports these variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BIND` | `127.0.0.1:8080` | Server bind address |
+| `IMAGE` | `tooling-trusted-release` | Container image name |
+| `STATE_DIR` | `state` | State directory path |
+
+Example:
+```shell
+make serve-local BIND=0.0.0.0:8080
+```
+
+## CI/CD
+
+The GitHub Actions workflow (`.github/workflows/build.yml`) runs:
+1. Pre-commit checks
+2. Playwright browser tests
+3. Container build verification
+
+See the workflow file for details on the CI environment.
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..1231172
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,153 @@
+# Contributing to ATR
+
+Thank you for your interest in contributing to Apache Trusted Releases (ATR)!
This guide will help you get started.
+
+For detailed ASF policies, commit message guidelines, and security
considerations, see the [contribution policies
guide](https://release-test.apache.org/docs/how-to-contribute).
+
+## Before You Start
+
+> **IMPORTANT:** New contributors must introduce themselves on the
[development mailing list](mailto:[email protected]) first, to deter
spam. Please do not submit a PR until you have introduced yourself, otherwise
it will likely be rejected.
+
+**Subscribe to the mailing list:** Send an email with empty subject and body
to [[email protected]](mailto:[email protected])
and reply to the automated response.
+
+## Finding Something to Work On
+
+- Browse the [issue
tracker](https://github.com/apache/tooling-trusted-releases/issues) for open
issues
+- For new features or bugs, [create an
issue](https://github.com/apache/tooling-trusted-releases/issues/new) to
discuss before starting work
+
+## Development Setup
+
+1. **Fork and clone** the repository:
+ ```shell
+ git clone https://github.com/YOUR_USERNAME/tooling-trusted-releases.git
+ cd tooling-trusted-releases
+ ```
+
+2. **Install dependencies** (includes pre-commit, dev tools, and test
dependencies):
+ ```shell
+ # Install uv if you don't have it
+ curl -LsSf https://astral.sh/uv/install.sh | sh
+
+ # Install all dependencies
+ uv sync --frozen --all-groups
+ ```
+
+3. **Set up pre-commit hooks:**
+ ```shell
+ uv run pre-commit install
+ ```
+
+4. **Run the server:** See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed
instructions.
+
+## Pull Request Workflow
+
+1. **Create a branch** with a descriptive name:
+ ```shell
+ git checkout -b fix-typo-in-docs
+ ```
+
+2. **Make your changes** following our [code
conventions](https://release-test.apache.org/docs/code-conventions)
+
+3. **Run checks** before committing:
+ ```shell
+ make check
+ ```
+
+4. **Commit** with a clear message (see [commit style](#commit-message-style)
below)
+
+5. **Push** your branch:
+ ```shell
+ git push origin your-branch-name
+ ```
+
+6. **Open a pull request** to the `main` branch
+ - Explain what your changes do and why
+ - Reference any related issues (e.g., "Fixes #123")
+ - Mark as draft until ready for review
+ - **Enable "Allow maintainer edits"** (strongly recommended)
+
+7. **Participate in review** - we may request changes
+
+## Commit Message Style
+
+Use clear, concise commit messages:
+
+**Format:**
+- First line: imperative mood, sentence case, 50-72 characters
+- No period at the end
+- Use articles ("Fix a bug" not "Fix bug")
+
+**Good examples:**
+```
+Add distribution platform validation to the compose phase
+Fix a bug with sorting version numbers containing release candidates
+Update dependencies
+```
+
+**Poor examples:**
+```
+fixed stuff
+Updated the code.
+refactoring vote resolution logic
+```
+
+For complex changes, add a body separated by a blank line explaining what and
why (not how).
+
+## Code Standards Summary
+
+- **Python:** Follow PEP 8, use double quotes, no `# noqa` or `# type: ignore`
+- **HTML:** Use Bootstrap classes, avoid custom CSS
+- **JavaScript:** Minimize usage, follow best practices for dependencies
+- **Shell:** POSIX sh only, no bash-specific features
+
+See the [full code
conventions](https://release-test.apache.org/docs/code-conventions) for
complete guidelines.
+
+## Running Tests
+
+```shell
+# Browser tests (requires Docker)
+sh tests/run-playwright.sh
+
+# End-to-end tests
+sh tests/run-e2e.sh
+
+# Quick pre-commit checks
+make check-light
+```
+
+## ASF Requirements
+
+### Contributor License Agreement
+
+Before your first contribution, sign the [Apache
ICLA](https://www.apache.org/licenses/contributor-agreements.html#clas). This
is a one-time requirement.
+
+If your employer holds rights to your work, a
[CCLA](https://www.apache.org/licenses/contributor-agreements.html#clas) may
also be needed.
+
+### Licensing
+
+All contributions are licensed under [Apache License
2.0](https://www.apache.org/licenses/LICENSE-2.0). Third-party dependencies
must be compatible ([Category A
licenses](https://www.apache.org/legal/resolved.html#category-a)).
+
+### Code of Conduct
+
+Follow the [ASF Code of
Conduct](https://www.apache.org/foundation/policies/conduct.html).
+
+## Security Considerations
+
+ATR's primary goal is to prevent supply chain attacks. When contributing:
+
+- Follow secure coding practices
+- Validate all inputs and sanitize outputs
+- Use established libraries for cryptographic operations
+- Consider security implications of your changes
+- Report security issues via the [ASF security
process](https://www.apache.org/security/) (not public issues)
+
+## Getting Help
+
+- **Mailing list:**
[[email protected]](https://lists.apache.org/[email protected])
+- **Slack:**
[#apache-trusted-releases](https://the-asf.slack.com/archives/C049WADAAQG) on
ASF Slack
+- **Issue tracker:** Comment on relevant issues or PRs
+- **Documentation:** [Developer
Guide](https://release-test.apache.org/docs/developer-guide)
+
+## Alternative: Email Patches
+
+If you prefer not to use GitHub, you can [email
patches](https://lists.apache.org/[email protected]) using
standard Git patch formatting.
\ No newline at end of file
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..ddcaa4d
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,217 @@
+# Development Guide
+
+This guide will help you get started with developing ATR. For detailed
technical documentation, see the [Developer
Guide](https://release-test.apache.org/docs/developer-guide).
+
+## Prerequisites
+
+ATR can be developed on **Linux** or **macOS**. Windows and other platforms
are not supported.
+
+**Required (install manually):**
+
+- **Git** - For cloning the repository
+- **Python 3.13** - The runtime for ATR (can be installed via uv)
+- **uv** - Python package manager ([installation
guide](https://docs.astral.sh/uv/#installation))
+- **Docker or Podman** - For containerized development (recommended)
+- **mkcert** - For local TLS certificates (if running directly)
+- **make** - POSIX-compliant make utility
+- **biome** - For JavaScript/TypeScript linting ([installation
guide](https://biomejs.dev/guides/manual-installation/))
+- **cmark** - CommonMark processor (optional, for rebuilding documentation)
+
+**Installed via `uv sync`:** pre-commit, ruff, pyright, playwright, and other
dev/test tools (see `pyproject.toml`).
+
+### Platform-Specific Installation
+
+**Alpine Linux:**
+
+```shell
+apk add cmark curl git make mkcert@testing
+curl -LsSf https://astral.sh/uv/install.sh | env
UV_INSTALL_DIR="/usr/local/bin" sh
+uv python install 3.13
+```
+
+**macOS (Homebrew):**
+
+```shell
+brew install cmark mkcert
+curl -LsSf https://astral.sh/uv/install.sh | sh
+rehash
+uv python install 3.13
+```
+
+## Quick Start
+
+There are two ways to run the server: in a container (recommended) or
directly. **Do not use both methods simultaneously** - they share the same
state directory and will conflict.
+
+### Option 1: Docker Compose (Recommended)
+
+The easiest way to run ATR with all dependencies (CycloneDX, syft, Apache RAT
for SBOM generation and license checking):
+
+```shell
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/tooling-trusted-releases.git
+cd tooling-trusted-releases
+
+# Create state directory and start
+mkdir -p state
+docker compose up --build
+```
+
+The first build takes several minutes. Subsequent runs are faster due to
caching.
+
+Visit [`https://127.0.0.1:8080/`](https://127.0.0.1:8080/) and accept the
self-signed certificate.
+
+The container:
+- Runs in test mode (`ALLOW_TESTS=1`) with mock authentication
+- Mounts `atr/` for live code changes without rebuilding
+- Auto-reloads when files change
+
+**Optional LDAP credentials** (for rsync writes and certain tasks):
+
+```shell
+LDAP_BIND_DN=dn LDAP_BIND_PASSWORD=pass docker compose up --build
+```
+
+**Useful container commands:**
+
+```shell
+docker compose exec atr bash # Shell in running container
+docker compose run --rm atr bash # Start container with shell (not ATR)
+docker compose down # Stop the server
+```
+
+### Option 2: Running Directly
+
+For faster iteration without containers:
+
+```shell
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/tooling-trusted-releases.git
+cd tooling-trusted-releases
+
+# Install Python dependencies
+uv sync --frozen --all-groups
+
+# Create state directory and certificates
+mkdir -p state
+make certs-local
+
+# Start the server
+make serve-local
+```
+
+**Accessing the site:**
+
+We recommend using `localhost.apache.org`, which requires adding to
`/etc/hosts`:
+
+```
+127.0.0.1 localhost.apache.org
+```
+
+Then visit:
[`https://localhost.apache.org:8080/`](https://localhost.apache.org:8080/)
+
+Alternatively, use [`https://127.0.0.1:8080/`](https://127.0.0.1:8080/)
without modifying hosts.
+
+> **Note:** Pick one host and stick with it - logging in on one host doesn't
log you in on another.
+
+**Why TLS is required:** ATR uses the actual ASF OAuth server for login, even
in development. This keeps development behavior aligned with production.
+
+**Initial startup:** It takes 1-2 minutes to fetch committee and project
information from the ASF website. Until complete, no existing
committees/projects will appear.
+
+## Development Workflow
+
+1. **Set up pre-commit hooks:**
+ ```shell
+ uv run pre-commit install
+ ```
+
+2. **Run code checks:**
+ ```shell
+ make check # Full checks
+ make check-light # Quick checks
+ ```
+
+3. **Run tests:**
+ ```shell
+ sh tests/run-playwright.sh # Browser tests with Docker Compose
+ sh tests/run-e2e.sh # End-to-end tests
+ ```
+
+4. **Build documentation:**
+ ```shell
+ make docs
+ ```
+
+## Key Make Targets
+
+| Target | Description |
+|--------|-------------|
+| `make serve-local` | Run server locally with debug mode |
+| `make check` | Run all pre-commit checks |
+| `make check-light` | Run quick pre-commit checks |
+| `make docs` | Build documentation |
+| `make build-alpine` | Build the Alpine container |
+| `make run-playwright` | Run browser tests |
+
+See [BUILD.md](BUILD.md) for the complete list of build targets.
+
+## Project Structure
+
+```
+tooling-trusted-releases/
+├── atr/ # Main application source code
+│ ├── api/ # API endpoints
+│ ├── db/ # Database interfaces
+│ ├── docs/ # Documentation (Markdown)
+│ ├── get/ # GET route handlers
+│ ├── models/ # Data models (SQLModel/Pydantic)
+│ ├── post/ # POST route handlers
+│ ├── shared/ # Shared route handler code
+│ ├── storage/ # Storage interface
+│ ├── tasks/ # Background task definitions
+│ └── templates/ # Jinja2 templates
+├── playwright/ # Browser test scripts
+├── scripts/ # Build and utility scripts
+├── state/ # Runtime state (created at runtime)
+└── tests/ # Test configuration and e2e tests
+```
+
+## Useful Resources
+
+- **[Overview of the
Code](https://release-test.apache.org/docs/overview-of-the-code)** - High-level
architecture
+- **[Running and Creating
Tests](https://release-test.apache.org/docs/running-and-creating-tests)** -
Testing guide
+- **[Code
Conventions](https://release-test.apache.org/docs/code-conventions)** - Style
guidelines
+- **[Contributing](CONTRIBUTING.md)** - How to contribute code
+- **[Build Guide](BUILD.md)** - Complete build targets reference
+
+## Troubleshooting
+
+### Certificate Issues
+
+If you encounter TLS certificate problems when running directly:
+
+1. Ensure `mkcert` is installed and run `make certs-local`
+2. You may need to run `mkcert -install` to trust the local CA
+3. See the [mkcert documentation](https://github.com/FiloSottile/mkcert) for
platform-specific guidance
+
+> **Security note:** `mkcert -install` creates a CA valid for 10 years for
your system, Java, and Firefox. If the private key (`rootCA-key.pem` in the
directory shown by `mkcert -CAROOT`) is ever leaked, anyone could create
certificates trusted by your system. See the [mkcert
caveats](https://github.com/FiloSottile/mkcert#installation).
+
+### Container Issues
+
+If Docker Compose fails:
+
+```shell
+# Clean up and rebuild
+docker compose down -v
+docker compose build --no-cache
+docker compose up
+```
+
+### Session Caching (Local Development)
+
+Developers without LDAP credentials can cache session information:
+
+1. Visit `/user/cache`
+2. Press the "Cache me!" button
+3. Restart the server to clear the authorization cache if needed
+
+This writes your session to the ATR state directory, which is consulted
instead of LDAP. This feature only works in debug mode (`make serve-local`).
\ No newline at end of file
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
new file mode 100644
index 0000000..46f9395
--- /dev/null
+++ b/GOVERNANCE.md
@@ -0,0 +1,46 @@
+# Governance
+
+This document describes the governance model for Apache Trusted Releases (ATR).
+
+## Project Status
+
+ATR is developed by **ASF Tooling**, an initiative of the Apache Software
Foundation rather than a top-level project (TLP). This means ATR follows the
development processes and governance structure of Tooling.
+
+> **Note:** As of January 2026, this code is available for internal ASF
feedback only. The project is in alpha development and subject to significant
changes.
+
+## ASF Tooling
+
+ASF Tooling is an ASF initiative launched in 2025, responsible for:
+
+- Streamlining development across the ASF
+- Automating repetitive tasks
+- Reducing technical debt
+- Enhancing collaboration throughout the ASF
+
+## Decision Making
+
+*TODO: Document the decision-making process for ATR.*
+
+## Roles and Responsibilities
+
+*TODO: Document roles (committers, PMC members, contributors, etc.)*
+
+## Communication
+
+- **Mailing List:**
[[email protected]](https://lists.apache.org/[email protected])
+- **Slack:**
[#apache-trusted-releases](https://the-asf.slack.com/archives/C049WADAAQG)
+- **Issue Tracker:** [GitHub
Issues](https://github.com/apache/tooling-trusted-releases/issues)
+
+## Code of Conduct
+
+All participants in the ATR community are expected to follow the [ASF Code of
Conduct](https://www.apache.org/foundation/policies/conduct.html).
+
+## Related ASF Policies
+
+- [Apache Release Policy](https://www.apache.org/legal/release-policy.html)
+- [ASF Contributor License
Agreements](https://www.apache.org/licenses/contributor-agreements.html)
+- [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)
+
+---
+
+*TODO: This document is a placeholder. Full governance details will be added
as the project structure is formalized.*
\ No newline at end of file
diff --git a/README.md b/README.md
index ee2a813..bf7f3a7 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@
<a href="https://github.com/apache/tooling-trusted-releases/blob/main/LICENSE";>
<img alt="Apache License"
src="https://img.shields.io/github/license/apache/tooling-trusted-releases";
/></a>
-**NOTE: New contributors must introduce themselves on [the development mailing
list first](mailto:[email protected]), to deter spam. Contributions are
very welcome, but please do not submit a PR until you have introduced yourself
first.**
+> **NOTE:** New contributors must introduce themselves on [the development
mailing list](mailto:[email protected]) first, to deter spam.
Contributions are very welcome, but please do not submit a PR until you have
introduced yourself.
## Status
@@ -21,31 +21,67 @@ The project is in **alpha development** and subject to
significant changes.
We welcome feedback and discussion, but note that many known issues and design
refinements are already scheduled for future iterations.
Please review our [issue
tracker](https://github.com/apache/tooling-trusted-releases/issues) and inline
comments before filing new issues.
-The alpha test deployment is available at:
-🔗 <https://release-test.apache.org/>
+**Alpha test deployment:** 🔗 https://release-test.apache.org/
> **Note:** This repository is not yet an officially maintained or endorsed
> ASF project.
> It does not represent final technical or policy decisions for future ASF
> Tooling products.
> The code is provided without guarantees regarding stability, security, or
> backward compatibility.
+## Quick Start
+
+**Run with Docker Compose (recommended):**
+
+```shell
+git clone https://github.com/apache/tooling-trusted-releases.git
+cd tooling-trusted-releases
+mkdir -p state
+docker compose up --build
+```
+
+Then visit https://127.0.0.1:8080/ (accept the self-signed certificate).
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for more options including running
without containers.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [DEVELOPMENT.md](DEVELOPMENT.md) | Quick start guide for developers |
+| [BUILD.md](BUILD.md) | Build instructions and Make targets |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute code |
+| [SUPPORT.md](SUPPORT.md) | Getting help and reporting issues |
+| [GOVERNANCE.md](GOVERNANCE.md) | Project governance |
+
+**Online documentation:** https://release-test.apache.org/docs/
+
## Getting Involved
-Community feedback is encouraged!
-If you are an ASF committer or contributor interested in Trusted Releases:
+Community feedback is encouraged! If you are an ASF committer or contributor
interested in Trusted Releases:
-1. **Try it out** – The alpha test server allows you to experiment with the
release process for your ASF project.
+1. **Try it out** – The [alpha test server](https://release-test.apache.org/)
allows you to experiment with the release process.
2. **Introduce yourself** on the development mailing list:
- 📧 [[email protected]](mailto:[email protected]) (Subscribe by
sending email with empty subject and body to
[[email protected]](mailto:[email protected]) and
replying to the automated response, per the [ASF mailing list
how-to](https://www.apache.org/foundation/mailinglists))
+ 📧 [[email protected]](mailto:[email protected])
+
+ Subscribe by sending email with empty subject and body to
[[email protected]](mailto:[email protected]) and
replying to the automated response (per the [ASF mailing list
how-to](https://www.apache.org/foundation/mailinglists)).
3. **Share ideas or file issues:**
Use the [GitHub
Issues](https://github.com/apache/tooling-trusted-releases/issues) page to
report bugs, suggest features, or discuss improvements.
-As mentioned above, **new contributors must introduce themselves on the
development mailing list first**, to deter spam. Contributions are very
welcome, but please do not submit a PR until you have introduced yourself
otherwise it will likely be rejected.
+4. **Chat with us:**
+ 💬
[#apache-trusted-releases](https://the-asf.slack.com/archives/C049WADAAQG) on
ASF Slack
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
-## Contribute to the project
+**Key resources for contributors:**
-Our [contribution
guide](https://release-test.apache.org/docs/how-to-contribute) contains lots
more useful information. You will need to learn how to [run the
server](https://release-test.apache.org/docs/running-the-server), and [run and
create tests](https://release-test.apache.org/docs/running-and-creating-tests)
in order to be able to contribute.
+- [Contribution
policies](https://release-test.apache.org/docs/how-to-contribute) – ASF
policies, commit style, security guidelines
+- [Developer guide](https://release-test.apache.org/docs/developer-guide) –
Technical documentation
+- [Server reference](https://release-test.apache.org/docs/running-the-server)
– Architecture and configuration details
+- [Running and creating
tests](https://release-test.apache.org/docs/running-and-creating-tests) –
Testing guide
+- [Code conventions](https://release-test.apache.org/docs/code-conventions) –
Style guidelines
## License
@@ -54,4 +90,4 @@ This project is licensed under the [Apache License, Version
2.0](LICENSE).
---
*Part of the [Apache Tooling Initiative](https://tooling.apache.org/).*
-For more information about the ASF, visit
[https://www.apache.org/](https://www.apache.org/).
+For more information about the ASF, visit https://www.apache.org/.
\ No newline at end of file
diff --git a/SUPPORT.md b/SUPPORT.md
new file mode 100644
index 0000000..280fa52
--- /dev/null
+++ b/SUPPORT.md
@@ -0,0 +1,55 @@
+# Support
+
+This document describes how to get help with Apache Trusted Releases (ATR).
+
+## Getting Help
+
+### Mailing List (Primary)
+
+The development mailing list is the primary forum for ATR discussions:
+
+📧
**[[email protected]](https://lists.apache.org/[email protected])**
+
+**To subscribe:** Send an email with empty subject and body to
[[email protected]](mailto:[email protected]) and
reply to the automated response.
+
+### Slack
+
+Chat with the team in real-time:
+
+💬
**[#apache-trusted-releases](https://the-asf.slack.com/archives/C049WADAAQG)**
on ASF Slack
+
+### Issue Tracker
+
+Report bugs or request features:
+
+🐛 **[GitHub
Issues](https://github.com/apache/tooling-trusted-releases/issues)**
+
+## Reporting Bugs
+
+1. Check [existing
issues](https://github.com/apache/tooling-trusted-releases/issues) to avoid
duplicates
+2. [Create a new
issue](https://github.com/apache/tooling-trusted-releases/issues/new) with:
+ - Clear description of the problem
+ - Steps to reproduce
+ - Expected vs. actual behavior
+ - Environment details (OS, browser, etc.)
+
+## Security Issues
+
+⚠️ **Do not open public issues for security vulnerabilities.**
+
+Follow the [ASF security reporting process](https://www.apache.org/security/)
to report security issues responsibly.
+
+## Documentation
+
+- **[ATR Documentation](https://release-test.apache.org/docs/)** - Full
platform documentation
+- **[Tutorial](https://release-test.apache.org/tutorial)** - Getting started
guide
+- **[DEVELOPMENT.md](DEVELOPMENT.md)** - Developer quick start
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contribution guide
+
+## Status
+
+The alpha test deployment is available at: **https://release-test.apache.org/**
+
+---
+
+*TODO: This document is a placeholder. Additional support information will be
added as the project matures.*
\ No newline at end of file
diff --git a/atr/docs/how-to-contribute.md b/atr/docs/how-to-contribute.md
index e3bcbcc..ce94361 100644
--- a/atr/docs/how-to-contribute.md
+++ b/atr/docs/how-to-contribute.md
@@ -8,118 +8,100 @@
**Sections**:
-* [Introduction](#introduction)
-* [Finding something to work on](#finding-something-to-work-on)
-* [Pull request workflow](#pull-request-workflow)
+* [Quick start](#quick-start)
* [Commit message style](#commit-message-style)
* [ASF contribution policies](#asf-contribution-policies)
* [Special considerations for ATR](#special-considerations-for-atr)
* [Getting help](#getting-help)
-## Introduction
+## Quick start
-ATR is developed by ASF Tooling in public as open source code, and we welcome
high quality contributions from external contributors. Whether you are fixing a
typographical error in documentation, improving an error message, implementing
a new feature, or addressing a security issue, your contribution helps to
improve ATR for all of our users.
+For the contribution workflow, see
**[CONTRIBUTING.md](https://github.com/apache/tooling-trusted-releases/blob/main/CONTRIBUTING.md)**
in the repository root.
-This page explains how to contribute code and documentation to ATR. We
recommend reading the [platform introduction](introduction-to-atr) and
[overview of the code](overview-of-the-code) first to understand the purpose of
ATR and how the codebase is structured. You should also read the [code
conventions](code-conventions) page; we expect all contributions to follow
those conventions.
+That guide covers:
-**IMPORTANT: New contributors must introduce themselves on [the development
mailing list first](mailto:[email protected]), to deter spam.**
Contributions are very welcome, but please do not submit a PR until you have
introduced yourself first.
+- Development setup
+- Pull request workflow
+- Running tests
+- Code standards summary
-## Finding something to work on
+**IMPORTANT:** New contributors must introduce themselves on [the development
mailing list](mailto:[email protected]) first, to deter spam. Please do
not submit a PR until you have introduced yourself.
-The easiest way to find something to work on is to look at our [issue
tracker](https://github.com/apache/tooling-trusted-releases/issues) on GitHub.
We label [issues that are suitable for new
contributors](https://github.com/apache/tooling-trusted-releases/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22)
as `good first issue`. These are typically small, well-defined tasks that do
not require deep familiarity with the entire codebase. Working on one of these
issues [...]
-
-If you find a bug that is not already reported in the issue tracker, or if you
have an idea for a new feature, please [create a new
issue](https://github.com/apache/tooling-trusted-releases/issues/new) to
discuss it with other developers before you start working on it. This helps to
ensure that your contribution will be accepted, and that you do not duplicate
work that is already in progress. For small changes such as fixing
typographical errors or improving documentation clarity, you do [...]
-
-## Pull request workflow
-
-Once you have identified something to work on, the process of contributing is
as follows:
-
-1. **Fork the repository.** Create a personal fork of the [ATR
repository](https://github.com/apache/tooling-trusted-releases) on GitHub.
-
-2. **Clone your fork.** Clone your fork to your local machine and set up your
development environment. Follow the instructions in the [running the
server](running-the-server) guide to get ATR running locally. Please [ask us
for help](#getting-help) if you encounter any problems with this step.
-
-3. **Ensure that you enable pre-commit checks.** Download
[pre-commit](https://pre-commit.com/), [install
`biome`](https://biomejs.dev/guides/manual-installation/), and run `pre-commit
install` in the ATR repository where you are going to make your changes.
-
-4. **Install Python dependencies.** [Install `uv` if you do not have it
already](https://docs.astral.sh/uv/getting-started/installation/), and run `uv
sync --frozen --all-groups` to install Python dependencies.
-
-5. **Create a branch.** [Create a new
branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository)
for your work. Use a descriptive name that indicates what you are working on,
such as `fix-typo-in-docs` or `improve-error-messages`.
-
-6. **Make your changes.** Implement your fix or feature, following our [code
conventions](code-conventions). If you are changing code, ensure that your
changes do not break existing functionality. Whenever you change code, and
especially if you are adding a new feature, consider [adding a
test](running-and-creating-tests).
-
-7. **Commit your changes.** Write clear, concise commit messages following
[our commit message style](#commit-message-style). Each commit should represent
a logical unit of work, but we are not particularly strict about this.
-
-8. **Push your branch.** Push your branch to your fork on GitHub.
-
-9. **Create a pull request (PR).** The PR should be from your branch to the
`main` branch of the ATR repository. In the PR description, explain what your
changes do and why they are needed. If your PR addresses an existing issue,
reference that issue by number. Use the rebase strategy, not merge, to keep
your PR up to date as you work on it. Mark your PR as a draft until it is ready
for review.
-
-10. **Participate in code review.** A member of the Tooling team will review
your PR and may request changes. _We strongly recommend enabling the option to
allow maintainers to edit your PR when you create it._ Even if you allow us to
make changes, we may still ask you to make the changes yourself. Also, because
of the stringent security and usability requirements for ATR, we accept only
[high quality contributions](#special-considerations-for-atr).
-
-You can also [email
patches](https://lists.apache.org/[email protected]) if you
prefer not to use GitHub. Please use standard Git patch formatting, as if you
were e.g. contributing to the Linux Kernel.
+The rest of this page covers detailed policies and guidelines.
## Commit message style
-We follow a consistent style for commit messages. The first line of the commit
message is called the subject line, and should follow these guidelines:
+We follow a consistent style for commit messages. The first line (subject
line) should:
-* **Use the imperative mood.** The subject line should complete the sentence
"If applied, this commit will...".
-* **Use sentence case.** Start with a capital letter, but do not use a full
stop at the end.
-* **Use articles as appropriate before nouns**. Write about "a feature" not
just "feature". Say, for example, "fix a bug", and not "fix bug".
-* **Be specific and descriptive.** Prefer "Fix a bug in vote resolution for
tied votes" to "Fix a bug" or "Update the vote code".
-* **Keep it concise.** Aim for 50 to 72 characters. If you need more space to
explain your changes, use the commit body.
+* **Use the imperative mood.** Complete the sentence "If applied, this commit
will..."
+* **Use sentence case.** Start with a capital letter, no full stop at the end.
+* **Use articles before nouns.** Write "Fix a bug", not "Fix bug".
+* **Be specific and descriptive.** Prefer "Fix a bug in vote resolution for
tied votes" to "Fix a bug".
+* **Keep it concise.** Aim for 50-72 characters.
-**Examples of good subject lines:**
+**Good examples:**
-```cmd
+```
Add distribution platform validation to the compose phase
Fix a bug with sorting version numbers containing release candidates
Move code to delete releases to the storage interface
Update dependencies
```
-**Examples of poor subject lines:**
+**Poor examples:**
-```cmd
+```
fixed stuff
Updated the code.
refactoring vote resolution logic
```
-Most commits do not need a body. The subject line alone is sufficient for
small, focused changes. If, however, your commit is complex or requires
additional explanation, add a body separated from the subject line by a blank
line. In the body, explain what the change does and why it was necessary. We
typically use itemized lists for this, using asterisks. You do not need to
explain how the change works.
+Most commits do not need a body. For complex changes, add a body separated by
a blank line explaining _what_ and _why_ (not how). We typically use
asterisk-itemized lists.
## ASF contribution policies
-As an Apache Software Foundation project, ATR follows the standard ASF
contribution and licensing policies. These policies ensure that the ASF has the
necessary rights to distribute your contributions, and that contributors retain
their rights to use their contributions for other purposes.
+As an Apache Software Foundation project, ATR follows standard ASF
contribution and licensing policies.
### Contributor License Agreement
-Before we can accept your first contribution as an individual contributor, you
must sign the [Apache Individual Contributor License
Agreement](https://www.apache.org/licenses/contributor-agreements.html#clas)
(ICLA). This is a one-time requirement, and you do not need to sign a new ICLA
for each contribution. The ICLA grants the ASF the right to distribute and
build upon your work within Apache, while you retain full rights to use your
original contributions for any other purpose. The IC [...]
+Before your first contribution, you must sign the [Apache Individual
Contributor License
Agreement](https://www.apache.org/licenses/contributor-agreements.html#clas)
(ICLA). This is a one-time requirement.
+
+The ICLA grants the ASF the right to distribute and build upon your work,
while you retain full rights to use your contributions for any other purpose.
It is not a copyright assignment. See the [ASF new committers
guide](https://infra.apache.org/new-committers-guide.html#submitting-your-individual-contributor-license-agreement-icla)
for submission instructions.
-If your employer holds rights to your work, then you may also need to submit a
[Corporate Contributor License
Agreement](https://www.apache.org/licenses/contributor-agreements.html#clas)
(CCLA). Please consult with your employer to determine whether this is
necessary.
+If your employer holds rights to your work, you may also need a [Corporate
Contributor License
Agreement](https://www.apache.org/licenses/contributor-agreements.html#clas)
(CCLA). Consult your employer to determine if this is necessary.
### Licensing
-All contributions to ATR are licensed under the [Apache License
2.0](https://www.apache.org/licenses/LICENSE-2.0). By submitting a pull
request, you agree that your contributions will be licensed under this license.
If you include any third party code or dependencies in your contribution, you
must ensure that they are compatible with the Apache License 2.0. The ASF
maintains a list of [Category A
licenses](https://www.apache.org/legal/resolved.html#category-a) that are
compatible, and [C [...]
+All contributions are licensed under the [Apache License
2.0](https://www.apache.org/licenses/LICENSE-2.0). By submitting a pull
request, you agree to this license.
+
+Third-party code or dependencies must be compatible with Apache License 2.0:
+
+* [Category A licenses](https://www.apache.org/legal/resolved.html#category-a)
- Compatible
+* [Category X licenses](https://www.apache.org/legal/resolved.html#category-x)
- Not compatible
### Code of conduct
-All contributors to ATR are expected to follow the [ASF Code of
Conduct](https://www.apache.org/foundation/policies/conduct.html), and any
other applicable policies of the ASF.
+All contributors must follow the [ASF Code of
Conduct](https://www.apache.org/foundation/policies/conduct.html).
## Special considerations for ATR
-ATR is developed by ASF Tooling, which is an initiative of the ASF rather than
a top-level project (TLP). This means that ATR follows the development
processes and governance structure of Tooling, which may differ slightly from
those of other ASF projects. There are also significant security considerations
for ATR, which places additional requirements on contributions.
+ATR is developed by ASF Tooling, an ASF initiative rather than a top-level
project (TLP). This affects governance and development processes. More
significantly, ATR has stringent security requirements.
### Security focus
-The primary goal of ATR is to deter and minimize supply chain attacks on ASF
software releases. Since security is our highest priority, we scrutinize all
contributions for potential vulnerabilities. To assist us when you make a
contribution, please:
+The primary goal of ATR is to deter and minimize supply chain attacks on ASF
software releases. We scrutinize all contributions for potential
vulnerabilities.
+
+When contributing:
-* Follow secure coding practices. Review best practice guidelines to learn how
to avoid vulnerabilities such as injection attacks, cross-site scripting, and
insecure deserialization.
-* Validate all user inputs and sanitize all outputs.
-* Use well established, independently audited, and actively maintained
libraries rather than implementing cryptographic or security sensitive
functionality yourself.
-* Always consider the security implications of your changes. If you are unsure
of the implications of your changes, ask the team for guidance.
-* Report any security issues you discover in ATR responsibly. Do not open a
public issue for security vulnerabilities. Instead, follow the [ASF security
reporting process](https://www.apache.org/security/).
+* **Follow secure coding practices.** Avoid injection attacks, cross-site
scripting, insecure deserialization.
+* **Validate all inputs and sanitize all outputs.**
+* **Use established libraries** for cryptographic or security-sensitive
functionality. Prefer well-established, independently audited, actively
maintained libraries.
+* **Consider security implications.** If unsure, ask the team for guidance.
+* **Report vulnerabilities responsibly.** Do not open public issues for
security problems. Follow the [ASF security reporting
process](https://www.apache.org/security/).
### High quality standards
-Because of the critical nature of ATR, we maintain very high standards for
code quality. This means that the review process may take longer than you
expect, and we may request more extensive changes than you are accustomed to.
We appreciate your patience and understanding. Our goal is to ensure that ATR
remains as secure and reliable as possible.
+Because of ATR's critical nature, we maintain very high code quality
standards. The review process may take longer than expected, and we may request
extensive changes. Our goal is to keep ATR as secure and reliable as possible.
### Access controls
@@ -127,11 +109,11 @@ We strongly encourage all contributors to enable
two-factor authentication on th
## Getting help
-If you have questions about contributing to ATR, or if you need help with any
step of the contribution process, please reach out to the team. You can:
+* **Mailing list:**
[[email protected]](https://lists.apache.org/[email protected])
- Primary forum for development discussions
+* **Issue tracker:** [GitHub
Issues](https://github.com/apache/tooling-trusted-releases/issues) - Comment on
issues or PRs
+* **Slack:**
[#apache-trusted-releases](https://the-asf.slack.com/archives/C049WADAAQG) on
ASF Slack
+* **Documentation:** The rest of the [Developer Guide](developer-guide)
-* Ask questions on the [dev mailing
list](https://lists.apache.org/[email protected]), which is the
primary forum for ATR development discussions.
-* Comment on the relevant issue or pull request in the [issue
tracker](https://github.com/apache/tooling-trusted-releases/issues).
-* Chat with us in the [#apache-trusted-releases
channel](https://the-asf.slack.com/archives/C049WADAAQG) on ASF Slack.
-* Read the rest of the [developer guide](developer-guide) for detailed
information about how ATR works and how to make changes to it.
+### Alternative: email patches
-We welcome all types of contribution, and are happy to help you get started.
Thank you for your interest in contributing to ATR.
+If you prefer not to use GitHub, you can [email
patches](https://lists.apache.org/[email protected]) using
standard Git patch formatting.
\ No newline at end of file
diff --git a/atr/docs/running-the-server.md b/atr/docs/running-the-server.md
index 4cefa90..f8ec11f 100644
--- a/atr/docs/running-the-server.md
+++ b/atr/docs/running-the-server.md
@@ -8,104 +8,98 @@
**Sections**:
-* [Introduction](#introduction)
-* [Get the source](#get-the-source)
-* [Run the server in an OCI container](#run-the-server-in-an-oci-container)
-* [Run the server directly](#run-the-server-directly)
+* [Quick start](#quick-start)
+* [Server architecture](#server-architecture)
+* [Configuration details](#configuration-details)
+* [Authentication and sessions](#authentication-and-sessions)
-## Introduction
+## Quick start
-To develop ATR locally, we manage dependencies using
[uv](https://docs.astral.sh/uv/). To run ATR on ASF hardware, we run it in
containers managed by Puppet, but since this guide is about development, we
focus on using Compose and uv. ATR can be developed on Linux or macOS. Windows
and other platforms are not supported.
+For step-by-step setup instructions, see
**[DEVELOPMENT.md](https://github.com/apache/tooling-trusted-releases/blob/main/DEVELOPMENT.md)**
in the repository root.
-## Get the source
+That guide covers:
-[Fork the source
code](https://github.com/apache/tooling-trusted-releases/fork) of [ATR on
GitHub](https://github.com/apache/tooling-trusted-releases), and then [clone
your fork
locally](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository).
+- Prerequisites and platform-specific installation
+- Running with Docker Compose (recommended)
+- Running directly with uv and mkcert
+- Development workflow and troubleshooting
-There are lots of files and directories in the root of the ATR Git repository.
The most important thing to know is that `atr/` contains the source code. ATR
is a Python application based on
[ASFQuart](https://github.com/apache/infrastructure-asfquart), which is based
on [Quart](https://github.com/pallets/quart). The Quart web framework is an
asynchronous version of [Flask](https://github.com/pallets/flask), a very
widely used synchronous web framework. In addition to Python, we use small [...]
+The rest of this page provides deeper technical context for how the server
works.
-Once you have the source, there are two ways of running the server: [in an OCI
container](#run-the-server-in-an-oci-container), or
[directly](#run-the-server-directly). The following sections explain how to do
this. The trade off is that running in an OCI container gives more isolation
from the system, but is slower. Running directly is fast, and does not require
you to configure your browser to trust the certificate, but requires more
manual set up. Do not use both methods simultaneousl [...]
+## Server architecture
-## Run the server in an OCI container
+ATR is a Python application based on
[ASFQuart](https://github.com/apache/infrastructure-asfquart), which is based
on [Quart](https://github.com/pallets/quart). Quart is an asynchronous version
of [Flask](https://github.com/pallets/flask). In addition to Python, we use
small amounts of JavaScript and TypeScript for the front end.
-The easiest way to run the ATR server with all dependencies included is using
Docker Compose. This builds an OCI container based on the Alpine Linux
distribution that includes external tools such as CycloneDX, syft, and Apache
RAT, syft which are required for SBOM generation and license checking.
+**Running in containers:** On ASF infrastructure, ATR runs in containers
managed by Puppet. For development, we use Docker Compose with an Alpine Linux
base image that includes external tools (CycloneDX, syft, Apache RAT) required
for SBOM generation and license checking.
-To run ATR in a container, you need an OCI compatible container runtime with
Compose support such as Docker or Podman. Then, in the ATR root source
directory, use your Compose tool to bring the container up. If using Docker,
for example, run:
+**Running directly:** For faster iteration, you can run ATR directly using uv
and Hypercorn. This requires manually installing dependencies and generating
TLS certificates with mkcert.
-```shell
-mkdir -p state
-[LDAP_BIND_DN=dn LDAP_BIND_PASSWORD=pass] docker compose up --build
-```
+**Trade-offs:**
-The first build will take several minutes as Compose downloads and compiles
dependencies. Subsequent runs will be faster due to caching.
+| Method | Pros | Cons |
+|--------|------|------|
+| Container | Isolated, includes all tools | Slower startup, certificate trust
setup |
+| Direct | Fast iteration, auto-trusted certs | Manual dependency setup |
-This setup mounts your local `atr/` directory into the container, so code
changes are reflected immediately without rebuilding. The containerised server
runs with `--reload` enabled, and automatically restarts when files change.
+**Important:** Do not run both methods simultaneously - they share the same
state directory and will conflict.
-The container runs in test mode (`ALLOW_TESTS=1`), which enables mock
authentication. Visit [`https://127.0.0.1:8080/`](https://127.0.0.1:8080/) to
access the site. You will need to accept the self-signed certificate. Browser
vendors update the methods to achieve this, so documenting this is a moving
target, but there is some advice from [Simple Web
Server](https://github.com/terreng/simple-web-server/blob/main/website/src/docs/https.md#using-a-dummy-certificate-for-testing-purposes)
and [...]
+## Configuration details
-To stop the server, press `Ctrl+C` or run your Compose tool equivalent of
`compose down` in the same directory in another terminal session. Do not run
ATR in a container if also running it directly.
+### TLS requirements
-If you use are using Docker, you can start a terminal session in a container
using `docker compose exec atr bash`, and you can start a container and run a
shell instead of ATR using `docker compose run -rm atr bash`.
+ATR requires TLS even for development because login is performed through the
actual ASF OAuth server. This ensures development behavior aligns closely with
production.
-## Run the server directly
+The `make certs-local` target generates certificates using mkcert:
-### Install dependencies
+```shell
+mkcert localhost.apache.org 127.0.0.1 ::1
+```
-To run ATR directly, on the local machine, after cloning the source, you will
need to install the following dependencies:
+We exclude `localhost` to avoid [DNS resolution issues noted in RFC
8252](https://datatracker.ietf.org/doc/html/rfc8252#section-8.3).
-* [cmark](https://github.com/commonmark/cmark) (optional; for rebuilding
documentation)
-* Any [POSIX](https://en.wikipedia.org/wiki/POSIX) compliant
[make](https://frippery.org/make/)
-* [mkcert](https://github.com/FiloSottile/mkcert)
-* [Python 3.13](https://www.python.org/downloads/release/python-3138/)
-* [uv](https://docs.astral.sh/uv/#installation)
+### Host configuration
-You can install Python 3.13 through your package manager or through uv. Here
is how to install these dependencies on [Alpine
Linux](https://en.wikipedia.org/wiki/Alpine_Linux):
+ATR serves on multiple hosts, but we recommend using `localhost.apache.org`
consistently. This requires an `/etc/hosts` entry:
-```shell
-apk add cmark curl git make mkcert@testing
-curl -LsSf https://astral.sh/uv/install.sh | env
UV_INSTALL_DIR="/usr/local/bin" sh
-uv python install 3.13
```
-
-For Homebrew on macOS these instructions become:
-
-```shell
-brew install cmark mkcert
-curl -LsSf https://astral.sh/uv/install.sh | sh
-rehash
-uv python install 3.13
+127.0.0.1 localhost.apache.org
```
-### Run the server
+**Why this matters:** Logging into the site on one host does not log you in on
another host. Pick one and use it consistently.
-Then, to run the server:
+### Environment variables
-```shell
-cd tooling-trusted-releases/
-mkdir state
-make certs-local
-make serve-local
-```
+| Variable | Description |
+|----------|-------------|
+| `ALLOW_TESTS=1` | Enable test mode with mock authentication |
+| `APP_HOST` | Hostname for the application |
+| `BIND` | Address and port to bind (default: `127.0.0.1:8080`) |
+| `LDAP_BIND_DN` | LDAP bind DN for rsync writes |
+| `LDAP_BIND_PASSWORD` | LDAP bind password |
+| `SSH_HOST` | SSH host for rsync operations |
-The `certs-local` step runs `mkcert localhost.apache.org 127.0.0.1 ::1` to
generate a locally trusted TLS certificate. To avoid potential DNS resolution
issues such as [those alluded to in RFC
8252](https://datatracker.ietf.org/doc/html/rfc8252#section-8.3), we do not
include `localhost`. If the certificate is not trusted, you may have to follow
the [mkcert guide](https://github.com/FiloSottile/mkcert/blob/master/README.md)
to resolve the issue.
+### Startup behavior
-**Note**: Using ```mkcert --install``` carries a risk, as by default it
installs a new CA for the system, Java, and Firefox. The CA is valid for 10
years, and it is not possible to change the expiry date when creating the CA
cert. If the private key ```rootCA-key.pem``` (which is created in the
directory shown by ```mkcert -CAROOT``) should ever be leaked, anyone could
create SSL certificates that are trusted by your system. See [mkcert usaage
caveat](https://github.com/FiloSottile/mkcer [...]
+On first startup, the server fetches committee and project information from
the ASF website. This takes 1-2 minutes, during which no existing committees or
projects will appear.
-ATR requires TLS even for development because login is performed through the
actual ASF OAuth server. This way, the development behavior aligns closely with
the production behavior. We try to minimize differences between development and
production environments.
+## Authentication and sessions
-Do not run ATR directly if also running it in an OCI container.
+### ASF OAuth
-### Load the site
+ATR uses ASF OAuth for user authentication. Even in development, you
authenticate against the real ASF OAuth server. This is why TLS is required.
-ATR will then be served on various hosts, but we recommend using only
`localhost.apache.org`. This requires adding an entry to your `/etc/hosts` and
potentially restarting your DNS server. If you do this, the following link
should work:
+### Session caching for developers
-[`https://localhost.apache.org:8080/`](https://localhost.apache.org:8080/)
+Developers without LDAP credentials will be unable to perform rsync writes,
and certain tasks may fail. To work around this in development:
-If you do not want to change your `/etc/hosts`, you can use `127.0.0.1`. The
following link should work:
+1. Visit `/user/cache`
+2. Press the "Cache me!" button
-[`https://127.0.0.1:8080/`](https://127.0.0.1:8080/)
+This writes your session information to the ATR state directory (`state/`),
which is consulted instead of LDAP when present.
-Pick one or the other, because logging into the site on one host does not log
you in to the site on any other host.
+To clear cached session data:
-It will take one or two minutes for the server to fetch committee and project
information from the ASF website. Until the fetch is complete, no existing
committees and projects will show.
+1. Use the clear button on `/user/cache`
+2. Restart the server (the `atr/principal.py` module caches authorization in
memory)
-Developers without LDAP credentials will be unable to perform `rsync` writes
and certain tasks may also fail. To enable these actions to succeed, visit
`/user/cache` and press the "Cache me!" button. This writes your session
information to the ATR state directory, where it will be consulted instead of
an LDAP lookup if it exists. The same page also allows you to clear your
session cache data. When you clear your session cache data, the
`atr/principal.py` module will still likely cache yo [...]
+**Note:** Session caching only works in debug mode, which is enabled when
using `make serve-local`.
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
