Skip to main content

​
Prerequisites

Before getting started, ensure you have the following installed:
  • Docker & Docker Compose: Version 20.10 or later
  • Git: For cloning the repository
  • At least 4GB RAM: Recommended for running all services
  • Node.js 18+ (optional, for development)

​
Clone the Repository

git clone https://github.com/qs-geoflow/geoflow.git
cd geoflow

​
Quick Start with Docker

The fastest way to get GeoFlow running is using Docker Compose. This will start all services with default configurations. 
# Start all services
docker compose up -d

# Or start only essential services for development
docker compose up geoflow-worker postgres geoflow-convex-backend geoflow-convex-dashboard mcp geoflow-motia -d
The first startup may take several minutes as Docker builds the images and initializes the database.

​
Access GeoFlow

Once all services are running, you can access:

​
Verify Installation

Check that all services are running: 
docker compose ps
You should see all services with status “Up”: 
NAME                    STATUS
geoflow-convex-backend    Up (healthy)
geoflow-convex-dashboard  Up
geoflow-motia            Up
geoflow-worker           Up
mcp                      Up (healthy)
postgres                 Up (healthy)

​
Test Basic Functionality

  1. Open http://localhost:3000 in your browser
  2. Create a new workflow
  3. Upload some geospatial data (optional test file available in storage/data/)
  4. Run a simple processing workflow

​
Next Steps

Complete Installation

Learn about production deployment and configuration options

Architecture Overview

Understand how GeoFlow services work together

​
Troubleshooting

​
Common Issues

Port conflicts: If ports 3000, 3210, or 5432 are already in use, stop conflicting services or modify the docker-compose.yml file. Memory issues: If containers crash due to insufficient memory, increase Docker’s memory limit or reduce concurrent services. Database connection: Ensure PostgreSQL container is healthy before starting other services.

​
Logs and Debugging

View logs for specific services: 
# View all logs
docker compose logs

# View logs for a specific service
docker compose logs geoflow-convex-backend

# Follow logs in real-time
docker compose logs -f geoflow-worker

​
Reset Everything

To start fresh: 
# Stop all services
docker compose down

# Remove volumes (WARNING: This deletes all data)
docker compose down -v

# Rebuild and restart
docker compose up --build -d