Configuration & Environment
Relevant source files
The following files were used as context for generating this wiki page:
The Configuration & Environment system of the SecondLayer project is designed to support a multi-tenant, containerized architecture across local, development, staging, and production environments. It relies on a combination of environment variables (.env files), Docker Compose orchestrations, and modular Nginx configurations to manage service connectivity, security credentials, and Model Context Protocol (MCP) integrations.
The system ensures consistency between environments by using standardized naming conventions and automated credential validation scripts. This architecture allows developers to switch between local hot-reloading frontend development and fully deployed gateway environments on remote servers with minimal configuration changes.
Environment Architecture
The project distinguishes between several environments, each with specific port allocations and container naming suffixes. Local development is optimized for productivity using Vite's hot-reload, while remote environments (Dev, Stage, Prod) utilize a unified gateway approach.
The diagram above shows the structural difference between direct service access in local development and the proxied unified gateway used in remote environments.
Sources: deployment/LOCAL_DEVELOPMENT.md:73-95, CLAUDE.md:144-150
Environment Comparison Matrix
| Feature | Local | Dev | Stage | Prod |
|---|---|---|---|---|
| Location | Your machine | Gate server | Gate server | Gate server |
| URL | localhost:3000 | dev.legal.org.ua | stage.legal.org.ua | legal.org.ua |
| Backend Port | 3000 | 3003 | 3004 | 3001 |
| Database | secondlayer_local | secondlayer_dev | secondlayer_stage | secondlayer_db |
| Gateway | No | Yes | Yes | Yes |
Sources: deployment/LOCAL_DEVELOPMENT.md:330-340, DEPLOY_DEV_FIXES.md:32-45
Credential Management & Security
Credential configuration is handled through .env files which are strictly excluded from version control. The system includes automated validation scripts to prevent common authentication failures during deployment.
Automated Initialization
The system uses an init-postgres.sh script to automatically create application users and databases based on environment variables if they do not exist.
This sequence illustrates the automated workflow for ensuring database credentials match the application environment.
Sources: deployment/CREDENTIALS_SETUP.md:68-90, deployment/CREDENTIALS_SETUP.md:168-180
Essential Configuration Variables
| Variable | Description | Requirement |
|---|---|---|
OPENAI_API_KEY | Primary AI analysis & embeddings | Required |
ZAKONONLINE_API_TOKEN | Court database access | Required |
SECONDARY_LAYER_KEYS | Comma-separated API auth tokens | Required |
POSTGRES_PASSWORD | Application database password | Required |
JWT_SECRET | Secret for user session signing | Required |
Sources: deployment/LOCAL_DEVELOPMENT.md:200-220, mcp_backend/DEPLOYMENT.md:27-40
Service Configuration
The SecondLayer backend is composed of several micro-services and storage engines. Connectivity is managed via internal Docker network hostnames that vary by environment suffix (e.g., redis-local vs redis-dev).
Service Connectivity
In the development environment, hostnames must be explicitly configured to avoid conflicts with local instances.
# Example .env.dev service URLs
RADA_MCP_URL=http://rada-mcp-app-dev:3001
REDIS_HOST=redis-dev
QDRANT_URL=http://qdrant-dev:6333
Sources: DEPLOY_DEV_FIXES.md:9-17
Storage Layer Configuration
The system utilizes three primary data stores:
- PostgreSQL: Stores document metadata and structured legal data.
- Redis: Used as a caching layer for RADA data (Deputies 7d, Bills 1d, Laws 30d).
- Qdrant: Vector database for storing legal reasoning patterns and embeddings.
Sources: CLAUDE.md:160-165, CLAUDE.md:245-250
Network & Gateway Configuration
Remote environments use a modular Nginx configuration to handle Model Context Protocol (MCP) traffic, OAuth endpoints, and static frontend assets.
Modular Nginx Includes
The configuration is split into functional modules to allow for easier maintenance and testing of specific protocol features.
| Module | Purpose | Key Routes |
|---|---|---|
oauth-endpoints.conf | OAuth 2.0 authorization | /.well-known/openid-configuration |
mcp-endpoints.conf | MCP protocol (SSE) | /sse, /v1/sse, /mcp |
api-endpoints.conf | REST API & Webhooks | /api, /auth, /webhooks |
frontend-routes.conf | React SPA routing | /, static assets |
Sources: deployment/nginx/README.md:10-20, deployment/nginx/README.md:90-125
The diagram depicts the modular inclusion system used to construct the final Nginx configuration for the staging environment.
Sources: deployment/nginx/README.md:140-155
Summary
The SecondLayer environment is managed through a "Configuration-as-Code" approach utilizing Docker Compose and environment-specific variable files. By isolating credentials, utilizing automated database initialization, and employing a modular Nginx gateway, the system achieves a secure and scalable architecture that supports both high-velocity local development and robust remote production deployments. Consistency is maintained across the lifecycle via the manage-gateway.sh script, which orchestrates environment transitions and health monitoring.