Installation

Installation#

Prerequisites#

Before installing, make sure you have the following on your system:

  • Python 3.10+ — python.org

  • uv — fast Python package manager (install guide)

  • Geospatial system libraries — required for geopandas / shapely:

    • macOS: brew install gdal proj geos

    • Linux (Debian/Ubuntu): apt-get install gdal-bin libgdal-dev libgeos-dev libproj-dev

    • Windows: install OSGeo4W or use WSL

  • pdflatex (optional) — only needed if report.compile_pdf: true in your config

Install#

1. Clone the repository

git clone https://github.com/dsih-artpark/acestor.git
cd acestor

2. Install dependencies

uv sync --extra dengue --extra cds --extra s3
Available extras#

Extra

What it adds

dengue

Geospatial and modeling stack: geopandas, scikit-learn, statsmodels, matplotlib

cds

Copernicus Climate Data Store (CDS) API client for weather downloads

s3

AWS S3 storage backend (boto3)

Install only what you need. For a local run without S3 or CDS:

uv sync --extra dengue

Environment Variables#

Create a .env file in the project root with your secrets. These are loaded automatically at runtime.

# Copernicus CDS — required if weather_download.source_mode = "cds"
CDS_API_KEY=your-cds-api-key

# SMTP — required if email.enabled = true
SMTP_FROM=sender@example.com
SMTP_HOST=smtp.example.com
SMTP_USERNAME=sender@example.com
SMTP_PASSWORD=your-password

# AWS — required if using S3 storage or S3 data sources
AWS_PROFILE=default
AWS_REGION=ap-south-1

You can reference these in your YAML config using ${VAR} or ${VAR:-default} syntax — they are resolved at config load time. Never commit real secrets to the config files.

Docker#

A pre-built Docker image is available on Docker Hub:

docker pull dsihartpark/acestor:latest

Images are tagged by version (e.g., dsihartpark/acestor:1.0.0) and built automatically on every GitHub release tag.

For production deployment on Docker or AWS EC2 — including systemd setup, IAM roles, S3 artifact storage, and log monitoring — see the Deployment Guide.

Verifying Installation#

Run a quick smoke test using the bundled example config:

uv run python -m acestor.run \
  --pipeline pipelines.dengue.pipeline:build_pipeline \
  --config configs-example/gba_docker_test.yaml \
  --run-id smoke-test

Exit code 0 means success. Outputs will be written to artifacts/smoke-test/.