The infDB is a user-friendly, platform-independent, and open-source data infrastructure as a foundation for energy system analyses. It enables complex evaluations by combining various tools through standardized interfaces, fostering an open and interoperable ecosystem.
| Category | Badges |
|---|---|
| License |  |
| Documentation |  |
| Development |     |
| Community |    |
infDB (Infrastructure Database) offers a flexible and easy-to-configure data infrastructure with essential services, minimizing the effort required for data management. By providing standardized interfaces and APIs, infDB streamlines collaboration in energy modeling and analysis, enabling users to focus on insights rather than data handling.
For instance, it can be used for the following applications:
- Energy System Modeling
- Infrastructure Planning
- Scenario Analysis
- Geospatial Analysis
The infDB architecture is composed of three coordinated layers as shown in the figure below:
- 3D City Database – foundational geospatial and semantic building data (center)
- Services – preconfigured platform services (top)
- Tools – external connected software and scripts. (right)
The 3D City Database is the basis and extended by services and tools. More information of each layer is described below.
The 3D City Database and all services are dockerized for a modular and flexible application.
The 3D City Database is developed by the Chair of Geoinformatics at Technical University of Munich (TUM) and the basis for infDB. It is a solution for managing, analyzing, and utilizing virtual 3D city models on top of a spatial database system. More information on http://www.3dcitydb.org/
Integrated, preconfigured services extending the 3D City Database:
- TimescaleDB: Scalable time-series storage (weather, load, generation) with hypertables, compression, optional continuous aggregates.
- pgAdmin: Web UI for inspecting schemas, running SQL, managing roles; auto-configured credentials.
- FastAPI: REST endpoints (/city, /weather) with OpenAPI docs and validated access to 3D, geospatial, and time-series data.
- Jupyter: Notebook environment (dependencies and env vars preloaded) for exploratory queries, ETL prototypes, reproducible analysis.
- QWC2: Web mapping client for 2D/3D visualization, layer styling, spatial inspection, quick dataset validation.
- PostgREST: Auto-generated REST API over PostgreSQL schemas (tables, views, RPC) using DB roles for auth; rapid, lightweight data access without extra backend code.
- pygeoapi: OGC API (Features/Coverages/Processes) server exposing PostGIS data via standards-based JSON & HTML endpoints for interoperable geospatial discovery and querying.
These services provide core functionalities and support a seamless path from ingestion to analysis and visualization.
Tools are external software that is already adopted to the infDB.
Currently integrated tools include:
- infDB-loader: Containerized automated loading public open data for Germany
- infDB-processor: Containerized data transformation and enrichment
- pylovo: Tool for generating synthetic low-voltage distribution grids
More community or domain-specific tools can be attached through the standardized APIs and database schemas.
To get started, follow these steps below. For more information in detail read the https://infdb.readthedocs.io/.
If you are happy with the preconfiguration and default passwords, then just follow these four steps (see detailed instructions in the corresponding sections below):
- Clone infDB
- Setup infDB
- Run infDB
- Optional: Run infDB-loader
The folder structure of the infdb as shown is recommend since all of the data of all instances are stored in 'data' automatically by default:
- infdb
- data
- instance1
- ...
- instanceN
# linux
mkdir infdb
cd infdb# ssh
# Replace "demo" by name of instance
git clone git@gitlab.lrz.de:tum-ens/need/infdb.git demo
# https
# Replace "demo" by name of instance
git clone https://gitlab.lrz.de/tum-ens/need/infdb.git demo
# Change directory into repo
cd demoThe configuration can be done via configs/config-infdb.yml
base:
name: demo
path:
base: "../data/{base/name}/"
network_name: "infdb-{base/name}_network"
services:
citydb:
user: citydb_user
password: infdb
db: citydb
host: citydb
exposed_port: 5432
epsg: 25832 # 3035 (Europe)
path:
base: "{base/path/base}/{base/name}/citydb/"
compose_file: "services/3dcitydb/compose.yml"
status: active
...After doing the configuration you need to generate the configurations files with the following command:
# on linux and macos
docker compose -f services/setup/compose.yml up
# on windowsOnce you generated the configuration files with the command above, you need to finally start the infDB:
# on linux and macos
docker compose -f compose.yml up -d
# on windowsThe infDB will be run as long as you stop it manually as described below even when the machine is restarted.
Hint: If compose.yml is not found, you either forgot to run the command above or something went wrong. Please check the logs of the setup service.
Hint: The infDB will be run as long as you stop it manually as described below even when the machine is restarted.
# on linux and macos
docker compose -f compose.yml down -v
# on windowsThe configuration can be done via configs/config-loader.yml
loader:
name: demo-sonthofen
scope: # AGS (Amtlicher Gemeindeschlüssel)
# - 09162000 # Munich
- "09780139" # Sonthofen
# - "09780116" # Bolsterlang
# - "09162000" # M
# - "09185149" # ND
# - "09474126" # FO
# - "09261000" # LA
multiproccesing:
status: active
max_cores: 4 # max cores since of memory limitations to 2
config-infdb: "config-infdb.yml" # only filename - change path in ".env" file "CONFIG_INFDB_PATH"
path:
base: "data" # only foldername - change path in ".env" file "LOADER_DATA_PATH"
opendata: "{loader/path/base}/opendata/"
processed: "{loader/path/base}/{loader/name}"
logging:
path: "{loader/path/base}/loader.log"
level: "DEBUG" # ERROR, WARNING, INFO, DEBUG
hosts:
citydb:
user: None
password: None
db: None
host: None
exposed_port: None
epsg: None # 3035 (Europe)
timescaledb:
user: None
password: None
db: None
host: None
exposed_port: None
sources:
package:
status: active
url: http://ds1.need.energy:8123/opendata.zip
path:
base: "{loader/path/base}"
processed: "{loader/path/opendata}"
lod2:
status: not-active
url:
- "https://geodaten.bayern.de/odd/a/lod2/citygml/meta/metalink/#scope.meta4" #scope placeholder for AGS
path:
lod2: "{loader/path/opendata}/lod2/"
gml: "{loader/path/opendata}/lod2/{loader/name}"
...Hint: In case you move the infdb-loader source folder outside of the folder tools in repo or want to change the location where the downloaded data is stored, the paths to data and to configs folder need to be defined in .env
CONFIG_INFDB_PATH=../infdb/configs # Change if you moved the "configs" folder
LOADER_DATA_PATH=./ # Change if you moved the "data" folderOnce you adjusted the configuration files with the command above, you need to finally start the infDB-loader and start importing:
# on linux and macos
docker compose -f tools/infdb-loader/compose.yml up
# on windows# on linux and macos
docker compose -f tools/infdb-preprocessor/compose.yml up
# on windows# on linux and macos
docker run --rm --add-host=host.docker.internal:host-gateway 3dcitydb/citydb-tool delete --delete-mode=delete -H host.docker.internal -d citydb -u citydb_user -p citydb_password -P 5432
# on windows# on linux and macos
PGPASSWORD='citydb_password' psql -h localhost -p 5432 -U citydb_user -d citydb
# on windows.pg_service.conf for QGIS to connect to InfDB via service
[infdb]
host=localhost
port=5432
dbname=citydb
user=citydb_user
password=citydb_password
sslmode=disable
# on linux and macos by installation script
curl -LsSf https://astral.sh/uv/install.sh | sh
# or by pip
pip install uv# linux and macos
uv sync# linux and macos
source .venv/bin/activate
# windows
venv\Scripts\activate# linux and macos
git fetch origin
git reset --hard origin/develop
git clean -fdx
# windows- src/: Main application package
- api/: API endpoints (cityRouter.py, weatherRouter.py)
- core/: Core application code (dbConfig.py, etc.)
- db/: Database models and repositories
- models/: SQLModel classes for database entities
- repositories/: Data access layer for database operations
- exceptions/: Custom exception classes
- externals/: External API integrations (e.g., weather API)
- schemas/: Data schemas and validation
- services/: Business logic services
- main.py: Application entry point
- docs/: Documentation
- architecture/: System architecture documentation
- contributing/: Contribution guidelines and code of conduct
- development/: Developer guides and workflows
- guidelines/: Project guidelines and standards
- operations/: Operational guides and CI/CD documentation
- source/: Source files for documentation
- img/: Images used in documentation
- dockers/: Docker configuration files
- tests/: Test suite
- unit/: Unit tests for individual components
- integration/: Tests for component interactions
- e2e/: End-to-end tests for the application
- conftest.py: Pytest configuration and fixtures
- Set up the environment following the installation instructions.
- Open an issue to discuss new features, bugs, or changes.
- Create a new branch for each feature or bug fix based on an issue.
- Implement the changes following the coding guidelines.
- Write tests for new functionality or bug fixes.
- Run tests to ensure the code works as expected.
- Create a merge request to integrate your changes.
- Address review comments and update your code as needed.
- Merge the changes after approval.
The CI/CD workflow is set up using GitLab CI/CD. The workflow runs tests, checks code style, and builds the documentation on every push to the repository. You can view workflow results directly in the repository's CI/CD section. For detailed information about the CI/CD workflow, see the CI/CD Guide.
The following resources are available to help developers understand and contribute to the project:
The Coding Guidelines document outlines the coding standards and best practices for the project. Start here when trying to understand the project as a developer.
The Architecture Documentation provides an overview of the system architecture, including the database schema, components, and integration points.
- Development Setup Guide: Comprehensive instructions for setting up a development environment
- Contribution Workflow: Step-by-step process for contributing to the project
- API Development Guide: Information for developers who want to use or extend the API
- Database Schema Documentation: Detailed information about the database schema
- Contributing Guide: Guidelines for contributing to the project
- Code of Conduct: Community standards and expectations
- Release Procedure: Process for creating new releases
- CI/CD Guide: Detailed information about the CI/CD workflow
Everyone is invited to develop this repository with good intentions. Please follow the workflow described in the CONTRIBUTING.md.
This repository follows consistent coding styles. Refer to CONTRIBUTING.md and the Coding Guidelines for detailed standards.
Pre-commit hooks are configured to check code quality before commits, helping enforce standards.
The changelog is maintained in the CHANGELOG.md file. It lists all changes made to the repository. Follow instructions there to document any updates.
The code of this repository is licensed under the MIT License (MIT).
See LICENSE for rights and obligations.
See the Cite this repository function or CITATION.cff for citation of this repository.
Copyright: TU Munich - ENS | MIT