Setup and usage - geosolutions-it/digital-twin-toolbox GitHub Wiki

Prerequisites

A Docker instance installed on the selected working machine is needed in order to install and run this toolbox. From the official documentation Docker is described as an open platform for developing, shipping and running applications and it is possible to find documentaion on how setup Docker Engine at this link.

You can run it in any platform (e.g GNU/Linux, Windows, MacOS). The following installation process has been tested on Ubuntu 26.04 LTS (WSL) using Docker version 29.5.3

Quick start: Setup and Installation using Docker

The goal of this page is to instruct the users on how run the application locally in order to process assets and generate 3D Tiles dataset.

In order to move on, please clone the repository

[!NOTE] On Windows OS is important to clone the repository with the original line endings, in particular the .sh files needs to end with LF and not CRLF (see https://github.com/geosolutions-it/digital-twin-toolbox/issues/23)

git clone -c core.autocrlf=false https://github.com/geosolutions-it/digital-twin-toolbox

Navigate in the cloned digital-twin-toolbox repository

cd ./digital-twin-toolbox

Checkout to the latest release

git checkout v1.0.0-rc4

[!NOTE] Always check the latest published release at https://github.com/geosolutions-it/digital-twin-toolbox/releases and use that tag.

Create your local environment file by copying the provided template:

cp .env.copy .env

Start the application with

./scripts/compose.sh --workers vector,point-cloud -- up

After the docker containers are running is possible to access the client at: http://localhost

[!NOTE] The actual conversion of assets to 3D Tiles is performed by background workers. You need to start at least the worker that matches the data you want to process: vector for Shapefiles and point-cloud for LAS point clouds. Without a running worker the upload will succeed but no processing will happen.

The `compose.sh` helper

scripts/compose.sh is a thin wrapper around docker compose that selects the right set of compose files and starts the optional workers. Everything after -- is forwarded as-is to docker compose.

Usage: ./scripts/compose.sh [OPTIONS] -- DOCKER COMPOSE ARGS

Options:
  --prod              Run in production mode (exclude docker-compose.override.yml)
  --dev               Hot reload (mounted source) for the backend and the selected --workers
  --workers LIST      Comma-separated list of workers to include: vector, point-cloud
  -h, --help          Show this help and exit

Examples:

# Start the stack with the vector and point-cloud workers
./scripts/compose.sh --workers vector,point-cloud -- up

# Same, in detached mode
./scripts/compose.sh --workers vector,point-cloud -- up -d

# Development with hot reload - build once so the dev dependencies (watchfiles) are installed
./scripts/compose.sh --dev --workers vector,point-cloud -- up --build

# Stop and remove the stack
./scripts/compose.sh -- down

Build images locally

The command above pulls the latest images from the registry. If you want to build the frontend, backend and worker images locally run the following command: