Pre-requisites
The following section assumes you have installed all the tools required for web development from our tools section.
Before you move on, it is also mandatory that you read through the key technology list in our web technologies section and you understand the justification for each one, especially if you're not familiar with the specific technology.
It is presumed that you already have a Web Base prepared and ready for you install modlets, otherwise, please go to the
Web Framework quickstart section to initialize your
Web Base.
It is also presumed that you are already familiar with running a local development environment, otherwise, please go to the Local Dev Environment to prepare your machine for local development.
Installation
1. CLI tool installation of GIS Modlet
Run the following command in the root of the Web Base folder.
npx cli install @mssfoobar/gis-console
You'll then be prompted to choose your 'root folder', use the default (current working directory).
The modlet will be installed, with the appropriate files being copied over, and dependencies will be added and copied into your package.json.
2. Manual steps
The installation steps are still a work in progress, future versions of the modlet will shift all manual steps into the CLI tool.
2.1 Add the following properties to your .env file
These default values will work if you're using 127.0.0.1.nip.io for development, otherwise, change them accordingly.
The specifics for what each environment variable does can be found in the
configuration section.
...
## ==================== GIS ====================
## The URL to the GIS backend service
GIS_URL=http://gis.127.0.0.1.nip.io
## The URL to the RTUS Server Sent Events service
PUBLIC_RTUS_SEH_URL=http://rtus-seh.127.0.0.1.nip.io
## The name of the distributed map to connect to in RTUS
PUBLIC_GIS_RTUS_MAP_NAME=gis
2.2 Update Vite Configuration
In order to properly import Cesium, Vite requires additional configuration to copy some required files out from Cesium's
node_modules package, as well as an additional CESIUM_BASE_URL variable definition that can be accessed by
JavaScript on the browser.
First, install vite-plugin-static-copy:
npm install -D vite-plugin-static-copy@^1.0.6
Then, modify the vite.config.ts file to include 4 necessary folders for Cesium to work properly, as well as the
additional CESIUM_BASE_URL definition:
import { normalizePath, searchForWorkspaceRoot } from "vite";
import { viteStaticCopy } from "vite-plugin-static-copy";
const cesium = `${normalizePath(searchForWorkspaceRoot(__dirname))}/node_modules/@cesium`;
const cesiumBaseUrl = "cesium";
import { sveltekit } from "@sveltejs/kit/vite";
import { defineConfig, configDefaults } from "vitest/config";
export default defineConfig({
plugins: [
sveltekit(),
viteStaticCopy({
targets: [
{ src: `${cesium}/engine/Build/Workers`, dest: `${cesiumBaseUrl}` },
{ src: `${cesium}/engine/Source/Assets`, dest: `${cesiumBaseUrl}` },
{ src: `${cesium}/engine/Source/ThirdParty`, dest: `${cesiumBaseUrl}` },
{ src: `${cesium}/widgets/Source`, dest: `${cesiumBaseUrl}` },
],
}),
],
test: {
include: ["src/**/*.{test,spec}.{js,ts}"],
exclude: [...configDefaults.exclude, "src/lib/aoh/core/components/ui/*.ts"],
},
build: {
outDir: "build",
},
server: {
allowedHosts: [".localhost", ".127.0.0.1.nip.io"],
},
define: {
CESIUM_BASE_URL: JSON.stringify("/" + cesiumBaseUrl),
},
});
2.3 Install additional dependencies
The following additional dependencies, used by some GIS modlet components (that uses shadcn-svelte patterns)
requires zod (for validation), formsnap, and sveltekit-superforms.
npm install zod formsnap sveltekit-superforms
3. Run the local environment required for GIS development
podman compose --env-file .env -f gis/compose.yml up -d
Remeber to adjust and add the compose.override.yml if you're using Docker, or have other requirements like exposing
the database for direct connection from database management tool.
4. Start the development server
npm run dev