Installer

This page tracks the current backend installation flow in core-stack-backend/installation.

The backend now uses a three-part path:

1. clone the repo and open a Linux shell
2. run installation/install.sh
3. review nrm_app/.env, optional credentials, and the installer validation output

Primary sources:

• installation/install.sh
• installation/INSTALLATION.md
• computing/misc/internal_api_initialisation_test.py

---

Before You Run It

• Linux is the main target.
• Windows users should use WSL2 and run the installer from the Linux path such as /mnt/y/....
• You need sudo, internet access, and enough disk for the admin-boundary dataset download.
• The current backend assumes PostgreSQL 15+, RabbitMQ, and Python via Miniconda.

If you are starting from a fresh machine, the usual baseline packages are:

sudo apt update
sudo apt install -y git wget curl build-essential libpq-dev rabbitmq-server unzip

install.sh installs and configures most runtime dependencies itself.

---

Review The Installer Defaults

Variable	Default	Meaning
MINICONDA_DIR	$HOME/miniconda3	Miniconda install path
CONDA_ENV_NAME	corestackenv	Conda environment name
BACKEND_DIR	derived from the repo root	active backend checkout
APP_ENV_FILE	nrm_app/.env	single runtime env file
POSTGRES_USER	corestack_admin	local PostgreSQL user
POSTGRES_DB	corestack_db	local PostgreSQL database
POSTGRES_PASSWORD	corestack@123	local PostgreSQL password
DEFAULT_PUBLIC_API_BASE_URL	https://geoserver.core-stack.org/api/v1	public API smoke-test base URL

---

Run The Installer

Existing checkoutFresh clone

cd /mnt/y/core-stack-org/core-stack-backend/installation
chmod +x install.sh
./install.sh

git clone https://github.com/core-stack-org/core-stack-backend.git
cd core-stack-backend/installation
chmod +x install.sh
./install.sh

---

Targeted Reruns And Optional Inputs

The installer now supports step selection and queued optional inputs directly. The examples below assume you are in the backend repo root.

Useful rerun patterns:

# Continue from a later point
bash installation/install.sh --from gee_configuration

# Only rerun validation
bash installation/install.sh --only initialisation_check

# Skip the large admin-boundary download on a partial rerun while starting the installation from env_file step.
bash installation/install.sh --from env_file --skip admin_boundary_data

Useful optional-input patterns:

# Import a GEE service-account JSON during the GEE step
bash installation/install.sh --gee-json /full/path/to/service-account.json

# Provide the same GEE path through the generic input mechanism
bash installation/install.sh --input gee_json=/full/path/to/service-account.json

# Configure public API smoke-test credentials
bash installation/install.sh \
  --input public_api_key=your-public-api-key \
  --input public_api_base_url=https://geoserver.core-stack.org/api/v1

# Configure GeoServer publish validation
bash installation/install.sh \
  --input geoserver_url=https://host/geoserver \
  --input geoserver_username=admin \
  --input geoserver_password=your-password

Supported optional input keys in the current installer:

• gee_json
• public_api_key
• public_api_base_url
• geoserver_url
• geoserver_username
• geoserver_password

---

What The Installer Automatically Sets Up

• Miniconda installation
• conda environment creation from installation/environment.yml
• PostgreSQL installation and database/user setup
• RabbitMQ installation and service startup
• nrm_app/.env creation
• collectstatic
• Django migrations
• seed data loading from installation/seed/seed_data.json
• creation or refresh of an installer test superuser
• optional GEE JSON staging into data/gee_confs/ plus GEEAccount import
• admin-boundary dataset download or normalization into data/admin-boundary/
• in-process backend validation via computing/misc/internal_api_initialisation_test.py
• optional public API smoke testing via installation/public_api_client.py

Two details matter operationally:

• The installer-created superuser is a test account shaped like test_user_#### with password test_change_me.
• The installer uses nrm_app/.env as the runtime source of truth.

---

What You Still Need To Review

Review or fill the environment-specific values that depend on your deployment:

• GEOSERVER_URL, GEOSERVER_USERNAME, GEOSERVER_PASSWORD
• PUBLIC_API_X_API_KEY and, if needed, PUBLIC_API_BASE_URL
• GEE_DEFAULT_ACCOUNT_ID, GEE_HELPER_ACCOUNT_ID, and the GEE key-path variables if you skipped GEE import during install
• S3, DPR S3, ODK, email, and similar service secrets only when your workflow actually uses them

Review the test superuser

The installer ensures an active Django superuser exists so it can generate JWTs automatically during validation.

If you plan to keep using that account beyond setup checks, change its password or create your own operator account:

source "$HOME/miniconda3/etc/profile.d/conda.sh"
conda activate corestackenv
python manage.py createsuperuser

---

Understand The Built-In Validation

install.sh now performs the first serious backend verification itself.

The initialisation_check step runs Django in-process and does not require runserver or a separate Celery worker. It checks:

• database connectivity
• key env values from nrm_app/.env
• automatic JWT generation from an active Django user
• GEE authentication if GEE_DEFAULT_ACCOUNT_ID is configured
• GCS upload access for the same GEE service account
• GeoServer REST reachability if GeoServer credentials are configured
• local admin-boundary compute artifact generation
• POST /api/v1/generate_block_layer/ in Celery eager mode when GEE, GCS, and GeoServer are ready
• route import and a curated endpoint probe set

To rerun the validation manually:

source "$HOME/miniconda3/etc/profile.d/conda.sh"
conda activate corestackenv
cd /path/to/core-stack-backend
python computing/misc/internal_api_initialisation_test.py
python computing/misc/internal_api_initialisation_test.py --require-gee

If PUBLIC_API_X_API_KEY is configured, the installer can also run the public API smoke test:

bash installation/install.sh --only public_api_check

---

Start The App Manually

Once the installer and checks are done, the usual development runtime is uses two terminal runs.

Terminal 1

source "$HOME/miniconda3/etc/profile.d/conda.sh"
conda activate corestackenv
python manage.py runserver 127.0.0.1:8000

Terminal 2

source "$HOME/miniconda3/etc/profile.d/conda.sh"
conda activate corestackenv
cd /path/to/core-stack-backend
celery -A nrm_app worker -l info -Q nrm

---

What To Do Next

If installation passed, continue in this order:

1. read the validation output and clear any remaining warnings that matter for your workflow
2. configure the integrations you actually need
3. trace one real request path
4. then move into pipeline development

The most useful next pages are Setup Troubleshooting, Integrations, First Manual API Run, and Backend Code Map.