Skip to content

development.md

Latest commit

 

History

History
115 lines (79 loc) · 2.52 KB

development.md

File metadata and controls

115 lines (79 loc) · 2.52 KB

Development

Guide for contributors working on Groupint source code.

Local setup

git clone https://github.com/OSINT-for-Ukraine/groupint.git
cd groupint
poetry install

Python 3.11 is required (pyproject.toml).

Pre-commit

pip install pre-commit
pre-commit install

On commit, linters and formatters run automatically. Fix reported issues before pushing.

Run Streamlit locally

poetry run streamlit run interface.py

Ensure Neo4j is reachable and NEO4J_URI is set in .env.

Tests

poetry run pytest

Example incident tests: tests/test_atlos_export.py, tests/test_watchlist_channels.py.

Docker during development

Rebuild after code changes:

./scripts/up-desktop.sh --build
# or
docker restart groupint-streamlit

Project layout (selected)

Path Purpose
interface.py Main Streamlit app
pages/2_Incidents.py Incidents UI
core/tg_api_connector.py Telethon operations
core/telegram_session.py StringSession persistence
core/incidents/ Incident pipeline
db/dal.py, db/queries.py Neo4j access
draw_graph/ Plotly graph builders
scripts/incident-worker.py Background worker
docker-compose.desktop.yml Desktop stack

Contributing

  1. Create a branch named for your change.
  2. Make focused commits with clear messages.
  3. Ensure pre-commit passes.
  4. Push and open a PR to main.
  5. Wait for CI and review.

Do not commit .env, secrets.toml, session files, or API keys.

Building documentation

Modular sources live under docs/. To build a single manual and PDF:

./scripts/build-docs.sh
Output Path
Merged Markdown docs/groupint-manual.md
PDF dist/groupint-manual.pdf

Prerequisites for PDF:

  • pandoc
  • A LaTeX PDF engine: texlive-xetex / texlive-basic (Debian/Arch), or tectonic
# Arch / Manjaro
sudo pacman -S pandoc texlive-basic

# Debian / Ubuntu
sudo apt install pandoc texlive-xetex

Merge only (skip PDF if pandoc is not installed, or force skip):

BUILD_DOCS_PDF=0 ./scripts/build-docs.sh

Edit the chapter list in scripts/merge_docs.py when adding new guides. CI uploads dist/groupint-manual.pdf as a workflow artifact on pushes to main.

Internal knowledge base

User documentation: docs/index.md.

Related