2. Environment Setup

Configure your local development and staging environments to integrate securely with the Aevum Zenth ecosystem. This guide covers dependency installation, environment variable configuration, and service initialization.

Prerequisites

Before proceeding, ensure your system meets the following requirements. All tools should be accessible via your system PATH.

🐳

Docker & Compose

v20.10+ with Compose v2.20+

📦

Node.js & npm

v18.17 LTS or higher

🔑

AWS CLI

v2.13+ configured with Zenth IAM role

🔗

Git

v2.40+ with SSH key configured

Step 1: Clone & Configure

Clone the repository and initialize environment variables

Download the official Aevum Zenth boilerplate and copy the provided template configuration.

bash

git clone git@github.com:aevum-zenth/dev-boilerplate.git
cd dev-boilerplate
cp .env.example .env

⚠️

Security Notice

Never commit .env files to version control. All secrets are rotated automatically via the Zenth Vault service.

Step 2: Initialize SDK

Authenticate and initialize the Zenth SDK

The SDK handles token rotation, region routing, and encrypted communication with Zenth core services.

bash

npm install
npx zenth-sdk init --env development
npx zenth-sdk auth:configure --provider oidc

ℹ️

OIDC Provider

Ensure your AWS IAM identity center is synced. The SDK will automatically fetch short-lived credentials.

Step 3: Local Services

Spin up required infrastructure

We provide a production-parity docker-compose.yml that includes PostgreSQL, Redis, Kafka, and the Zenth Gateway proxy.

bash

docker compose up -d --build
docker compose exec gateway zenth-gateway --healthcheck

Step 4: Verification

Run connectivity & health checks

Validate that all services are responding and the SDK can establish a secure tunnel.

bash

curl -s http://localhost:8080/health | jq
# Expected: {"status": "ok", "services": ["db", "cache", "mq", "gateway"]}

Docker containers show healthy status
SDK logs indicate successful OIDC handshake
Health endpoint returns HTTP 200 with all services
Local DNS resolution points to Docker bridge network

Troubleshooting

Port Conflicts

If Docker fails to bind, run lsof -i :8080 to identify conflicting processes. The Zenth gateway defaults to 8080 but can be overridden via APP_PORT.

SDK Timeout

Connection timeouts usually indicate misconfigured proxy settings or expired OIDC tokens. Run npx zenth-sdk auth:refresh and verify AWS_REGION matches your deployment target.

Database Migration Errors

PostgreSQL requires the zenth_dev database and zenth_user role. Ensure POSTGRES_DB and POSTGRES_USER in .env match the compose file defaults.

← 1. Introduction 3. Authentication →