localnerve/jam-build-propsdb repository overview

⁠jam-build-propsdb - Go Fiber Data Service

A high-performance data service built with Go and Fiber, serving as a drop-in replacement for the Node.js Express data service in the Jam Build⁠ project. Supports all GORM-compatible databases including MariaDB/MySQL, PostgreSQL, SQLite, and SQL Server.

⁠Features

• 🚀 High Performance: Built with Go Fiber for maximum throughput
• 🗄️ Multi-Database Support: Works with MariaDB, MySQL, PostgreSQL, SQLite, and SQL Server via DB_TYPE configuration. Configuration details⁠
• 🔐 Authentication: Integrated with Authorizer using authorizer-go SDK
• 📦 API Compatibility: Drop-in replacement for the Node.js Express service. API details⁠
• 🔄 Version Control: Optimistic locking with E_VERSION conflict detection
• 🐳 Docker Ready: Multi-stage Dockerfile for containerized deployments
• 🧪 Testable: Designed for unit, integration, and e2e testing with testcontainers. Testing details⁠

⁠Quick Start

⁠Public Docker Image

• https://hub.docker.com/r/localnerve/jam-build-propsdb⁠

  • localnerve/jam-build-propsdb:latest

• Environment:

  • PORT: The exposed port to the propsdb-api
  • DB_TYPE: The database type [mariadb | mysql | mssql | postgres | sqlite]
  • DB_HOST: The hostname of the database service
  • DB_PORT: The database service port
  • DB_APP_DATABASE: The property database name
  • DB_APP_USER: The application user name
  • DB_APP_PASSWORD: The application user password
  • DB_USER: The user user name
  • DB_PASSWORD: The user user password
  • DB_APP_CONNECTION_LIMIT: The application connection pool limit
  • DB_CONNECTION_LIMIT: The user connection pool limit
  • AUTHZ_URL: The url to the authorizer service
  • AUTHZ_CLIENT_ID: The client ID of the authorizer service

⁠Development

⁠Prerequisites

• Go 1.26.0 or higher
• Docker Desktop
• Node 24.12.0 or higher
• GNU Make 4.4.1

⁠Installation

1. Clone the repository:

git clone https://github.com/localnerve/jam-build-propsdb.git
cd jam-build-propsdb

1. Install dependencies:

make deps
make install-tools

1. Build and run the full service:

make docker-compose-up

The service will start on http://localhost:3000.

⁠Ports

These are the ports used by default:

• Service ports: 3000 (api), 6379 (cache), 8080 (authorizer)
• Typical database ports (depends on DB_TYPE, defaults to mariadb):
  • 3306 (mariadb, mysql)
  • 5432 (postgres)
  • 1433 (mssql)
• Monitoring ports: 3001 (grafana), 9090 (prometheus)

⁠Database Configuration

⁠Supported Databases

Configure the database type using the DB_TYPE environment variable (defaults to mariadb). For a detailed matrix of configuration requirements (ports, images, healthchecks), see the database documentation⁠.

• MySQL/MariaDB: DB_TYPE=mysql or DB_TYPE=mariadb
• PostgreSQL: DB_TYPE=postgres or DB_TYPE=postgresql
• SQLite: DB_TYPE=sqlite (set DB_APP_DATABASE to file path)
• SQL Server: DB_TYPE=sqlserver or DB_TYPE=mssql

⁠Initialization

SQL migration files will be applied for each database type in the data/initdb/ directory:

• data/initdb/mariadb/ - MariaDB initialization
• data/initdb/mysql/ - MySQL initialization
• data/initdb/postgres/ - PostgreSQL initialization
• data/initdb/sqlite/ - SQLite initialization
• data/initdb/sqlserver/ - SQL Server initialization

⁠Migrations

SQL migration files will be applied for each database type in the data/migrations/ directory:

• data/migrations/mariadb/ - MariaDB migrations
• data/migrations/mysql/ - MySQL migrations
• data/migrations/postgres/ - PostgreSQL migrations
• data/migrations/sqlite/ - SQLite migrations
• data/migrations/sqlserver/ - SQL Server migrations

The service also supports GORM AutoMigrate as a fallback.

⁠API Endpoints

Swagger documentation is available at http://localhost:3000/swagger/ and updated with make swagger.

⁠Application Data (Public GET, Admin POST/DELETE)

• GET /api/data/app/:document/:collection - Get properties for a document/collection
• GET /api/data/app/:document?collections=col1,col2 - Get collections and properties
• GET /api/data/app - Get all documents, collections, and properties
• POST /api/data/app/:document - Upsert document (requires admin role)
• DELETE /api/data/app/:document/:collection - Delete collection (requires admin role)
• DELETE /api/data/app/:document - Delete document or properties (requires admin role)

⁠User Data (All require user authentication)

• GET /api/data/user/:document/:collection - Get user properties
• GET /api/data/user/:document?collections=col1,col2 - Get user collections
• GET /api/data/user - Get all user documents
• POST /api/data/user/:document - Upsert user document
• DELETE /api/data/user/:document/:collection - Delete user collection
• DELETE /api/data/user/:document - Delete user document or properties

⁠API Versioning

The service supports API versioning via the X-Api-Version header:

curl -H "X-Api-Version: 1.0.0" http://localhost:3000/api/data/app

Supported versions:

• 1.0.0 (default)
• 1.0 (alias for 1.0.0)

⁠Docker Deployment

⁠Service Stack Docker Compose

This will start the API service, database, cache, and authorizer.

make docker-compose-up

⁠Observability Stack Docker Compose

This will start the observability services for the API service.

make obs-up

For information on Prometheus metrics and Grafana dashboards, see OBSERVABILITY⁠.

⁠Development

⁠Running Tests

Full information on running tests is available in the testing documentation⁠.

# Unit tests
make test

# Integration tests (requires Docker)
make test-integration

# End-to-end service health tests (requires Docker)
make test-e2e

# Full stack end-to-end tests (requires Docker)
make test-e2e-js # Params: DEBUG=1 (debug, no rebuild), DEBUG=2 (debug, full rebuild)

# Full stack end-to-end tests with coverage (requires Docker)
make test-e2e-js-cover # Params: REBUILD=1 (rebuild orchestrator), HOST_DEBUG=1 (debug host)

Many more tests are available in the Makefile, see the testing documentation⁠ for full details.

⁠Building

# Build the api service binary
make build

# Build the healthcheck binary
make build-healthcheck

# Build the testcontainers binary
make build-testcontainers

# Build the docker image
make docker-build

# Build and run the entire composition
make DB_TYPE=mariadb docker-compose-up # DB_TYPE = mariadb | mysql | mssql | postgres | sqlite

⁠Authentication

The service integrates with Authorizer⁠ for authentication and authorization.

• Admin routes: Require admin role
• User routes: Require user role
• Session cookie: cookie_session

⁠Version Control

All mutation operations (POST, DELETE) use optimistic locking:

1. Client sends current version in request body
2. Server checks if version matches current document version
3. If mismatch, returns 409 Conflict with E_VERSION error
4. Client must refresh, reconcile, and retry

⁠License

Copyright (c) 2026 Alex Grant [email protected]⁠ (https://www.localnerve.com⁠), LocalNerve LLC

This project is licensed under the GNU Affero General Public License v3.0 or later.

⁠Acknowledgments

Special thanks to the Antigravity AI assistant for help with the Go migration, testing architecture, and documentation.