<div align="center">
  <img src="docs/assets/vresto_logo.jpg" alt="vresto logo" width="320" />
  
  # vresto
  
  **A beautiful, professional Python toolkit for searching and accessing Copernicus Sentinel satellite data**
  
  [![PyPI version](https://badge.fury.io/py/vresto.svg)](https://badge.fury.io/py/vresto)
  [![Tests](https://github.com/kalfasyan/vresto/actions/workflows/tests.yml/badge.svg)](https://github.com/kalfasyan/vresto/actions/workflows/tests.yml)
  [![Docs](https://github.com/kalfasyan/vresto/actions/workflows/build-docs.yml/badge.svg)](https://github.com/kalfasyan/vresto/actions/workflows/build-docs.yml)
  [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
  [![Gitleaks](https://img.shields.io/badge/secret%20scanning-gitleaks-blue)](https://github.com/gitleaks/gitleaks)
</div>

---

## Features

- 🗺️ **Interactive Map Interface** - Visually search and filter satellite products
- 🔍 **Smart Search** - Filter by location, date range, cloud cover, and product type
- 📦 **Product Management** - Download quicklooks and metadata from S3
- 🐍 **Professional API** - Clean Python API for programmatic access
- 🔐 **Secure** - Handle S3 credentials safely with static key support
- ⚡ **Efficient** - Batch operations and smart caching

## ⚡ Quick Start with Docker 🐳

The fastest way to run `vresto` is by using Docker Compose 🚢

You only need Docker and Docker Compose installed on your machine. If you don't have them yet, you can find installation instructions on the [Docker website](https://docs.docker.com/get-docker/) and [Docker Compose documentation](https://docs.docker.com/compose/install/).

Start `vresto` in just a few steps:

1. **Clone the repository and go to its main directory**
    ```bash
    git clone https://github.com/kalfasyan/vresto.git && cd vresto
    ```

2. **Start the application with Docker Compose**
    ```bash
    docker compose up -d
    ```

✅ **Done!** 🎉

You're all set—your vresto dashboard is now running at:  
🌐 [http://localhost:8610](http://localhost:8610)

**Note:** You'll need to set Copernicus credentials to use the search functionality. You can do this by:
1. Setting environment variables in the docker-compose.yml:
   ```yaml
   environment:
     - COPERNICUS_USERNAME=your_email@example.com
     - COPERNICUS_PASSWORD=your_password
   ```
   
2. Or by creating a `.env` file in the project root before running `docker compose up`:
   ```bash
   export COPERNICUS_USERNAME="your_email@example.com"
   export COPERNICUS_PASSWORD="your_password"
   ```

<details>
<summary><strong>🚀 Essential Docker & Docker Compose Commands</strong></summary>

```bash
# Start the app in background (Docker Compose)
docker compose up -d
```

```bash
# View logs (Docker Compose)
docker compose logs -f
```

```bash
# Stop and remove services (Docker Compose)
docker compose down
```

```bash
# Rebuild and start (Docker Compose)
docker compose up -d --build
```

```bash
# Run the container directly (plain Docker)
docker run -d -p 8610:8610 \
  --name vresto-dashboard \
  vresto:latest
```

```bash
# View logs (plain Docker)
docker logs -f vresto-dashboard
```

```bash
# Stop and remove the container (plain Docker)
docker stop vresto-dashboard && docker rm vresto-dashboard
```
</details>

## Quick Start

**Note:** You need Copernicus credentials to use vresto. Get free access at https://dataspace.copernicus.eu/


### Installation

**From PyPI (recommended for users):**
```bash
docker run -d -p 8610:8610 \
  --name vresto-dashboard \
  vresto:latest
```

**For development:**
```bash
git clone https://github.com/kalfasyan/vresto.git
cd vresto
uv pip install -e .
```

### Configuration

Configure your credentials (see [Setup Guide](docs/getting-started/setup.md) for details):
```bash
export COPERNICUS_USERNAME="your_email@example.com"
export COPERNICUS_PASSWORD="your_password"
```

Or run the interactive setup helper which writes a `.env` in the project root:
```bash
python scripts/setup_credentials.py
```

### Launch the App

Simply run:
```bash
make app
```

Or directly with Python:
```bash
python src/vresto/ui/app.py
```

Opens at http://localhost:8610

**API usage:**
```python
from vresto.api import CatalogSearch, BoundingBox, CopernicusConfig
from vresto.products import ProductsManager

config = CopernicusConfig()
catalog = CatalogSearch(config=config)
bbox = BoundingBox(west=4.65, south=50.85, east=4.75, north=50.90)

products = catalog.search_products(
    bbox=bbox,
    start_date="2024-01-01",
    max_cloud_cover=20,
)

manager = ProductsManager(config=config)
for product in products[:5]:
    quicklook = manager.get_quicklook(product)
    if quicklook:
        quicklook.save_to_file(f"{product.name}.jpg")
```

For detailed setup and usage, see the documentation below.

## Documentation

- **[Setup Guide](docs/getting-started/setup.md)** ⭐ **Start here** - Installation, credentials setup, and configuration
- [API Guide](docs/user-guide/api.md) - Programmatic usage examples and reference
- [AWS CLI Guide](docs/advanced/aws-cli.md) - Direct S3 access with AWS CLI
- [Contributing](CONTRIBUTING.md) - Development setup

## Requirements

- Python 3.9+
- `uv` package manager (optional but recommended)

## License

See [LICENSE.txt](LICENSE.txt)
