rick-infra

Infrastructure as Code for secure, high-performance web services with native databases, Unix socket IPC, and centralized authentication.

Architecture Overview

Rick-infra implements a security-first infrastructure stack featuring:

• 🔒 Native Infrastructure: PostgreSQL, Valkey, Caddy managed by systemd for optimal performance
• 🚀 Container Applications: Rootless Podman with systemd integration for secure application deployment
• 🔐 Centralized Authentication: Authentik SSO with forward auth integration
• 🔌 Unix Socket IPC: Zero network exposure for database and cache communication
• 🛡️ Defense in Depth: Multi-layer security from network to application level

┌─────────────────────────────────────────────────────────────┐
│ rick-infra Security-First Architecture                     │
│                                                             │
│ ┌─────────────────┐  ┌─────────────────┐  ┌───────────────┐ │
│ │  Applications   │  │ Authentication  │  │ Reverse Proxy │ │
│ │ (Podman/systemd)│  │  (Authentik)    │  │ (Caddy/HTTPS) │ │
│ └─────────────────┘  └─────────────────┘  └───────────────┘ │
│           │                    │                    │       │
│           └────────────────────┼────────────────────┘       │
│                    ┌───────────┼───────────┐                │
│ ┌─────────────────┐│  ┌─────────▼────────┐  │┌──────────────┐│
│ │   PostgreSQL    ││  │      Valkey      │  ││    Podman    ││
│ │ (Native/systemd)││  │ (Native/systemd) │  ││(Containers)  ││
│ │  Unix Sockets   ││  │   Unix Sockets   │  ││  Rootless    ││
│ └─────────────────┘│  └──────────────────┘  │└──────────────┘│
│                    └─────────────────────────┘                │
└─────────────────────────────────────────────────────────────┘

Infrastructure Environments

Rick-infra manages two separate environments:

🏠 Homelab (arch-vps)

Personal services and experimentation at jnss.me:

• PostgreSQL, Valkey, Podman infrastructure
• Authentik SSO (auth.jnss.me)
• Nextcloud (cloud.jnss.me)
• Gitea (git.jnss.me)

🚀 Production (mini-vps)

Client projects requiring high uptime:

• Sigvild Gallery (sigvild.no, api.sigvild.no)
• Minimal infrastructure footprint

Quick Start

Prerequisites

• VPS: Fresh Arch Linux VPS with root access
• DNS: Domains pointed to VPS IP addresses
• SSH: Key-based authentication configured

Deploy Infrastructure

# 1. Clone repository
git clone https://github.com/your-username/rick-infra.git
cd rick-infra

# 2. Configure inventory (already set up)
# inventory/hosts.yml defines homelab and production groups

# 3. Set up vault variables
ansible-vault edit group_vars/production/vault.yml   # Production secrets
ansible-vault edit host_vars/arch-vps/vault.yml      # Homelab secrets

# 4. Deploy to specific environment
ansible-playbook playbooks/homelab.yml      # Deploy homelab
ansible-playbook playbooks/production.yml   # Deploy production
ansible-playbook site.yml                   # Deploy both

Deployment times:

• Homelab (full stack): 8-14 minutes
• Production (minimal): 3-5 minutes

Verify Deployment

# Check homelab services
curl -I https://auth.jnss.me/     # Authentik SSO
curl -I https://cloud.jnss.me/    # Nextcloud
ansible homelab -a "systemctl status postgresql valkey caddy"

# Check production services
curl -I https://sigvild.no/       # Sigvild Gallery
ansible production -a "systemctl status sigvild-gallery caddy"

Key Features

🔒 Security First

• Native Database Services: No container attack vectors for critical infrastructure
• Unix Socket IPC: Zero network exposure for database/cache communication
• Rootless Containers: All applications run unprivileged
• Centralized Authentication: SSO with MFA support via Authentik
• Defense in Depth: Network, container, database, and application security layers

⚡ High Performance

• Native Database Performance: No container overhead for PostgreSQL/Valkey
• Unix Socket Communication: 20-40% faster than TCP for local IPC
• Optimized Container Runtime: Podman with minimal overhead
• CDN-Ready: Automatic HTTPS with Cloudflare integration

🛠️ Operational Excellence

• Infrastructure as Code: Complete Ansible automation
• systemd Integration: Native service management and monitoring
• Comprehensive Monitoring: Centralized logging and metrics
• Automated Backups: Database and configuration backup procedures

Documentation

📖 Getting Started

• Setup Guide - Initial VPS and Ansible configuration
• Deployment Guide - Complete infrastructure deployment
• Authentik Deployment Guide - Authentication server setup

🏗️ Architecture & Decisions

• Architecture Decisions - Technical choices and rationale
• Authentication Architecture - SSO strategy and patterns
• Security Hardening - Multi-layer security implementation

🔧 Development & Integration

• Service Integration Guide - Adding new services
• Caddy Configuration - Reverse proxy patterns

📚 Service Documentation

• Authentik Role - Authentication service
• PostgreSQL Role - Database service
• Valkey Role - Cache service
• Caddy Role - Reverse proxy service

Core Services

Homelab Services (arch-vps)

Infrastructure (Native systemd):

• PostgreSQL - High-performance database with Unix socket support
• Valkey - Redis-compatible cache with Unix socket support
• Caddy - Automatic HTTPS reverse proxy with Cloudflare DNS
• Podman - Rootless container runtime with systemd integration

Authentication:

• Authentik - Modern SSO server with OAuth2/OIDC/SAML support
• Forward Auth - Transparent service protection via Caddy

Applications (Containerized):

• Nextcloud - Personal cloud storage and file sync
• Gitea - Self-hosted Git service with SSO integration

Production Services (mini-vps)

Infrastructure:

• Caddy - Automatic HTTPS reverse proxy with Cloudflare DNS

Applications:

• Sigvild Gallery - Wedding photo gallery with PocketBase API
  • Frontend: SvelteKit static site
  • Backend: Go + SQLite (PocketBase)
  • Domains: sigvild.no, api.sigvild.no

Architecture Benefits

Why Native Databases?

Performance: Native PostgreSQL delivers 15-25% better performance than containerized alternatives

Security: Unix sockets eliminate network attack surface for database access

Operations: Standard system tools and procedures for backup, monitoring, maintenance

Reliability: systemd service management with proven restart and recovery mechanisms

Why Unix Socket IPC?

Security: No network exposure - access controlled by filesystem permissions

Performance: Lower latency and higher throughput than TCP communication

Simplicity: No network configuration, port management, or firewall rules

Why Rootless Containers?

Security: No privileged daemon, reduced attack surface

Isolation: Process isolation without compromising host security

Integration: Native systemd service management for containers

Contributing

Development Workflow

1. Fork the repository
2. Create feature branch: git checkout -b feature/new-service
3. Follow role template: Use existing roles as templates
4. Test deployment: Verify on development environment
5. Update documentation: Add service documentation
6. Submit pull request: Include deployment testing results

Adding New Services

See the Service Integration Guide for complete instructions on adding new services to rick-infra.

Security Considerations

All contributions must follow the security-first principles:

• Services must integrate with Authentik authentication
• Database access must use Unix sockets only
• Containers must run rootless with minimal privileges
• All secrets must use Ansible Vault

License

MIT License - see LICENSE file for details.

Support

For issues, questions, or contributions:

• Issues: GitHub Issues
• Documentation: All guides linked above
• Security: Follow responsible disclosure for security issues

---

rick-infra - Infrastructure as Code that prioritizes security, performance, and operational excellence.