Merge pull request #948 from jupyter-naas/fix/local-dev-setup

fix(local-dev): make local stack work out of the box

Author: Dr0p42

.deploy/docker/element-config.json

@@ -334,16 +334,6 @@ const NODES_DEF = [
     status: 'local',
     links: [{ label: 'Dagster UI', port: 3001, path: '/' }],
   },
-  {
-    id: 'matrix', label: 'Matrix\n+ Element', group: 'ui',
-    type: 'Messaging UI',
-    desc: 'Federated Matrix server (Synapse) and Element web client for distributed AI output delivery.',
-    status: 'running',
-    links: [
-      { label: 'Element Web',  port: 8081, path: '/' },
-      { label: 'Synapse API',  port: 8008, path: '/' },
-    ],
-  },
 
   // ── CUSTOM MODULES ────────────────────────────────────────────────────────
   // These nodes are populated from the abi00-modules package loaded by the
@@ -371,8 +361,6 @@ const EDGES_DEF = [
   { from: 'abi-api', to: 'dagster' },
   { from: 'dagster', to: 'minio'   },
   { from: 'dagster', to: 'postgres' },
-  // matrix
-  { from: 'matrix', to: 'abi-api' },
   // nexus ↔ data
   { from: 'nexus', to: 'postgres' },
   { from: 'nexus', to: 'redis'    },

.deploy/docker/service-portal/index.html.template

@@ -165,7 +165,27 @@ def unsupported_method(self, arg: str) -> None:
 **Problem:** Frontend won't start (`next: command not found`)  
 **Solution:** Run `pnpm install` in `libs/naas-abi/naas_abi/apps/nexus/apps/web`
 
-### Stack Management
+### Local Access
+
+After `abi stack start`, the web UI is at `http://localhost:3042`.
+
+Default admin credentials (set in `config.local.yaml` under `nexus_config.users`):
+
+| Email | Password |
+|---|---|
+| `admin@example.com` | `Admin1234!` |
+
+Password login is enabled via `auth_password_enabled: true` in `config.local.yaml`. Set it to `false` to switch back to magic link.
+
+If you see "Incorrect email or password", the Postgres volume may have been initialized with a different password. Reset it:
+
+```bash
+PG_PASS=$(grep POSTGRES_PASSWORD .env | cut -d= -f2)
+docker exec abi-postgres-1 psql -U abi -c "ALTER USER abi PASSWORD '$PG_PASS';"
+docker compose restart abi
+```
+
+## Stack Management
 
 ```bash
 # Start full stack (requires RabbitMQ, Redis, Qdrant, MinIO)

.deploy/docker/synapse/bootstrap.sh

@@ -22,89 +22,144 @@ ABI (Agentic Brain Infrastructure) is the open-source AI Operating System that g
 
 </div>
 
+## Why ABI?
+
+Most AI platforms lock you in: proprietary data models, opaque pipelines, no exit. When the vendor changes pricing or discontinues a model, you have no contingency.
+
+ABI is built for continuity and ownership. Every layer is swappable: LLM providers, infrastructure services, data adapters. Agents reason over context sources you control (knowledge graph, vector store, file system), so your data and logic stay yours regardless of what any upstream vendor does.
+
+It also covers the full stack from ingestion to UI, so you are not stitching together five different tools. The knowledge graph is built on [ISO/IEC 21838-2 Basic Formal Ontology (BFO)](https://www.iso.org/standard/74572.html), the open top-level ontology standard used in biotech, defense, and enterprise. BFO-grounded data makes compliance with [ISO/IEC 42001:2023 AI Management Systems](https://www.iso.org/standard/42001) and the [EU AI Act (Regulation 2024/1689)](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=OJ:L_202401689) significantly easier, since traceability and auditability are built into the data model from the start.
+
 ## Quick Start
 
 ### Prerequisites
 
 - Python 3.12+, Git, [uv](https://astral.sh/uv) (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
 - [Docker Desktop](https://www.docker.com/products/docker-desktop) (8GB+ RAM for full stack)
-- LLMs API key: OpenAI and OpenRouter
+- LLM API keys: any OpenAI-compatible provider (OpenAI, OpenRouter, or equivalent)
 
-You also need to have the `docker` command available in your terminal.
-
-### Local Development
+### Get started
 
 ```bash
 uv tool install naas-abi-cli --force --upgrade
 
-abi new project demo #You can change the project name to your own
-cd demo
+abi new project my_ai   # replace "my_ai" with your project name
+cd my_ai
 abi start
 ```
 
-**Platform launch:**
+### Web UI
+
+The main interface. Chat with Abi, switch agents, manage your workspace, and access your knowledge graph. Open [http://localhost:3042](http://localhost:3042) and log in with `admin@example.com` / `Admin1234!`.
 
-- Services Portal: https://localhost:8080
-- Backend: https://api.localhost (Important: you must access it first and accept the self-signed TLS certificate for the frontend to work)
-- Frontend: https://nexus.localhost
+<div align="center">
+  <img src="docs/site/static/abi/Screenshot_Local_WebUI.png" alt="ABI web UI" width="800">
+</div>
 
-### CLI Commands
+### API
+
+Every agent is exposed as a REST endpoint. Useful for integrating ABI into your own tools, triggering agents from scripts, or building on top of the platform. Explore the full reference at [http://localhost:9879/docs](http://localhost:9879/docs).
+
+<div align="center">
+  <img src="docs/site/static/abi/Screenshot_Local_API.png" alt="ABI API docs" width="800">
+</div>
+
+### CLI
+
+Run `abi chat` to talk to Abi directly from your terminal. No browser needed.
+
+<div align="center">
+  <img src="docs/site/static/abi/Screenshot_Local_CLI.png" alt="ABI CLI" width="800">
+</div>
 
 ```bash
-abi start         # Start all services
-abi stop          # Stop all services
-abi chat          # Interactive agent chat
-abi config validate # Validate the configuration
+abi start            # Start the full stack and open the browser
+abi stop             # Stop all running services
+abi chat             # Chat with Abi in the terminal
+abi logs             # Tail logs from a service (e.g. abi logs abi)
+abi stack status     # Check health of all running containers
+abi config validate  # Check your config.yaml for errors
+abi new module       # Scaffold a new module
+abi new agent        # Scaffold a new agent
+abi new workflow     # Scaffold a new workflow
 ```
 
 ## How It Works
 
-**1. Your data becomes structured knowledge**
+Everything in ABI is organized around **modules**. A module models a domain, connects to its data sources, and exposes intelligent capabilities on top. You enable one with a single line in `config.yaml`.
 
-Connect any data source: CRMs, code repositories, databases, productivity tools, financial systems. ABI ingests everything, maps relationships between entities, and builds a living knowledge graph of your organization. Not a data warehouse. A model of your reality.
+A module bundles:
 
-**2. Your team gets AI that knows their job**
+- **Agents**: LLM-powered agents that reason over the knowledge graph and dispatch to the right domain capability
+- **Applications**: web UI, REST API, and CLI surfaces that expose module capabilities to end users and operators
+- **Integrations**: connectors to external APIs (GitHub, Salesforce, LinkedIn, Notion, ...) that pull data into the module
+- **Ontologies**: OWL/Turtle files that define the domain as typed entities and relationships in a knowledge graph
+- **Orchestrations**: Dagster-based schedules, jobs, and event sensors that automate module execution
+- **Pipelines**: operations that read and write RDF triples to the knowledge graph (add, merge, insert)
+- **Workflows**: structured callable tools exposed to agents and users that query or act on the knowledge graph
 
-Build agents for any role and workflow, each grounded in your organization's ontology. They understand the context of the work, not just the words in the question. The more you build, the deeper the institutional intelligence.
+Each infrastructure concern is abstracted as a port with a swappable adapter. Change the adapter in `config.yaml`, no module code changes needed. The community edition ships every service as a Docker container. Enterprise deployments swap each adapter for a managed cloud service or run the whole stack on Kubernetes.
 
-**3. Every question finds the right intelligence**
+- **Triple store** (knowledge graph): Community: Apache Fuseki / Enterprise: Amazon Neptune, Stardog, Ontotext GraphDB
+- **Vector store** (semantic search): Community: Qdrant / Enterprise: Pinecone, Weaviate, pgvector, Azure AI Search
+- **Relational store** (agent memory): Community: PostgreSQL / Enterprise: Amazon RDS, Azure Database, Cloud SQL
+- **Object storage** (files and artifacts): Community: MinIO / Enterprise: Amazon S3, Azure Blob Storage, Google Cloud Storage
+- **Message bus** (async task routing): Community: RabbitMQ / Enterprise: Amazon MQ, Azure Service Bus, Google Pub/Sub
+- **Cache** (sessions and hot data): Community: Redis / Enterprise: Amazon ElastiCache, Azure Cache for Redis, Memorystore
+- **Orchestration** (schedules and sensors): Community: Dagster / Enterprise: Dagster Cloud, Airflow on MWAA, Cloud Composer
 
-A supervisor agent reads the intent behind each request and routes it to the right AI model, domain expert agent, or directly into your knowledge graph. Swap providers without rebuilding. The infrastructure adapts as AI evolves.
+The **Context Engine** wires all these services at startup and routes every request to the right agent. **Abi** acts as the supervisor: it reads the intent behind each request and dispatches to the right domain agent or answers directly from the knowledge graph, vector store, or file system.
 
-For the full architecture, including module structure, five-layer stack, services, and data flow, see [The ABI Stack](https://docs.naas.ai/architecture/the-stack).
+Start with the marketplace modules to get running immediately, then use `abi new module` to model your own domain. Full architecture reference: [The ABI Stack](https://docs.naas.ai/architecture/the-stack).
 
 ## Repository Layout
 
-| Package                | What it does                                                     |
-| ---------------------- | ---------------------------------------------------------------- |
-| `naas-abi-core`        | Infrastructure adapters: storage, vector DB, message bus, SPARQL |
-| `naas-abi`             | Core agents, ontologies, and the Nexus app (API + web UI)        |
-| `naas-abi-cli`         | The `abi` CLI                                                    |
-| `naas-abi-marketplace` | Optional domain agents and third-party integrations              |
+**Your project** (created with `abi new project my_ai`):
 
-## Production Deployment
+```
+my_ai/
+├── src/
+│   └── my_ai/                 # Your module (agents, integrations, ontologies, ...)
+├── config.yaml                # Base module and service configuration
+├── config.local.yaml          # Local overrides (ports, credentials, enabled modules)
+├── config.remote.yaml         # Remote/production overrides
+├── docker-compose.yml         # Local stack definition (generated)
+├── pyproject.toml             # Python project, naas-abi-* installed as dependencies
+└── .env                       # Secrets and environment variables
+```
 
-### Self-Hosted Docker
+**This repo** (for contributors):
 
-```bash
-docker compose up -d
+```
+abi/
+├── libs/
+│   ├── naas-abi-core/         # Infrastructure adapters (storage, vector DB, message bus, SPARQL)
+│   ├── naas-abi/              # Core agents, ontologies, and the Nexus app (API + web UI)
+│   ├── naas-abi-cli/          # The abi CLI
+│   └── naas-abi-marketplace/  # Domain modules and third-party integrations
+├── docs/site/                 # Docusaurus documentation site
+├── docker/                    # Caddy, Dagster, Postgres, and service configs
+├── scripts/                   # Utility scripts (sync, export, datastore, docs generation)
+├── config.local.yaml          # Module and service configuration (local)
+├── config.yaml                # Module and service configuration (base)
+└── docker-compose.yml         # Local stack definition
 ```
 
-Full stack with PostgreSQL, Fuseki, Qdrant, MinIO
+## Production Deployment
 
-### Managed Hosting
+### Self-Hosted
 
-Need a hosted, managed deployment? [Get started on naas.ai](https://naas.ai) or reach out to the team directly.
+Copy your `.env` and config files to the target server, then run:
 
-## Why ABI?
+```bash
+docker compose -f docker-compose.yml up -d
+```
 
-Most AI tools are black boxes. ABI is built on open standards so every decision is traceable, every model is replaceable, and you own your data.
+All services (PostgreSQL, Fuseki, Qdrant, MinIO, RabbitMQ, Redis, Dagster) start as containers. For production workloads, swap the Docker adapters for managed cloud services as described in [How It Works](#how-it-works).
 
-**Built on international standards:**
+### Managed Hosting
 
-- [ISO/IEC 42001:2023](https://www.iso.org/standard/42001) - AI Management Systems
-- [ISO/IEC 21838-2:2021](https://www.iso.org/standard/74572.html) - Basic Formal Ontology (BFO)
-- EU AI Act compliance-ready
+Need a hosted, managed deployment? [Get started on naas.ai](https://naas.ai) or reach out to the team directly.
 
 ## Research & Development
 
@@ -116,14 +171,16 @@ Collaborative effort between:
 - **[NCOR](https://ncor.buffalo.edu/)** - National Center for Ontological Research
 - **[Forvis Mazars](https://www.forvismazars.com/)** - Global Audit & Consulting
 
-⭐ **If ABI is useful to you, star the repo to help others find it.**
-
 ## Contributing
 
-We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+We welcome contributions. Open an issue or pull request to get started.
 
 ## License
 
-MIT License - see [LICENSE](https://opensource.org/licenses/MIT)
+MIT License - see [LICENSE](LICENSE)
 
 For enterprise support or managed hosting, visit [naas.ai](https://naas.ai).
+
+---
+
+⭐ If ABI is useful to you, star the repo to help others find it.