Skip to main content

​
Overview

This guide walks you through setting up Walle, an AVL (Automatic Vehicle Location) telemetry tracking API service built with NestJS. Walle uses PostgreSQL with table partitioning and PostGIS for geospatial data, along with MongoDB for additional data storage.

​
System Requirements

  • Node.js: v18 or higher
  • npm: v9 or higher
  • PostgreSQL: v14 or higher with PostGIS extension
  • MongoDB: v6 or higher
  • Operating System: Linux, macOS, or Windows with WSL2
  • CPU: 2+ cores recommended
  • RAM: 4GB minimum, 8GB recommended
  • Storage: 20GB+ for database partitions
  • Network: Stable connection for MongoDB Atlas (if using cloud)

​
PostgreSQL Setup

​
Install PostgreSQL

sudo apt update
sudo apt install postgresql postgresql-contrib postgis

​
Enable PostGIS Extension

PostGIS is required for geospatial functionality (storing and querying GPS coordinates).
1

Connect to PostgreSQL

sudo -u postgres psql
2

Create the database

CREATE DATABASE walledb;
3

Connect to walledb

\c walledb
4

Enable PostGIS extension

CREATE EXTENSION IF NOT EXISTS postgis;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
Verify installation:
SELECT PostGIS_version();
5

Create database user

CREATE USER ngynx WITH PASSWORD 'ngynx';
GRANT ALL PRIVILEGES ON DATABASE walledb TO ngynx;
GRANT ALL ON SCHEMA public TO ngynx;

​
Configure PostgreSQL Authentication

Edit pg_hba.conf to allow password authentication: 
sudo nano /etc/postgresql/14/main/pg_hba.conf
Add or modify the following line: 
# IPv4 local connections:
host    walledb         ngynx           127.0.0.1/32            md5
Restart PostgreSQL: 
sudo systemctl restart postgresql

​
MongoDB Setup

​
Install MongoDB

wget -qO - https://www.mongodb.org/static/pgp/server-6.0.asc | sudo apt-key add -
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list
sudo apt update
sudo apt install -y mongodb-org
sudo systemctl start mongod
sudo systemctl enable mongod

​
Create MongoDB Databases

Walle requires two MongoDB databases: 
mongosh

use deltaDispatch
db.createCollection("init")

use authSoftware
db.createCollection("users")

​
Application Setup

1

Clone and Install Dependencies

Navigate to the Walle source directory and install dependencies:
cd ~/workspace/source/walle
npm install
2

Configure Environment Variables

Create a .env file in the project root:
cp .env.example .env
See the Environment Configuration guide for details.
3

Initialize Database

Start the application to automatically create the partitioned table structure:
npm run start:dev
The application will:
  • Create the points parent table with partitioning
  • Create partitions for today and tomorrow
  • Set up all required indexes

​
Database Initialization

Walle automatically creates the partitioned table structure on first run. The parent table is defined in src/app/database/constants/points.sql.ts:1.

​
Parent Table Structure

The points table is partitioned by timestamp (BIGINT) using range partitioning: 
CREATE TABLE points (
  id UUID NOT NULL DEFAULT gen_random_uuid(),
  timestamp BIGINT NOT NULL,
  
  -- Device identification
  tracker_device_imei BIGINT NOT NULL,
  tracker_device_license_plate VARCHAR(20),
  
  -- Geospatial position (PostGIS)
  location GEOMETRY(Point, 4326),
  tracker_device_latitude DOUBLE PRECISION NOT NULL,
  tracker_device_longitude DOUBLE PRECISION NOT NULL,
  
  -- Movement and speed
  tracker_device_speed_kh REAL DEFAULT 0,
  tracker_device_movement BOOLEAN DEFAULT false,
  
  -- Composite primary key (required for partitioning)
  PRIMARY KEY (id, timestamp)
) PARTITION BY RANGE (timestamp);

​
Partition Creation

Partitions are created automatically by PartitionManagerService in src/app/points/partition-manager.service.ts:18:
  • On startup: Creates partitions for today and tomorrow
  • Daily schedule: Creates next day’s partition at 23:50
  • Manual creation: Use the service methods for specific dates

​
Verification Steps

After setup, verify the installation using the provided verification script.

​
Run Verification Script

node verify-partitions.js
Expected output: 
✅ Connected to PostgreSQL

📊 Table Information:
{
  table_name: 'points',
  table_type: 'Partitioned Table',
  partition_key: 'RANGE (timestamp)'
}

📋 Partitions:
  - points_2026_03_03: FOR VALUES FROM ('1709424000000') TO ('1709510400000')
  - points_2026_03_04: FOR VALUES FROM ('1709510400000') TO ('1709596800000')

🔍 Indexes on points_2026_03_03:
  - idx_points_2026_03_03_timestamp
  - idx_points_2026_03_03_imei_ts
  - idx_points_2026_03_03_imei_ts_trip
  - idx_points_2026_03_03_location

​
Verify PostGIS

Test PostGIS functionality: 
SELECT ST_AsText(ST_MakePoint(-74.006, 40.7128));
Expected result: 
POINT(-74.006 40.7128)

​
Troubleshooting

Problem: Cannot connect to PostgreSQL databaseSolutions:
  • Check if PostgreSQL is running: sudo systemctl status postgresql
  • Verify connection settings in .env file
  • Check pg_hba.conf authentication settings
  • Ensure the user has proper permissions: 
    GRANT ALL PRIVILEGES ON DATABASE walledb TO ngynx;
GRANT ALL ON SCHEMA public TO ngynx;
Problem: ERROR: could not open extension control fileSolutions:
  • Install PostGIS: sudo apt install postgis postgresql-14-postgis-3
  • Verify installation: SELECT * FROM pg_available_extensions WHERE name = 'postgis';
  • Ensure you’re connected to the correct database when creating extension
Problem: Cannot connect to MongoDBSolutions:
  • Check if MongoDB is running: sudo systemctl status mongod
  • Verify connection URI format in .env
  • For MongoDB Atlas, check network access and IP whitelist
  • Test connection: mongosh <your-connection-string>
Problem: Error creating partitions on startupSolutions:
  • Verify PostGIS extension is enabled
  • Check that POSTGRES_SYNC is set to false in .env
  • Ensure the user has CREATE TABLE permissions
  • Manually create parent table if needed: 
    psql -U ngynx -d walledb -f src/app/database/constants/points.sql.ts
Problem: 401 Unauthorized errorsSolutions:
  • Verify JWT_SECRET is set in .env
  • Ensure the secret matches between token generation and validation
  • Check token expiration settings in src/app/auth/auth.module.ts
Problem: Error: listen EADDRINUSE: address already in use :::3700Solutions:
  • Change the PORT in .env file
  • Kill the process using the port: 
    lsof -i :3700
kill -9 <PID>

​
Next Steps

Environment Configuration

Configure environment variables for different environments

Partition Management

Learn how to manage and monitor database partitions

API Reference

Explore the API endpoints and authentication

Points API

Start saving telemetry data points

Build docs developers (and LLMs) love

Get started for freeTalk to us