rick-infra/README.md

# 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

```bash
# 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

```bash
# 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](docs/setup-guide.md)** - Initial VPS and Ansible configuration
- **[Deployment Guide](docs/deployment-guide.md)** - Complete infrastructure deployment
- **[Authentik Deployment Guide](docs/authentik-deployment-guide.md)** - Authentication server setup

### 🏗️ **Architecture & Decisions**
- **[Architecture Decisions](docs/architecture-decisions.md)** - Technical choices and rationale
- **[Authentication Architecture](docs/authentication-architecture.md)** - SSO strategy and patterns
- **[Security Hardening](docs/security-hardening.md)** - Multi-layer security implementation

### 🔧 **Development & Integration**
- **[Service Integration Guide](docs/service-integration-guide.md)** - Adding new services
- **[Caddy Configuration](docs/caddy-service-configuration.md)** - Reverse proxy patterns

### 📚 **Service Documentation**
- **[Authentik Role](roles/authentik/README.md)** - Authentication service
- **[PostgreSQL Role](roles/postgresql/README.md)** - Database service  
- **[Valkey Role](roles/valkey/README.md)** - Cache service
- **[Caddy Role](roles/caddy/README.md)** - 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](docs/service-integration-guide.md) 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](LICENSE) file for details.

## Support

For issues, questions, or contributions:
- **Issues**: [GitHub Issues](https://github.com/your-username/rick-infra/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.