Internal Developer Platform (IDP)

The Internal Developer Platform (IDP) is a cloud-native developer portal built on Backstage.io. It serves as the primary gateway for engineering teams to manage the entire software development lifecycle—unifying service catalogs, documentation, and automated scaffolding into a high-performance "Golden Path" ecosystem.

🚀 Key Features

• Service Catalog: A centralized, searchable directory of microservices, websites, and data pipelines with ownership and dependency tracking.
• Software Templates: Rapid scaffolding of new projects (React, FastAPI, etc.) using industry-standard best practices and security defaults.
• TechDocs: High-quality Documentation-as-Code (DaC), rendered adjacent to service components for maximum discoverability.
• AI-Enhanced Governance: Integrated Agent Constitution governing agentic workflows for platform evolution and automated maintenance.
• Identity & Security: Enterprise SSO via Keycloak (OIDC) with granular RBAC mapped to organizational hierarchies.

🛠️ Prerequisites

• Node.js: v20.x or v22.x (v22.x required for Docker build)
• Yarn: v1.x (Classic)
• Docker: Required for running Keycloak and local databases.

🏁 Quick Start

1. Environment Setup

Copy the example environment file and configure your secrets:

cp .env.example .env

Note: You must configure APP_BASE_URL, KEYCLOAK_CLIENT_SECRET and GITLAB_TOKEN in the .env file before starting.

2. Start Services (Keycloak & Postgres)

If you are running locally, you MUST start these services as we have removed SQLite support to ensure production parity:

docker compose -f docker-compose.dev.yaml up -d

Ensure Keycloak is configured according to the Keycloak Setup Guide.

3. Installation

Install all dependencies:

yarn install

4. Run the Platform

Start both the Frontend (App) and Backend servers:

yarn dev

• App: http://localhost:3000
• Backend: http://localhost:7007
• Keycloak: http://localhost:8080

5. 🐳 Production Deployment

To run the platform in a production-like environment (with PostgreSQL and optimized Docker image):

1. Build the Image:

   docker compose -f docker-compose.prod.yaml build

2. Start Production Services: You can use the provided helper script to pull the latest code, build, and start the services:

   ./scripts/deploy.sh

   Alternatively, run manually:

   docker compose -f docker-compose.prod.yaml up -d

This spins up:

• Backstage: The optimized Node.js app serving both frontend and backend.

IMPORTANT: This setup now requires an external PostgreSQL instance (AWS RDS, Azure Generic, etc.). Local SQLite state is not supported for production-grade environments. Ensure POSTGRES_HOST and credentials in .env are configured.

IMPORTANT: This setup assumes you have an enterprise-grade Keycloak instance running and accessible. Ensure KEYCLOAK_BASE_URL in your .env points to the correct location.

📚 Documentation

Detailed documentation for platform engineers:

• Authentication: Keycloak Setup Strategy
• Deployment: Deployment Strategy
• RBAC Policy: RBAC Configuration

📂 Project Structure

├── packages/
│   ├── app/                 # Frontend (React)
│   └── backend/             # Backend (Node.js)
├── templates/               # Software Templates (Golden Paths)
│   └── scaffolding-templates/
├── docs/                    # Architecture & Setup Documentation
├── app-config.yaml          # Main configuration file
└── users.yaml               # Local user/group definitions

🤝 Contributing

1. Commit Often: We follow a strict "Commit Every Change" policy.
2. Linting: Ensure code passes linting before pushing.
3. Docs: Update documentation if you change infrastructure or configuration.