1 files changed, 82 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..afb70a1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,82 @@
+<!--
+Back - An extremely simple git bug visualization system. Inspired by TVL's
+panettone.
+
+Copyright (C) 2024 Benedikt Peetz <benedikt.peetz@b-peetz.de>
+Copyright (C) 2025 Benedikt Peetz <benedikt.peetz@b-peetz.de>
+SPDX-License-Identifier: AGPL-3.0-or-later
+
+This file is part of Back.
+
+You should have received a copy of the License along with this program.
+If not, see <https://www.gnu.org/licenses/agpl.txt>.
+-->
+
+# Back
+
+> An extremely simple git issue tracking system. Inspired by tvix's panettone.
+
+## Usage
+
+`back` is modelled after `cgit`, only for `git-bug` initialized repositories.
+The server is than started at `http://127.0.0.1:8000` and provides access to the
+issues (bugs) tracked via `git-bug`, via multiple routes:
+
+### `/`
+
+The default index is a list of all repositories that have `git-bug` data in
+them.
+
+### `<repo_path>/issues/<state>`
+
+This path displays all issues in `<state>` (i.e., open or closed) for the
+repository at `<repo_path>`.
+
+### `<repo_path>/issue/<issue_id>`
+
+Displays the actual issue with `id` `<issue_id>`. Beware, that the `<isuse_id>`
+is sourced from the actual git object associated with the issue create commit.
+As such, it is not the same ID, as displayed by the `git-bug` CLI.
+
+### `<repo_path>/issues/feed`
+
+An RSS feed usable to subscribe to. This includes all issues and all comments of
+issues.
+
+## Configuration file
+
+The config file is passed to `back` via the first command line argument. It is
+written in JSON. An example configuration file is available at
+[`./contrib/config.json`](./contrib/config.json).
+
+Following keys are required:
+
+### `source_code_repository_url`
+
+The URL to the source code of this instance of `back`.
+
+### `root_url`
+
+The root URL this instance of `back` is hosted at. For example:
+`https://issues.foss-syndicate.org`. This is required by the RSS feed to
+generate links to the various issues/comments.
+
+### `scan_path`
+
+The path under which to search for the repositories as specified by the
+`projects.list` file. This is semantically the same as `cgit`'s `scan-path`.
+
+### `project_list`
+
+The path to the file specifying the repositories to search. A repository path
+per line. This is semantically the same as `cgit`'s `project-list`.
+
+### Note
+
+`back` needs write access to the repository, because of internal `gix` and `git`
+object reasons.
+
+## Licensing
+
+This project complies with the REUSE v3.3 specification. This means that every
+file clearly states its copyright.