Overview

Relevant source files

• README.md
• pyproject.toml

Purpose and Scope

This document provides a high-level introduction to the Simple Secrets Manager system, explaining its purpose, core features, and architectural design. It covers what the system does, how the major components are organized, and the key technologies used. For detailed setup instructions, see Getting Started. For architecture deep-dives, see Architecture. For API usage, see API Reference.

What is Simple Secrets Manager

Simple Secrets Manager is a lightweight, self-hosted secrets management system designed for teams that need organized secret storage without enterprise complexity. The system organizes secrets using a three-tier hierarchy: projects contain configs (representing environments like dev, staging, prod), and configs contain secrets (key-value pairs).

The system is delivered as a unified Docker container that includes both a web-based admin console and a REST API for programmatic access. It uses MongoDB for persistent storage and supports both human authentication (username/password) and machine authentication (scoped API tokens).

Primary use cases:

• Store application secrets organized by project and environment
• Share inherited configuration across environments with environment-specific overrides
• Access secrets via web UI for manual management or via API for CI/CD integration
• Generate scoped tokens for service-to-service authentication

Sources: README.md10-22

Key Features

Feature	Description
Hierarchical Organization	Three-tier model: projects → configs → secrets
Config Inheritance	Base configs can be inherited by environment configs with selective overrides
Dual Interface	Web-based admin console and REST API
Flexible Authentication	Username/password for humans, scoped tokens for automation
Scope-based Authorization	Fine-grained access control using permission scopes (e.g., secrets:read, projects:write)
Import/Export	Import .env files, export secrets as JSON or .env format
Audit Logging	Track all modifications to secrets and configurations
Multi-Architecture	Docker images for amd64 and arm64 (including Raspberry Pi support)
Self-Contained Deployment	Single unified container with frontend and backend

Sources: README.md16-22 README.md43-49

System Architecture

High-Level Component View

The following diagram shows the major architectural components and their relationships using actual code entity names:

Component Responsibilities:

• nginx: Serves frontend static files on port 8080 and reverse proxies /api requests to Flask backend
• server.py: Flask application entry point binding to port 5000
• api_v1 Blueprint: Defines API routes with /api prefix at Api/api.py29-30
• Access Subsystem: Handles authentication (Tokens, UserPass), authorization (is_auth.py), and system initialization (Onboarding)
• Engines Subsystem: Business logic for secrets management, project management, configuration, and audit logging
• Connection singleton: Centralized database connection management at connection.py10-31
• MongoDB Databases: secrets_manager_data for operational data, secrets_manager_auth for credentials and tokens

Sources: README.md31-33 docs/README_dockerhub.md10-14 connection.py10-31 Api/api.py29-30

Data Organization Model

The system implements a hierarchical data model with config inheritance:

Key Concepts:

• Projects: Top-level organizational units (e.g., webapp, microservice-a)
• Configs: Environment-specific configuration sets within a project (e.g., dev, staging, prod)
• Secrets: Key-value pairs stored within a specific config
• Inheritance: Configs can inherit from other configs using the inherits_from field, reducing duplication
• Override Behavior: Child configs inherit all parent secrets but can override specific keys
• Database Separation: Operational data in secrets_manager_data, authentication data in secrets_manager_auth

Sources: README.md18-19 connection.py16-31

Technology Stack

Layer	Technology	Purpose
Frontend	React + Vite	Admin console UI with hot-reload development
Web Server	Nginx	Static file serving and API reverse proxy
Backend Framework	Flask + Flask-RESTx	REST API with automatic OpenAPI documentation
Process Manager	Supervisor	Manages both Nginx and Flask processes in container
Database	MongoDB 4+	Document storage for projects, configs, secrets, and auth data
Authentication	bcrypt + HMAC-SHA256	Password hashing and token hashing
Containerization	Docker + Docker Compose	Unified deployment with multi-architecture support
CI/CD	GitHub Actions	Automated builds, quality checks, and image publishing
Python Package Manager	uv	Fast dependency resolution and virtual environment management

Sources: README.md54-59 docs/README_dockerhub.md10-14

Deployment Model

Simple Secrets Manager uses a unified container architecture where a single Docker image contains all necessary components:

Deployment Characteristics:

• Unified Image: Single image at ghcr.io/bearlike/simple-secrets-manager contains frontend, backend, and web server
• Multi-Architecture: Built for amd64 and arm64 platforms using Docker Buildx
• Port Exposure: Port 8080 (Nginx), Port 5000 (Flask API)
• External Dependency: Requires MongoDB 4+ (separate container)
• Configuration: Environment variables for database connection, token salt, CORS, and binding
• Tag Strategy: Semantic versioning (X.Y.Z, X.Y, X, latest) from CI/CD pipeline

Typical Deployment:

The recommended deployment method is Docker Compose, which orchestrates the SSM container and MongoDB container together. The configuration is defined in docker-compose.yml1-40 and starts both services with appropriate networking and volume mounts.

Sources: docs/README_dockerhub.md10-28 README.md23-33

Access Control Model

Authentication and authorization are separated concerns:

Access Control Concepts:

• Token-Based Auth: API tokens are hashed with TOKEN_SALT before storage in secrets_manager_auth.tokens
• Scope-Based Authorization: Each token carries an array of permission scopes (e.g., ["projects:read", "secrets:write"])
• Actor Context: Authenticated requests set flask.g.actor containing username, scopes, and token metadata
• Authorization Decorators: @require_token ensures authentication, @require_scope("action") enforces permissions
• First-Time Setup: Special onboarding flow allows unauthenticated registration of the first admin user

Common Scopes:

• projects:read, projects:write
• configs:read, configs:write
• secrets:read, secrets:write
• tokens:read, tokens:write, tokens:revoke
• audit:read

Sources: Access/is_auth.py1-100 Access/tokens.py1-200 Access/userpass.py1-150

Related Pages

• For initial setup and first-time usage, see Getting Started
• For detailed architectural patterns and design decisions, see Architecture
• For complete API endpoint documentation, see API Reference
• For deployment options and configuration, see Deployment
• For contribution guidelines and development environment, see Development Guide
• For environment variable reference, see Configuration Reference

Sources: README.md1-168 docs/README_dockerhub.md1-83