Getting started

On Local

Git and Node.js must be installed on your locale to get started.

Clone the repository

You will only require the main branch unless you want to dig into the XYZ development legacy.

git clone https://github.com/GEOLYTIX/xyz --branch main --single-branch xyz-main

Install node modules

Step into the repository root and run the npm install command to install all node module dependencies.

npm install

Build the library

The mapp and ui library must be build. Esbuild will be installed from npm in the previous step. The build script is defined as _build in the package.json and can be executed with npm.

npm run _build

Hello OSM!

Express.js will be installed by npm as a development dependency. You can now run a zero config instance by loading the express.js script in your node runtime.

node express.js

The default port is 3000. You can access the mapp interface in your browser on localhost:3000.

You can prefix the node runtime command with environment variables like so.

PORT=3001 DIR="/hello" TITLE="Hello OSM!" node express.js

The test instance is now accessible on localhost:3001/hello. The TITLE environment variable value will provided to the application view.

The dotenv package is installed as a dev dependency. The express.js script will look for an .env file and assign the environment variables from this file to the node process.

VSCODE

Personally I work almost exclusively with VSCODE. You can open the cloned repository folder in VSCODE and create a launch file to customize run and debug. Chose the node.js debugger for your launch.json.

Update program to "${workspaceFolder}/express.js" and configure you environment variables before launching a local debug instance.

Creating a workspace

bit.io

We recommend bit.io to get started with Postgis in the cloud. Bit.io currently offers a free tier with 3 databases with 3GB storage. Databases can either be private or public. You are welcome to use my public test database to have a look at some of the sample datasets for XYZ/MAPP.

You will need to create the Postgis extensin to enable spatial features.

CREATE EXTENSION POSTGIS;

In order to connect to the database from the XYZ host you will need to copy the connection string from the connection tab.

Add ?sslmode=require to the connection string and add the string as a DBS_* connection to the environment variables like so:

The password has been replaced with ***

DBS_BIT: "postgresql://dbauszus:***@db.bit.io:5432/dbauszus/mapp?sslmode=require"

Adding an empty editable dataset

CREATE TABLE IF NOT EXISTS scratch
(
   id SERIAL,
   char_field character varying,
   textarea text,
   numeric_field numeric,
   integer_field integer,
   json_field json,
   bool_field boolean,
   datetime_integer integer,
   images text[] DEFAULT '{}'::text[],
   documents text[] DEFAULT '{}'::text[],
   geom_3857 geometry
);

CREATE INDEX IF NOT EXISTS scratch_geom_3857
   ON scratch USING gist (geom_3857);

Deploy your instance to Vercel

https://github.com/GEOLYTIX/xyz/wiki/VERCEL

Providing a login

https://github.com/GEOLYTIX/xyz/wiki/Security#acl

update acl_demeter set approved = true where email = '[email protected]';
update acl_demeter set admin = true where email = '[email protected]';