vresto

An elegant Python interface for discovering and retrieving Copernicus Sentinel data.

---

Demo

(wait a few seconds for it to load)

Features

• 🗺️ Interactive Map Interface - Visually search and filter satellite products
• 🛰️ High-Resolution Tile Server - Instantly visualize full-resolution product bands on the map (via localtileserver)
• 🔍 Smart Search - Filter by location, date range, cloud cover, and product type
• 📦 Granular Download Management - Advanced Band-Resolution matrix for precise data selection and de-duplicated downloads
• 🔌 Dual Backend Support - Flexible discovery via OData or STAC APIs
• 🐍 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 and Docker Compose documentation.

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

Start vresto in just a few steps:

1. Clone the repository and go to its main directory

   git clone https://github.com/kalfasyan/vresto.git && cd vresto

2. Start the application with one command

   make docker-up

   ℹ️ That's it! The app will start and you can add credentials later via the UI, or provide them now:

   Option A: Add credentials now (Recommended if you have them)

   • Create a .env file from the committed template:

     cp .env.example .env
     # Edit .env with your credentials

   • Then run one of these commands:

     make docker-up

     or:

     docker compose up -d

   • .env is ignored by git; do not commit secrets.
   • Optional .env variables: COPERNICUS_S3_ACCESS_KEY, COPERNICUS_S3_SECRET_KEY, COPERNICUS_S3_ENDPOINT, VRESTO_BASE_TILE_PORT (default: 8611)

   Option B: Add credentials later (via the app Settings menu)

   • Just run make docker-up without credentials (use make docker-rebuild if you just cloned the repo and want a rebuild)
   • The app will start at http://localhost:8610 (tile server traffic is mapped via VRESTO_BASE_TILE_PORT)
   • Click the ☰ menu button in the top-left corner to open the Settings drawer
   • Add your Copernicus credentials through the Settings menu anytime
   • S3 credentials are optional—without them you'll get temporary credentials with usage limits (see Setup Guide for details)

✅ Done! 🎉

Your vresto dashboard is now running at:
🌐 http://localhost:8610

Note: If you pulled recent changes and a feature isn't available, rebuild the Docker image:

docker compose up -d --build

🚀 Essential Docker & Docker Compose Commands

# Start the app in background (Docker Compose)
make docker-up

# View logs (Docker Compose)
make docker-logs

# Stop and remove services (Docker Compose)
make docker-down

# Rebuild and start (Docker Compose)
make docker-rebuild

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

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

# Stop and remove the container (plain Docker)
docker stop vresto-dashboard && docker rm vresto-dashboard

Quick Start

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

Installation

From PyPI (recommended for users):

pip install vresto

For development:

git clone https://github.com/kalfasyan/vresto.git
cd vresto
uv sync

Configuration

Configure your credentials (see Setup Guide for details):

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:

python scripts/setup_credentials.py

Note (pip install users): scripts/setup_credentials.py is only available in the cloned repo. If you installed via pip install vresto, use the export commands above or manually create a .env file in your working directory based on the template.

Launch the App

If you installed from PyPI and your Python scripts directory is on your PATH, run:

vresto

If you are developing from a cloned repository, run through the project environment:

# Either with uv
uv run vresto

# Or with pixi
pixi run vresto

# Or via Makefile
make app

If you get command not found: vresto, the console script is not on your shell PATH yet. Use pixi run vresto / uv run vresto, or install and activate a virtual environment where vresto is installed.

Local (non-Docker) runs open on http://localhost:8080 by default. Docker runs open on http://localhost:8610.

Alternative methods:

# Or directly with Python
python src/vresto/ui/app.py

Command-Line Interface (CLI):

Quick searches and downloads from the terminal:

# 🔍 Search for products
vresto-cli search-name "S2A_MSIL2A_20200612" --max-results 5

# 📸 Download quicklook (preview image)
vresto-cli download-quicklook "S2A_MSIL2A_20200612T023601_N0500_R089_T50NKJ_20230327T190018" --output ./quicklooks

# 📋 Download metadata
vresto-cli download-metadata "S2A_MSIL2A_20200612T023601_N0500_R089_T50NKJ_20230327T190018" --output ./metadata

# 🎨 Download specific bands
vresto-cli download-bands "S2A_MSIL2A_20200612T023601_N0500_R089_T50NKJ_20230327T190018" "B04,B03,B02" --resolution 10 --output ./data

For complete CLI documentation, see the CLI Guide.

API usage:

Get started with just a few lines of Python:

from vresto.api import CatalogSearch, CopernicusConfig
from vresto.products import ProductsManager

# Initialize
config = CopernicusConfig()
catalog = CatalogSearch(config=config)
manager = ProductsManager(config=config)

# 🔍 Search for a product by name
products = catalog.search_products_by_name("S2A_MSIL2A", max_results=5)

# 📸 Download quicklook and metadata
for product in products:
    quicklook = manager.get_quicklook(product)
    metadata = manager.get_metadata(product)
    if quicklook:
        quicklook.save_to_file(f"{product.name}.jpg")

# 🎨 Download specific bands for analysis/visualization
manager.download_product_bands(
    product=products[0].name,
    bands=["B04", "B03", "B02"],  # Red, Green, Blue
    resolution=10,
    dest_dir="./data",
)

For more examples, see the examples/ directory and API Guide.

For detailed setup and usage, see the documentation below.

Documentation

📖 Full Documentation - Hosted on GitHub Pages

• Setup Guide ⭐ Start here - Installation, credentials setup, and configuration
• API Guide - Programmatic usage examples and reference
• AWS CLI Guide - Direct S3 access with AWS CLI
• Contributing - Development setup

Requirements

• Python 3.11+
• uv package manager (optional but recommended)

License

See LICENSE.txt