Full installation¶

How do I run a full installation on my own infrastructure?¶

This guide targets an infrastructure administrator responsible for putting the DSP in production, migrating real data from an organization (the "adopter").

Infrastructure requirements¶

Installation flow¶

flowchart LR
  r["Step 1<br/>Organize repositories"] --> e["Step 2<br/>Enter dsp-core"]
  e --> a["Step 3<br/>./config.sh (wizard)"]
  a --> b["generates adopter-config.yaml<br/>and operational files"]
  b --> c["Step 4<br/>./setup.sh (option 2)"]
  c --> d["Step 5<br/>./start.sh — start stack"]

Step 1 — Organize repositories¶

The DSP is split into sibling repositories on GitHub. We recommend creating a dsp folder and cloning everything at the same level.

The scripts look for each module in this order: first the short folder (backend, frontend, job-data-migration, job-geo-file-generation) and, if the code is not there, the folder named after the repository (dsp-backend, dsp-frontend, dsp-job-data-migration, dsp-job-geo-file-generation). When both are missing, the automatic download creates the repository-named folder. Automatic publishing in CI keeps using the short folder.

Option A — simplest flow (recommended)¶

Create the folder, clone only the core, and enter it. The ./config.sh, ./setup.sh, and ./start.sh scripts detect missing sibling repositories and offer to clone them automatically next to the core:

mkdir dsp && cd dsp
git clone https://github.com/Rural-Environmental-Registry/dsp-core.git
cd dsp-core

After you accept automatic cloning in the scripts, the typical tree looks like this:

dsp/
├── dsp-core/          ← you work here (config.sh, setup.sh, start.sh)
├── dsp-backend/
├── dsp-frontend/
├── dsp-job-data-migration/
└── dsp-job-geo-file-generation/

Option B — manual clone¶

Clone all application repositories as sibling folders inside dsp:

mkdir dsp && cd dsp
git clone https://github.com/Rural-Environmental-Registry/dsp-core.git
git clone https://github.com/Rural-Environmental-Registry/dsp-backend.git
git clone https://github.com/Rural-Environmental-Registry/dsp-frontend.git
git clone https://github.com/Rural-Environmental-Registry/dsp-job-data-migration.git
git clone https://github.com/Rural-Environmental-Registry/dsp-job-geo-file-generation.git

Result:

dsp/
├── dsp-core/
├── dsp-backend/
├── dsp-frontend/
├── dsp-job-data-migration/
└── dsp-job-geo-file-generation/

Step 2 — Enter the core¶

If you are not already inside the core:

cd dsp/dsp-core

You do not need to create or copy .env manually. The file is generated automatically on first run of ./config.sh or ./setup.sh, from .env.example, when it does not exist yet.

Step 3 — ./config.sh¶

The person running the script is guided by questions in the terminal: at each stage the wizard explains the field, where the value is used, and shows the default or saved value (Enter keeps what is in brackets). This way you can configure everything the adopter needs — data source, ETL, text, map, KPIs, and customize the UI without editing JSON/YAML by hand.

The flow has 6 guided steps (the last, About, is optional):

./config.sh writes the adopter source of truth to config/adopter/adopter-config.yaml — this is the file meant for manual editing or importing ready YAML. On reapply (wizard or option 1 — Reapply), ./config.sh generates operational files consumed by backend, GeoServers, and jobs. Do not edit those operational files by hand: they are overwritten on every ./config.sh.

Without the wizard: copy a ready adopter-config.yaml to config/adopter/ (use .example as reference) or edit only that YAML. The DSP does not read the adopter at runtime — backend, GeoServers, and jobs use generated JSON/YAML.

Step 4 — ./setup.sh¶

On Step 3 — Setup mode, choose:

• Option 1 — Demonstration (see also Quick start):
• Loads sample data (simplified Brazil map) into local databases.
• Starts databases, applies seed, and publishes map layers on both GeoServers.
• Does not connect to your organization's database and does not enable background import jobs.

• At the end, indicates running ./start.sh to open the site and API.

• Option 2 — Real adopter (organization data): requires ./config.sh first. The script checks that import configuration is ready and asks how source data will change over time (English text in the terminal: How will your source data be updated over time?):

At the end of the real flow, setup saves chosen schedules in the .env file. Running ./setup.sh again with option 2 repeats the questions, using what is already saved as default.

• Option 3 — Stack status / cleanup / exit:
• Lists project container status and known URLs.
• Optionally removes containers, volumes, and images for this project (explicit confirmation).
• Does not run seed, migration, or start backend/frontend.

Step 5 — ./start.sh¶

Used after ./setup.sh, with databases, GeoServers, and jobs (when present) already running. ./start.sh starts only the site, API, and HTTP entry point — it does not import data again or republish layers. Import and demo stay in ./setup.sh or schedules saved in setup.

At the end, open http://localhost:8026/dsp/ in the browser (or the URL ./start.sh shows if you changed port or address in .env).

Full detail for each option and sub-flow: dsp-core.

Next steps¶