v3.5.3
Open source presentation, controller, domain and service layers for spatial data and application interfaces.
The XYZ stack consists of several application layers.
The pattern for the Node domain and service layers are that of a RESTful API which provides secure gateways for spatial data sources and 3rd party service providers. The domain layer handles API routing, rewrites, and ressource caching while the service layer manages authentication and processes transaction script. URL parameter (and payloads) from the application control layer are assigned to query templates and passed to the data source layer. The response from the database connection pool is then parsed into JSON and returned to the presentation layer. The Node application layers may be served by an Express web server or deployed as serverless functions to the cloud.
Spatial data must be stored in a cloud accessible PostGIS database to allow for the creation and caching of vector tiles in the data source layer.
Application control and presentation layers are provided as an ES6 javscript library. XYZ' client library utilizes the Openlayers mapping engine among other visualisation libraries such as Tabulator and ChartJS to power engaging application views.
Please visit geolytix.github.io/xyz/docs for project documentation hosted from the development branch of this repository.
Application views are dashboards made up of multiple data views such as maps, tables, lists, or graphs. Build with markup and the XYZ control library, application views connect to XYZ hosts. The hosted API is capable of rendering templates and passing queries to the data source layer. Custom script may be added as tags to the DOM. This allows XYZ' application control to dispatch itself as well as functional objects such as layers and locations as event details to the custom script.
Views may be static sites requested from a CDN or server side rendered by the XYZ/views API.
XYZ' templating is a process of assigning configuration objects and parameter substitution. Templates may be text (e.g. HTML/SQL) to be rendered by the XYZ host and send as views to the presentation layer or passed as transaction script to the data source layer.
Environment settings contain sensitive information such as connection strings for data sources, secrets for the generation of token, and API keys for 3rd party service provider.
The workspace defines which layers, locations, and templates are available to the XYZ API. Transaction script must never be sent directly from the application control layer but needs to be rendered from script and query templates provided by the workspace. Roles may be assigned to the configuration objects in the XYZ workspace.
The XYZ API may be deployed as an Express web server (used for local debugging). For production we recommended to deploy the XYZ host as serverless functions to Vercell's (former Zeit) Now platform. XYZ' API is designed to fall within the function handler and memory limit which qualify for the free Hobby plan.
Configurations and ressources may either be deployed with the application code from a local repository or stored in Github repositories. Private repositories are now freely available to everyone. XYZ workspaces must not contain sensitive information and may therefore be stored in a public repository. A Github API token in the environment settings allows the XYZ host access to private repositories.
Access to the API can be secured with signed JWT. Token may be provided as URL parameter or with a cookie. User accounts can be stored in a PostgreSQL Access Control List (ACL). Administrative and functional roles can be assigned to registered user accounts. Roles define the level of access to connected data sources. The security strategy also supports the issue of API keys which may be revoked and do not provide access to any sensitive administrative tasks.
The XYZ/location API provides the ability to create, delete and update locations on configured PostGIS layers. The application control library provides utilities to digitize geometries in a Openlayers map view. Ressources such as documents and images may be uploaded to Cloudinary with links being sent as properties for a location update query.
SQL script templates are provided as default for the presentation of clustered data views.
The XYZ service layer is capable to generate and cache vector tiles in connected PostGIS data sources.
The domain and service layer may secure proxy access for services provided by Google Maps, Mapbox, MapTiler, Bing, Cludinary, or Here.
Openlayers - High-performance web mapping engine.
jsonwebtoken - A Node implementation of JSON Web Token.
bcryptjs - Optimized bcrypt in JavaScript with zero dependencies.
Node-Postgres - PostgreSQL client for Node.
Express - Fast, unopinionated, minimalist web framework for Node.
µhtml - A micro HTML/SVG render.
chart.js - For the creation of HTML canvas charts in info panels and report views.
tabulator - Javascript library for interactive tables and data grids.
flatpickr - A customisable JavaScript datetime picker.
chroma.js - A JavaScript library for all kinds of color manipulations.
TurfJS - A modular geospatial engine for geometry aggregation and transformations in the middleware and on the client side.
lodash - A modern JavaScript utility library delivering modularity, performance, & extras.
nodemailer - Send e-mails with Node – easy as cake!
node-fetch - A light-weight module that brings window.fetch to Node.
a-color-picker - a color picker for web app.
THe purpose of this is to provide the ability to run the XYZ docker container locally via an SSH tunnel and it'll be able to connect to the new RDS database.
- Run the docker command below if the XYZ docker image have not been built.
# Set vars for AWS ECR repository
AWS_ACCOUNT_ID=695431195173
AWS_REGION=eu-west-2
AWS_ECR_REPO=map
AWS_ECR_URI=${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/${AWS_ECR_REPO}:latest
# Build XYZ docker image
docker build -t ${AWS_ECR_URI} . --network=host
# Login to ECR
aws ecr get-login-password --region ${AWS_REGION} | docker login --username AWS --password-stdin ${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com
# Push the XYZ image to docker repo
docker push ${AWS_ECR_URI}- Create an SSH tunnel to connect to the new RDS database via Bastion Host.
# Unpopulated command
ssh -L [LOCAL_IP:]LOCAL_PORT:DESTINATION:DESTINATION_PORT [USER@]SSH_SERVER -i [BASTION_HOST_PEM_CER_FILE]
# Example
ssh -L 0.0.0.0:5432:postgres-rds-private-eu-west-2.ct36hfcslmg5.eu-west-2.rds.amazonaws.com:5432 [email protected] -i ./commonplace-bastion.cer- Run the XYZ container via SSH tunnel. NOTE: Please run the docker command as root.
# Run docker container with --network=host flag
sudo docker run --network=host -p 3000:3000 --rm -it <image_name_repo_name>:<tag>THe purpose of this is to provide the ability to run the XYZ docker container locally via an SSH tunnel and it'll be able to connect to the new RDS database.
- Run the docker command below if the XYZ docker image have not been built.
# Switch AWS profile to prodAdministratorAccess
AWS_PROFILE=cp_role
# Set vars for AWS ECR repository
AWS_ACCOUNT_ID=695431195173
AWS_REGION=eu-west-2
AWS_ECR_REPO=map
AWS_ECR_URI=${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/${AWS_ECR_REPO}:latest
# Build XYZ docker image
docker build -t ${AWS_ECR_URI} . --network=host
# Login to ECR
aws ecr get-login-password --region ${AWS_REGION} | docker login --username AWS --password-stdin ${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com
# Push the XYZ image to docker repo
docker push ${AWS_ECR_URI}- Clone down foundations and deploy
git clone https://github.com/Commonplace-Digital-Ltd/foundations
cd foundations
git checkout main
git pull
# Swap out DUMMY values for passwords for mongo/postgres, see AWS Secrets Manager acorn/geolytix
helm upgrade map ./charts/generic --values ./charts/map/values-override.yaml --create-namespace --install --namespace default --set env.MONGO_URL='mongodb+srv://acorn:[email protected]?retryWrites=true&w=majority' --set env.DBS_XYZ='postgres://postgres:DUMMY@postgres-rds-private-eu-west-2.ct36hfcslmg5.eu-west-2.rds.amazonaws.com:5432/postgres'Free use of the code in this repository is allowed through a MIT license.
BrowserStack supports this OpenSource project, providing us with valuable tools to test the XYZ client on different platforms.