bluegreencity-ki

Remote Development Setup Guide

This guide explains how to reproduce the remote-development workflow for the shared project workstation. It is written for publication and handover, so all workstation names, user names, and credentials are represented as placeholders.

Target Setup

Each contributor works in:

a personal operating-system account on the workstation
a personal clone of the repository
a shared PostGIS environment for common project data
a private local .env file for database access where needed

Prerequisites

Before starting, make sure you have:

access to the project VPN or private network
a workstation account provided by the administrator
VS Code installed locally
Git access to the repository

1. Connect to the Private Network

Install and configure the VPN or private-network client used by the project. Confirm that the workstation hostname resolves and is reachable before continuing.

Example test:

ping <workstation-hostname>

2. Install VS Code Remote SSH

Install the Microsoft Remote SSH extension in VS Code. This is the default access method because multiple contributors can work simultaneously without interfering with each other.

3. Configure SSH

Add a host entry to your local SSH configuration:

Host project-workstation
    HostName <workstation-hostname>
    User <your-username>

Then connect from VS Code through the command palette using Remote-SSH: Connect to Host.

4. Create Your Personal Project Clone

After connecting to the workstation, create a personal project folder and clone the repository there:

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\Projects"
Set-Location "$env:USERPROFILE\Projects"
git clone https://github.com/wanderfunke/bluegreencity-ki.git
Set-Location bluegreencity-ki

Recommended pattern:

one repository clone per user account
shared database, but isolated code workspaces
feature branches for non-trivial changes

5. Configure Local Environment Variables

If you need direct database access from Python, create a local .env file:

Copy-Item .env.example .env

Minimal structure:

POSTGIS_HOST=<database-hostname>
POSTGIS_PORT=5432
POSTGIS_DB=<database-name>
POSTGIS_USER=<database-user>
POSTGIS_PASSWORD=<database-password>

DATABASE_URL=postgresql://<database-user>:<url-encoded-password>@<database-hostname>:5432/<database-name>

Rules:

never commit the populated .env file
obtain credentials through an internal channel
keep passwords out of markdown guides and screenshots

6. Optional: Configure SSH Keys

Generate a key pair on your local machine if you want passwordless login:

ssh-keygen -t ed25519 -C "your.email@example.org"

Add the public key to the authorized key location required by the workstation policy. The exact location depends on whether the user account is standard or administrative on Windows.

General verification step:

ssh <your-username>@<workstation-hostname>

7. Optional: Remote Desktop

Use Remote Desktop only for tasks that truly require a full GUI session. Remote-SSH should remain the default development path.

Good reasons to use Remote Desktop:

GIS tasks that are difficult to perform headlessly
administrative troubleshooting
software configuration that cannot be done over SSH alone

Daily Workflow

Typical sequence:

connect to the private network
open VS Code
connect to project-workstation via Remote SSH
pull the latest changes
work in your own branch or agreed collaboration branch
commit and push regularly

Useful commands:

git pull origin main
git checkout -b feature/<short-name>
git status

Administrator Notes

Administrator tasks should be documented without embedding passwords directly in scripts.

Safer pattern for creating a Windows user interactively:

$Username = "newuser"
$FullName = "New User"
$Password = Read-Host "Enter a temporary password" -AsSecureString

New-LocalUser $Username -Password $Password -FullName $FullName -Description "Remote development account"
Add-LocalGroupMember -Group "Administrators" -Member $Username

If SSH keys are required for administrative Windows accounts, document the correct authorized-keys location in an internal admin note rather than distributing live workstation paths and account details publicly.

Security and Publication Notes

Use placeholders for hostnames, usernames, and service endpoints in published docs.
Never include actual passwords, even temporary ones, in examples.
Keep onboarding checklists and live connection details in internal-only material if they contain sensitive operational data.