Skip to content

Commit

Permalink
Misc documentation updates (#4091)
Browse files Browse the repository at this point in the history
* Update info about support channels

* Fix typo

* Remove architecture diagram

I updated the diagram to properly reflect the current code base, but realized there would be way too many edges between for it to be useful. I think the textual representation is more useful.

* Remove Memorious

* Fix typo

* Mention RabbitMQ in architecture docs

* Bump Astro version (and our docs theme)
  • Loading branch information
tillprochaska authored Jan 6, 2025
1 parent bb4b6da commit ca555fa
Show file tree
Hide file tree
Showing 13 changed files with 9,527 additions and 8,547 deletions.
6 changes: 3 additions & 3 deletions SUPPORT.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ The objective of the Aleph project is to provide powerful software to those who

## Eligible use cases

The maintainers of this project limit support and responses both on GitHub and in the Slack channel to authorised groups and individuals. In order to receive authorisation, we require that you disclose the manner in which you use our technology. **We will decide if that use falls within the intended uses of Aleph.**
The maintainers of this project limit support and responses both on GitHub and on Discourse to authorised groups and individuals. In order to receive authorisation, we require that you disclose the manner in which you use our technology. **We will decide if that use falls within the intended uses of Aleph.**

Examples of intended uses could include:

Expand All @@ -20,7 +20,7 @@ Support includes installation support, requests for new features or issues speci

Please submit a description of your use case along with your name, affiliation and email address using one of the following channels:

- The Slack #intros channel
- As part of the [Discourse](https://aleph.discourse.group/) signup process
- As part of the first GitHub issue that you file
- Via our [contact form](https://requests.occrp.org/datadesk)

Expand All @@ -30,4 +30,4 @@ Make sure you describe your goals, rather than the set of techniques that define

The Aleph team supports feature versions for 12 months after the first major iteration of that version was released. For example, we support Aleph 3.12.x for 12 months after Aleph 3.12.0 was released. The Aleph team supports upgrades, but only from supported feature versions of the product. Support means helping to ensure that you can get your Aleph instance up and running. As we're a small team we don't have the capacity to backport bugs to supported versions. In the case of critical secruity vulnrabilities we'll endeavour to ensure that all currently supported versions, but we recommend administrators upgrade to the latest version as soon as possible.

For versions that are supported, if you are having problems, you can reach out to us in Slack or by raising an issue in Github.
For versions that are supported, if you are having problems, you can reach out to us on Discourse or by raising an issue in Github.
1 change: 1 addition & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,4 @@ node_modules
dist
tmp
.DS_STORE
.astro
4 changes: 1 addition & 3 deletions docs/astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,7 @@ const root = path.dirname(url.fileURLToPath(import.meta.url));
const base = path.join(root, 'src/components');

export default defineConfig({
experimental: {
redirects: true,
},
scopedStyleStrategy: 'where',
redirects: {
'/how-aleph-is-used': '/about',
'/guide': '/users',
Expand Down
17,989 changes: 9,509 additions & 8,480 deletions docs/package-lock.json

Large diffs are not rendered by default.

3 changes: 1 addition & 2 deletions docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,9 @@
"license": "MIT",
"dependencies": {
"@alephdata/followthemoney": "^3.4.0",
"@astrojs/markdown-component": "^1.0.5",
"@rollup/plugin-yaml": "^4.1.1",
"@untitaker/hyperlink": "^0.1.26",
"astro": "^2.8.5",
"astro": "^5.1.2",
"astro-theme-docs": "github:alephdata/astro-theme-docs"
},
"devDependencies": {
Expand Down
2 changes: 1 addition & 1 deletion docs/src/components/ReferenceListing.astro
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
import Markdown from '@astrojs/markdown-component';
import { Markdown } from 'astro-theme-docs/components';
const { items } = Astro.props;
---

Expand Down
59 changes: 6 additions & 53 deletions docs/src/pages/developers/explanation/architecture/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,53 +9,6 @@ title: Architecture Overview

## Components

<Mermaid
straightEdges
highlightActive
content={`
graph TB
memorious("Memorious")
ui("UI")
alephclient("alephclient")
subgraph level2
api("API")
workers("Workers")
ingest("ingest-file")
end
subgraph level3
ftm("FtM store")
files("File archive")
db("App database")
es("Elasticsearch")
redis("Redis")
end
class level2 dummy
class level3 dummy
ui-->api
memorious-->api
alephclient-->api
api-->db
api-->es
api-->redis
api-->files
ingest-->redis
ingest-->files
ingest-->ftm
workers-->db
workers-->es
workers-->redis
workers-->files
workers-->ftm
`}
/>

### API

The Aleph API is a Flask application. It powers the web UI and alephclient, can be used to ingest data scraped using [Memorious crawlers](https://alephdata.github.io/memorious) or custom scripts.
Expand All @@ -66,7 +19,7 @@ The Aleph UI is a single-page application implemented using React. End users can

### Workers

Workers process background tasks such as [exporting search results](/users/search/basics#export-multiple-search-results), indexing updated new or entities in Elasticsearch, or [cross-referencing data against other datasets](/users/investigations/cross-referencing).
Workers process background tasks such as [exporting search results](/users/search/basics#export-multiple-search-results), indexing updated or new entities in Elasticsearch, or [cross-referencing data against other datasets](/users/investigations/cross-referencing).

### ingest-file

Expand All @@ -86,7 +39,11 @@ Elasticsearch is used to make data searchable. Aleph maintains [multiple indexes

### Redis

Aleph uses Redis in many ways, for example as a task queue, to store user sessions, and to cache collection statistics.
Aleph uses Redis in many ways, for example to keep metadata about background tasks, to store user sessions, and to cache collection statistics.

### RabbitMQ

Aleph uses RabbitMQ as a disk-based queue for background tasks.

### File archive

Expand All @@ -96,10 +53,6 @@ The file archive stores all files uploaded to Aleph. It supports multiple storag

alephclient is a Python library and CLI that simplifies common tasks (e.g. batch uploads). It interacts with Aleph via the API.

### Memorious

Memorious is a scraping toolkit that facilitates fast development and easy maintenance of scrapers. While Memorious integrates with Aleph and can emit data as FollowTheMoney entities, Memorious is a completely optional component.

## Code repositories

### `alephdata/aleph`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ title: Export Network Graphs

## Transformation strategy

Data in Aleph ist stored using [FollowTheMoney](/developers/explanation/followthemoney). FollowTheMoney sees every unit of information as an entity with a set of properties. To analyze this information as a network with nodes and edges, we need to decide what logic should rule the transformation of entities into nodes and edges. Different strategies are available:
Data in Aleph is stored using [FollowTheMoney](/developers/explanation/followthemoney). FollowTheMoney sees every unit of information as an entity with a set of properties. To analyze this information as a network with nodes and edges, we need to decide what logic should rule the transformation of entities into nodes and edges. Different strategies are available:

* Some entity schemata, such as `Directorship`, `Ownership`, `Family` or `Payment`, contain annotations that define how they can be transformed into an edge with a source and target.
* Entities also naturally reference others. For example, an `Email` has an emitters property that refers to a `LegalEntity`, the sender. The emitters property connects the two entities and can also be turned into an edge.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ layout: '@layouts/DevelopersLayout.astro'
title: Configuration Options
---

import options from './options.yml';
import options from './_options.yml';
import ReferenceListing from '@components/ReferenceListing.astro';

# Configuration Options
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ layout: '@layouts/DevelopersLayout.astro'
title: Prometheus Metrics
---

import metrics from './metrics.yml';
import metrics from './_metrics.yml';
import ReferenceListing from '@components/ReferenceListing.astro';

# Prometheus Metrics
Expand Down
4 changes: 2 additions & 2 deletions docs/src/pages/get-in-touch/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@ Aleph is an open source project developed by staff and volunteers. Everyone is i
While the Aleph source code is openly available and licensed, the community support for the system is subject to some criteria. Please refer to our [Support Policy](https://github.com/alephdata/aleph/blob/main/SUPPORT.md).
</Callout>

## Slack Community
## Discourse

Most discussion and support takes place on the **Aleph Slack**. Please follow the steps lined out in the [Aleph Support Policy](https://github.com/alephdata/aleph/blob/main/SUPPORT.md) to receive an invitation for the community.
Most discussion and support takes place on **Discourse**. Please follow the steps lined out in the [Aleph Support Policy](https://github.com/alephdata/aleph/blob/main/SUPPORT.md) to sign up for Discourse.

## Bugs

Expand Down

0 comments on commit ca555fa

Please sign in to comment.