pal-enterprises

Business hub and identity platform for Pal Enterprises, serving as the web presence, client portal, and SSO backbone for the broader Pal Enterprises ecosystem.

Live URL: pal-enterprises.tail5b443a.ts.net

---

What This Is

pal-enterprises is the web layer of a two-surface product:

Surface	Repo	Purpose
Pal Enterprises (this repo)	pal-enterprises	Business hub, client portal, lead gen

Email is the universal identifier. A user provisioned here can authenticate across all client surfaces via Keycloak SSO.

---

Stack

Layer	Technology
Framework	Ruby on Rails 8.1
Ruby	3.4
Frontend	Hotwire (Turbo + Stimulus), plain CSS
Database	PostgreSQL (CNPG on pal-e cluster)
Auth	Keycloak OIDC (pal-enterprises realm)
CI	Woodpecker (test + kaniko build)
Hosting	k3s via Kustomize + ArgoCD

---

Architecture Overview

pal-enterprises.tail5b443a.ts.net
│
├── /                  → Public landing page
├── /contacts/new      → Lead gen form
├── /login             → Keycloak-backed email + password auth
├── /dashboard         → Authenticated client portal (role-aware)
└── /up                → Health check

Auth flow:

1. User visits /login
2. Rails delegates to Keycloak via omniauth-openid-connect (OIDC)
3. Keycloak issues tokens, Rails establishes a session
4. Roles (owner, client, lead) gate what each user sees in the dashboard

Lead gen flow:

1. Visitor fills out form on /contacts/new
2. Rails writes a lead record to Postgres
3. Owner promotes to client (admin UI planned)

---

User Types

Role	Access	Provisioned By
owner	Full admin, all dashboards	Manual seed
client	Their own dashboard and tools	Owner promotes from lead
lead	None (DB record only)	Form submission

---

Seeded Users

The following users are created in the initial DB seed and Keycloak realm:

• draneylucas@gmail.com -- client
• westsidebasketball@gmail.com -- client

---

Local Development

Prerequisites

• Ruby 3.4+
• PostgreSQL (or access to the CNPG cluster)
• Keycloak (or access to keycloak.tail5b443a.ts.net)

Setup

# Clone
git clone https://forgejo.tail5b443a.ts.net/ldraney/pal-enterprises.git
cd pal-enterprises

# Install dependencies
bundle install

# Setup database
bin/rails db:prepare

# Start dev server
bin/dev

Environment Variables

# Database
POSTGRES_USER=ldraney
POSTGRES_PASSWORD=<from k8s secret>
POSTGRES_HOST=pal-e-postgres-rw.postgres.svc.cluster.local

# Keycloak OIDC
KEYCLOAK_URL=https://keycloak.tail5b443a.ts.net
KEYCLOAK_REALM=pal-enterprises
KEYCLOAK_CLIENT_ID=pal-enterprises
KEYCLOAK_CLIENT_SECRET=<from Keycloak admin>

---

Project Structure

pal-enterprises/
├── app/
│   ├── controllers/
│   │   ├── pages_controller.rb        (landing page)
│   │   ├── contacts_controller.rb     (lead gen form)
│   │   ├── sessions_controller.rb     (Keycloak login/logout/callback)
│   │   └── dashboard_controller.rb    (authenticated portal)
│   ├── models/
│   │   └── lead.rb
│   └── views/
│       ├── pages/home.html.erb
│       ├── contacts/new.html.erb
│       ├── sessions/new.html.erb
│       └── dashboard/index.html.erb
├── config/
│   ├── database.yml
│   ├── routes.rb
│   └── initializers/
│       └── omniauth.rb
├── db/
│   ├── migrate/
│   └── seeds.rb
├── Dockerfile
├── .woodpecker.yaml
└── README.md

---

CI Pipeline

Woodpecker CI runs on every push and PR via .woodpecker.yaml:

1. test (PR + push) -- bundle-audit, brakeman, rubocop
2. build-and-push (main only) -- kaniko build to Harbor with layer caching
3. update-kustomize-tag (main only) -- bumps image tag in pal-e-deployments for ArgoCD sync

Roadmap

• Define auth model and user roles
• Rails scaffold + landing page + health check
• Keycloak OIDC integration (omniauth-openid-connect)
• Plain CSS design system
• Arch Linux base image + Dockerfile migration
• Woodpecker CI with test gates + kaniko build
• Kustomize overlay + ArgoCD deployment
• Contact form + calendar redirect
• Authenticated dashboard with tool grid
• Admin UI for user/lead management
• Client board view (read-only project board proxy)