Docker Compose Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The Docker Compose configuration defines the Nyansa "second brain" stack. It manages a collection of services including local Large Language Models (LLMs), a vector store, a workflow engine, and a web interface. The stack uses a fixed project name nyansa to ensure consistent container and volume management across deployments.
Sources: docker-compose.yml:4-6, README.md:10-12
Core Service Architecture
Nyansa organizes services within a dedicated internal Docker network named nyansa. This network isolates backend components like the database, vector store, and LLM inference engine from direct external access.
Internal Services
These services do not publish any ports to the host network and communicate solely within the internal Docker network.
- nyansa-postgres: Provides persistence for n8n.
- nyansa-qdrant: Serves as the vector database for storing note embeddings.
- nyansa-ollama: Runs local LLMs (
qwen2.5:3b) and embedding models (nomic-embed-text). - nyansa-memory-api: A TypeScript RAG service that handles vault ingestion and semantic search.
Exposed Services
The stack restricts external access through specific gateways.
- nyansa-n8n: The workflow engine, bound to
127.0.0.1:5678for local or tunnel access. - nyansa-open-webui: The chat interface, bound to
127.0.0.1:3000. - nyansa-caddy-public: The primary entry point for public HTTPS access, publishing ports 80 and 443.
Sources: docker-compose.yml:101-260, README.md:38-66, scripts/check-exposure.sh:6-12
Service Relationship Diagram
The following diagram illustrates how services interact and share data within the Docker network.
Sources: README.md:38-66, docker-compose.yml:101-260
Hardware and Access Profiles
The configuration uses Docker Compose profiles to support different hardware environments and access methods. You enable these profiles using the --profile flag.
Hardware Profiles
Hardware profiles determine which version of the nyansa-ollama service runs to utilize available accelerators.
| Profile | Target Hardware | Image/Configuration Detail |
|---|---|---|
cpu | Standard CPU | Uses ollama/ollama without specialized drivers. |
gpu-nvidia | NVIDIA GPUs | Includes nvidia driver reservations and GPU capabilities. |
gpu-amd | AMD GPUs | Uses ollama/ollama:*-rocm image and maps /dev/kfd. |
Sources: docker-compose.yml:234-266, README.md:15-18
Access Profiles
Access profiles manage how the stack is exposed to the network.
- public: Enables
nyansa-caddy-public. It handles Let's Encrypt certificates and basic auth for the n8n editor. - tailscale: Enables
nyansa-tailscaleandnyansa-caddy-tailscale. It allows access via a Tailscale tailnet without opening any host ports.
Sources: docker-compose.yml:272-332, README.md:27-30
Initialization and Data Import
The stack includes two one-shot services that perform setup tasks on the first boot.
- nyansa-n8n-import: This service imports credentials and workflows from
./n8n/demo-data. It skips the import if workflows already exist in the database. - nyansa-ollama-pull-model: This service automatically pulls the required AI models (
qwen2.5:3bandnomic-embed-text) into the Ollama storage volume.
Sources: docker-compose.yml:85-100, docker-compose.yml:128-146
Security Configuration
The Docker Compose file implements several hardening measures to protect the host and internal data.
- Read-only Filesystems: The
nyansa-memory-apicontainer runs with a read-only root filesystem and dropped Linux capabilities. - Network Isolation: Critical services (PostgreSQL, Qdrant, Ollama) are not reachable from the host.
- Secret Management: Mandatory variables like
POSTGRES_PASSWORDandQDRANT_API_KEYare enforced using YAML interpolation syntax (${VAR:?error}). - Safe n8n Configuration: n8n is configured to block workflow access to container environment variables (
N8N_BLOCK_ENV_ACCESS_IN_NODE=true). - Immutable Releases: Production deployments use specific image tags based on commit SHAs, replacing the default
devtag during the build process.
Sources: docker-compose.yml:211-215, docker-compose.yml:45-56, scripts/check-exposure.sh:6-12, scripts/build-publish.sh:84-91
Volume Management
The stack uses named volumes to persist data across container restarts and updates.
| Volume Name | Service | Purpose |
|---|---|---|
nyansa_n8n_storage | n8n | Stores user data and configuration. |
nyansa_postgres_storage | Postgres | Stores n8n workflow and state database. |
nyansa_ollama_storage | Ollama | Stores downloaded LLM models. |
nyansa_qdrant_storage | Qdrant | Stores vector embeddings and collection state. |
nyansa_caddy_data | Caddy | Stores Let's Encrypt certificates. |
Sources: docker-compose.yml:8-25, scripts/backup.sh:30-41
Operations and Health Checks
Every service defines a healthcheck to allow the orchestration layer to determine if the stack is ready. The scripts/wait-healthy.sh script monitors these checks during deployment.
- Custom Checks: Qdrant uses a
bashTCP check on port 6333. n8n uses anodefetch call to its/healthzendpoint. - Backup Strategy: The
scripts/backup.shscript performs a logical dump of PostgreSQL and createstar.gzarchives of stateful volumes. It stops "writer" containers like Caddy and n8n before archiving to ensure data consistency.
Sources: docker-compose.yml:164-171, scripts/wait-healthy.sh:16-52, scripts/backup.sh:64-100