This is an automated email from the ASF dual-hosted git repository.
sbp pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git
The following commit(s) were added to refs/heads/main by this push:
new 2f3c2aa Document how to run the development server using OCI
containers
2f3c2aa is described below
commit 2f3c2aaf266d316e2dda48c1b4afad56d5caf844
Author: Sean B. Palmer <[email protected]>
AuthorDate: Fri Jan 9 16:00:58 2026 +0000
Document how to run the development server using OCI containers
---
README.md | 8 ++++++--
atr/docs/running-the-server.md | 40 +++++++++++++++++++++++++++++++++-------
2 files changed, 39 insertions(+), 9 deletions(-)
diff --git a/README.md b/README.md
index 47a3b13..ee2a813 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@
This repository contains code developed by the **Apache Software Foundation
(ASF) Tooling team**.
-As of **October 2025**, this code is available for **internal ASF feedback
only**.
+As of **January 2026**, this code is available for **internal ASF feedback
only**.
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.
@@ -41,7 +41,11 @@ If you are an ASF committer or contributor interested in
Trusted Releases:
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. Our [contribution
guide](https://release-test.apache.org/docs/how-to-contribute) contains lots
more useful information.
+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.
+
+## Contribute to the project
+
+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.
## License
diff --git a/atr/docs/running-the-server.md b/atr/docs/running-the-server.md
index e287f4c..0a2d477 100644
--- a/atr/docs/running-the-server.md
+++ b/atr/docs/running-the-server.md
@@ -10,9 +10,8 @@
* [Introduction](#introduction)
* [Get the source](#get-the-source)
-* [Install dependencies](#install-dependencies)
-* [Run the server](#run-the-server)
-* [Load the site](#load-the-site)
+* [Run the server in an OCI container](#run-the-server-in-an-oci-container)
+* [Run the server directly](#run-the-server-directly)
## Introduction
@@ -24,9 +23,34 @@ To develop ATR locally, we manage dependencies using
[uv](https://docs.astral.sh
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 [...]
-## Install dependencies
+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 [...]
-To run ATR locally after cloning the source, you will need to install the
following dependencies:
+## Run the server in an OCI container
+
+The easiest way to run the ATR server with all dependencies included is using
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.
+
+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:
+
+```shell
+mkdir -p state
+docker compose up --build
+```
+
+The first build will take several minutes as Compose downloads and compiles
dependencies. Subsequent runs will be faster due to caching.
+
+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.
+
+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 [...]
+
+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.
+
+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`.
+
+## Run the server directly
+
+### Install dependencies
+
+To run ATR directly, on the local machine, after cloning the source, you will
need to install the following dependencies:
* [cmark](https://github.com/commonmark/cmark) (optional; for rebuilding
documentation)
* Any [POSIX](https://en.wikipedia.org/wiki/POSIX) compliant
[make](https://frippery.org/make/)
@@ -53,7 +77,7 @@ uv python install 3.13
ATR should work in any POSIX style environment.
-## Run the server
+### Run the server
Then, to run the server:
@@ -68,7 +92,9 @@ The `certs-local` step runs `mkcert localhost.apache.org
127.0.0.1 ::1` to gener
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.
-## Load the site
+Do not run ATR directly if also running it in an OCI container.
+
+### Load the site
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:
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
