PeerMeshCore's runtime foundation for self-hosted applications. Clone it, configure it, deploy it.
A production-grade PeerMeshCore runtime foundation. This repository provides:
- Battle-tested Docker Compose configurations for common deployment patterns
- A foundation runtime stack (not a single app container) that other module containers layer onto
- Traefik reverse proxy with automatic TLS certificate management
- Docker secrets-based credential management
- Resource-based profiles (lite/core/full) for different deployment targets
- Database profiles (PostgreSQL, MySQL, MongoDB, Redis) as composable modules
- Healthcheck-based startup ordering for reliable deployments
- Network isolation patterns for security
This is infrastructure boilerplate for PeerMeshCore – clone it and layer your own modules on top.
This repository is the PeerMeshCore public boundary, exposed at https://github.com/peermesh/core. It hosts the public documentation, automation, and runtime assets, so follow the canonical quick-start guide in docs/QUICKSTART.md whenever you need public install or onboarding instructions.
PeerMeshCore Core uses a two-layer model:
- OpenTofu provisions infrastructure through provider APIs (for example, Hetzner VPS + DNS prerequisites).
- Core deploys and operates the runtime foundation and modules on that infrastructure.
This means:
- OpenTofu is the infrastructure control plane.
- Core is the runtime/container control plane.
- Modules are layered onto the foundation after the base runtime is up.
- OpenTofu providers are API connectors used during plan/apply, not always-on autoscaling agents.
See OpenTofu Deployment Model for the full walkthrough and options. See Enterprise Version Immutability Standard for dependency pinning and upgrade controls.
Core is designed to be forked. The recommended way to build on Core is the fork + upstream remote pattern: fork this repo into your own, add your modules, and periodically merge upstream improvements.
# Fork peermesh/core on GitHub, then:
git clone https://github.com/YOUR-ORG/your-project-deploy.git
cd your-project-deploy
git remote add upstream https://github.com/peermesh/core.git
cp .env.example .env && ./scripts/generate-secrets.sh
./launch_pm-core.sh module create my-appSee Deployment Repo Pattern for the complete step-by-step guide, conflict avoidance rules, and a real-world example (peers.social).
- Not app-specific automation - You bring your own application containers
- Not magic - You still need to understand Docker, networking, and your application requirements
- Not a one-size-fits-all solution - Some configurations will need adjustment for your use case
- Not a managed service - You are responsible for updates, backups, and monitoring
The canonical public install path is maintained in docs/QUICKSTART.md. That guide walks through cloning https://github.com/peermesh/core.git, configuring your .env, generating secrets, and starting the foundation services so you can treat it as the single source of truth for onboarding the core public repository.
# Clone the repository
git clone https://github.com/peermesh/core.git
cd core
# Initialize configuration
./launch_pm-core.sh config init
# Start services
./launch_pm-core.sh up --profile=postgresql,redis
# Check status
./launch_pm-core.sh statusYour PeerMeshCore runtime is now running with Traefik reverse proxy at ports 80/443.
The launch_pm-core.sh script is the PeerMeshCore CLI and provides a single entry point for all deployment operations:
# Interactive menu (run without arguments)
./launch_pm-core.sh
# Direct commands
./launch_pm-core.sh status # Show deployment status
./launch_pm-core.sh up --profile=redis # Start with specific profiles
./launch_pm-core.sh down # Stop services
./launch_pm-core.sh logs traefik -f # Follow service logs
./launch_pm-core.sh health -v # Run health checks
./launch_pm-core.sh deploy --target=prod # Deploy to production
./launch_pm-core.sh backup run # Run backup
./launch_pm-core.sh module list # List available modules
./launch_pm-core.sh config validate # Validate configuration# Help
./launch_pm-core.sh --helpSee CLI Documentation for complete usage.
- Reverse Proxy (Traefik) - Automatic HTTPS via Let's Encrypt, request routing
- Authentication (Authelia) - Single sign-on, 2FA support
- Databases - PostgreSQL, MySQL, MongoDB profiles ready to use
- Caching (Redis) - Session storage, application caching
- Object Storage (MinIO) - S3-compatible file storage
- Automated Backups - Scheduled database dumps with retention policies
- Security Hardening - Non-root containers, network isolation, secret management
Select the resource profile matching your deployment environment:
| Profile | RAM | CPU | Use Case |
|---|---|---|---|
lite | 512MB | 0.5 | CI/CD, testing, development laptops |
core | 2GB | 2 | Development servers, staging |
full | 8GB | 4 | Production with monitoring stack |
Activate a profile:
docker compose --profile core up -dAdd database and infrastructure services as needed:
| Profile | Purpose |
|---|---|
postgresql | Relational database with pgvector support |
mysql | Traditional web application database |
mongodb | Document database for NoSQL workloads |
redis | Caching, sessions, pub/sub |
minio | S3-compatible object storage |
Include a profile:
docker compose -f docker-compose.yml \
-f profiles/postgresql/docker-compose.postgresql.yml \
up -dReady-to-deploy application configurations:
| Application | Description | Profiles Used |
|---|---|---|
| Ghost | Publishing platform | MySQL |
| LibreChat | AI chat interface | MongoDB, PostgreSQL |
| Matrix | Federated messaging | PostgreSQL |
| WordPress | CMS/blog platform | MySQL |
| Python API (HTTPBin) | API workload baseline | Foundation |
See examples/ for complete configurations.
- Deployment Repo Pattern - Fork + upstream remote setup for your project
- Quick Start Guide - Get running in 5 minutes
- Public Quick Start Tutorial - Public onboarding walkthrough
- System Architecture - Four-tier modular architecture overview
- Configuration Reference - Environment variables and options
- Profiles Guide - Choosing and customizing profiles
- Security Guide - Security architecture and hardening
- OpenBao No-TPM Fallback Strategy - Fail-closed fallback tiers for unseal workflows
- Secrets Management - Docker secrets patterns
- Deployment Guide - Production deployment guidance
- Enterprise Version Immutability Standard - Mandatory version pinning and digest policy
- Image Digest Baseline - Current locked image references
- OpenTofu Deployment Model - Infra via API + runtime on-host model
- Troubleshooting - Common issues and solutions
- Gotchas - High-friction deployment pitfalls and fixes
- Secrets Per App - Required keys per example app
- Multi-Domain Pattern - Domain override strategy and usage
- Public Repo Manifest - Public/private file boundaries
- Architecture Decisions - ADR documentation
- Foundation Reference - Module system documentation
- Launch Strategy - Public launch sequencing and channels
- Community Engagement Plan - SLA and triage model
- Good First Issues Backlog - New-contributor task queue
- Demo Materials - Screenshot + onboarding walkthrough set
- Docker Engine 24.0+
- Docker Compose 2.20+
- 2GB RAM minimum (4GB+ recommended)
- Linux, macOS, or Windows with WSL2
See CONTRIBUTING.md for development setup, validation commands, and secrets safety requirements.
Original source code and documentation in this repository are licensed under the PolyForm Noncommercial License 1.0.0 (LICENSE). See COPYRIGHT, COMMERCIAL-LICENSE.md for commercial use, THIRD_PARTY_NOTICES.md for third-party components, and DEPENDENCY-LICENSE-POLICY.md for how project and dependency licenses interact.
Third-party components (including container images, libraries, and upstream applications) remain under their respective licenses; the project license does not replace them.