stack.basicstack.de/apps/pangolin/pangolin-paperclip-configuration-guide-community.md

# Pangolin Community Edition: Configuration Guide for paperclip.basicstack.de

**Task:** DEV-400 - Configure access policy and routing for paperclip.basicstack.de  
**Edition:** Community Edition (Self-Hosted)  
**Date:** 2026-08-02

## Overview

This guide provides step-by-step instructions for configuring Pangolin Community Edition to protect paperclip.basicstack.de with authentication and routing. The Community Edition has some limitations compared to Enterprise Edition, so this guide focuses on features available in the free tier.

## Community Edition Limitations

The following features mentioned in the original guide are **Enterprise-only** and will appear locked in your UI ([source](https://docs.pangolin.net/self-host/enterprise-edition)):

- ❌ **Global/Shared Resource Policies** - Enterprise only
- ❌ **Advanced RBAC with multiple roles** - Enterprise only  
- ❌ **External identity providers for user management** - Enterprise only
- ❌ **Multi-organization support** - Enterprise only
- ❌ **Health checks** - May be Enterprise only
- ❌ **Geoblocking** - May be Enterprise only

## What Community Edition CAN Do

✅ **Basic authentication** via username/password  
✅ **OIDC authentication** (already configured with Pocket-ID)  
✅ **Resource-level access control** (per-resource settings)  
✅ **HTTP/HTTPS reverse proxy** with automatic TLS  
✅ **Basic routing and path matching**

## Architecture Overview

1. **Pangolin UI**: Central management interface for defining protected resources
2. **Pangolin API**: Provides Traefik configuration endpoint at `/api/v1/traefik-config`
3. **Pangolin Controller**: Kubernetes controller that polls the API and creates/updates Traefik CRDs
4. **Traefik**: Ingress controller that enforces the routing and authentication rules

**Flow**: UI Configuration → Pangolin API → Controller → Traefik CRDs → Enforced Access

---

## Prerequisites

- Pangolin Community Edition is deployed and accessible at https://pangolin.basicstack.de
- OIDC authentication with Pocket-ID is already configured (working)
- You have admin access via local admin account or SSO
- The Pangolin Kubernetes Controller is deployed

---

## Step 1: Access Pangolin Admin UI

1. Open your browser and navigate to: **https://pangolin.basicstack.de**
2. If you see enterprise-locked features in the UI (grayed out or with lock icons), you can ignore them
3. Sign in using one of these methods:
   - **SSO**: Click "Sign in with OIDC" or similar (uses Pocket-ID)
   - **Local Admin**: Use the admin username and password if SSO is not working

---

## Step 2: Create HTTP Resource for paperclip.basicstack.de

In Community Edition, we skip the separate "Policy" creation step and configure access control directly on the resource.

### 2.1 Navigate to Resources

1. In the Pangolin UI, find the navigation menu
2. Look for one of these sections:
   - **"Resources"**
   - **"HTTP Resources"** 
   - **"Services"**
   - **"Proxies"**
3. Click the **"Add"**, **"Create"**, or **"New Resource"** button

### 2.2 Basic Resource Configuration

Fill in the resource creation form with these values:

**Name/Label:** `Paperclip` (or `paperclip-basicstack-de`)

**Resource Type:**
- Select **"HTTP"** or **"HTTPS"** 
- Some UIs may show this as "Public HTTP Resource" or "Reverse Proxy"

**Domain/Hostname:**
- **Domain:** `paperclip.basicstack.de`
- This must match exactly
- If there's a dropdown for base domain, select `basicstack.de` first

**Description:** (Optional)  
`Paperclip task management and orchestration platform`

### 2.3 Backend/Target Configuration

This section defines where traffic should be forwarded after authentication:

**Target Type:** `Kubernetes Service` or `HTTP/HTTPS URL`

**Backend URL/Endpoint:**
- If using Kubernetes Service mode:
  - **Service Name:** `paperclip` (or the actual service name)
  - **Namespace:** `paperclip` (or the actual namespace)
  - **Port:** `80` or `3000` (whatever port the Paperclip service uses)
  
- If using HTTP URL mode:
  - **URL:** `http://paperclip.paperclip.svc.cluster.local` (adjust namespace/service name)
  - Or use the cluster IP if known: `http://10.x.x.x:port`

**Path Configuration:**
- **Match Path:** `/` (matches all paths - root and everything under it)
- **Strip Prefix:** Unchecked/No (preserve the full path)

> **Note:** You'll need to know the correct Kubernetes service name and namespace for Paperclip. If you're unsure, check with the cluster admin or look for the service definition in the Kubernetes manifests.

### 2.4 SSL/TLS Settings

**TLS/HTTPS:**
- ✅ **Enable TLS/SSL**
- ✅ **Force HTTPS redirect** (redirect HTTP → HTTPS automatically)
- **Certificate Provider:** Let's Encrypt (should be auto-configured)

The certificate will be issued automatically via Let's Encrypt after you save the resource.

### 2.5 Authentication Settings (Community Edition)

Since Community Edition doesn't support separate policy objects, authentication is configured directly on the resource:

**Authentication Required:** ✅ **Yes/Enabled**

**Authentication Method:** 
- Select **"SSO"** or **"OIDC"** (uses the Pocket-ID integration already configured)
- If you see a dropdown, it may show "Pocket ID" or "Default OIDC Provider"

**Access Control** (if available):
- **Allowed Users:** You may be able to add individual user emails:
  - `andreas.leinen@basicstack.de`
  - `admin@basicstack.de`
  - Add any other users who should have access
  
- **Allowed Groups:** If the UI supports groups in Community Edition:
  - Add group: `pangolin-admins` (if supported)
  - This may not work in Community Edition - focus on individual users instead

**Session/Cookie Settings** (if available):
- **Session Duration:** 24 hours (or whatever the default is)
- **Require Re-authentication:** Not required

> **Community Edition Limitation:** If you cannot assign groups or create complex access rules, you'll need to add each authorized user individually by email. This is a limitation of the free tier.

### 2.6 Optional Settings

**Site Selection:** (if prompted)
- Select the default site or your cluster name
- Usually this is automatic

**Labels/Tags:** (optional)
- Add labels for organization if the UI supports it
- Example: `environment:production`, `team:engineering`

### 2.7 Save the Resource

1. Review all settings
2. Click **"Create"**, **"Save"**, or **"Add Resource"**
3. Wait for the success confirmation message
4. The resource should appear in your resources list

---

## Step 3: Verify Resource Configuration

### 3.1 Check Resource Status in Pangolin UI

1. Go back to the **Resources** list
2. Find the **Paperclip** resource
3. Check for these indicators:
   - **Status:** Should show as Active, Running, or Online (often a green dot/badge)
   - **Domain:** `paperclip.basicstack.de`
   - **SSL:** Certificate status (may show "Pending" initially, then "Valid" after 1-2 minutes)
   - **Authentication:** Should show as Protected or SSO-enabled

### 3.2 View Resource Details

1. Click on the Paperclip resource to open its detail view
2. Verify:
   - Authentication is enabled
   - Target/backend URL is correct
   - TLS is enabled
   - The resource is active

---

## Step 4: Verify Kubernetes CRDs (Controller Output)

After saving the resource in Pangolin, the Kubernetes Controller should automatically create Traefik CRDs within 1-5 minutes (depending on the controller's poll interval).

**Expected Resources in Kubernetes:**

These should appear in the `pangolin` namespace (or wherever the controller creates them):

```bash
# Check for IngressRoute
kubectl get ingressroute -A | grep paperclip

# Check for Middleware (handles authentication)
kubectl get middleware -A | grep paperclip

# Optional: Check TraefikService
kubectl get traefikservice -A | grep paperclip
```

**What to expect:**
- **IngressRoute** named something like `paperclip-basicstack-de` or `pangolin-paperclip`
- **Middleware** for authentication, named like `paperclip-auth` or `pangolin-paperclip-auth`

If these don't appear after 5-10 minutes, check the controller logs:

```bash
kubectl logs -n pangolin -l app=pangolin-controller --tail=100
```

---

## Step 5: Test Access

### 5.1 Test Unauthenticated Access

1. Open an **incognito/private browser window** (to ensure no cached sessions)
2. Navigate to: **https://paperclip.basicstack.de**
3. **Expected behavior:**
   - You should be redirected to a login page
   - Either Pocket-ID (https://auth.basicstack.de) or Pangolin's own login page
   - You should NOT see the Paperclip application without logging in

### 5.2 Test Authenticated Access

1. In the same incognito window, log in with an authorized account:
   - Email: `andreas.leinen@basicstack.de` (or other authorized user)
   - Use your Pocket-ID password
2. After successful authentication:
   - You should be redirected back to https://paperclip.basicstack.de
   - The Paperclip application should load
   - You should NOT see any "Access Denied" errors

### 5.3 Test Unauthorized User (if possible)

1. Use a Pocket-ID account that is **not** in the allowed users list
2. Try to access https://paperclip.basicstack.de
3. **Expected behavior:**
   - Authentication to Pocket-ID succeeds (user can log in)
   - But Pangolin denies access (403 Forbidden or similar)

> **Note:** This test only works if you have another Pocket-ID user account available. If you only added specific users, anyone else should be blocked.

---

## Step 6: Confirm DNS and Network Path

If you can't access the site at all (not even a redirect):

1. **Check DNS:**
   ```bash
   dig paperclip.basicstack.de
   nslookup paperclip.basicstack.de
   ```
   Should resolve to your cluster's ingress IP

2. **Check Traefik routing:**
   ```bash
   kubectl get ingress -A | grep paperclip
   kubectl get ingressroute -A | grep paperclip
   ```

3. **Check TLS certificate:**
   ```bash
   kubectl get certificate -A | grep paperclip
   ```
   Should show Ready=True after a few minutes

---

## Troubleshooting

### Issue: Cannot create resource - "Shared policy required" or similar error

**Solution:** This is an enterprise feature warning. In Community Edition:
- Do NOT try to create a shared/global policy
- Configure authentication directly on the resource itself
- Add individual users instead of groups if group support is locked

### Issue: "External identity provider" option is grayed out

**Solution:** This is expected in Community Edition. However:
- OIDC authentication via environment variables (already configured) still works
- You can use the OIDC provider that's already set up at the application level
- You just can't manage multiple IDPs or switch providers via the UI

### Issue: Resource created but no Kubernetes CRDs appear

**Solution:**
1. Check controller status:
   ```bash
   kubectl get pods -n pangolin -l app=pangolin-controller
   kubectl logs -n pangolin -l app=pangolin-controller
   ```
2. Verify controller configuration in the ConfigMap:
   ```bash
   kubectl get configmap -n pangolin pangolin-controller-config -o yaml
   ```
3. Ensure the controller can reach the Pangolin API:
   - Check network policies
   - Verify the API endpoint URL in controller config
4. Check RBAC permissions:
   ```bash
   kubectl get serviceaccount,role,rolebinding -n pangolin | grep controller
   ```

### Issue: SSL certificate not issuing

**Solution:**
- Wait 2-5 minutes - Let's Encrypt can be slow
- Check cert-manager logs if you're using it
- Verify DNS is resolving correctly
- Check if there's a rate limit issue (Let's Encrypt has daily limits)

### Issue: Authentication loop (keeps redirecting to login)

**Solution:**
- Check browser cookies - clear cookies for `pangolin.basicstack.de` and `auth.basicstack.de`
- Verify the OIDC callback URL is correct: `https://pangolin.basicstack.de/auth/callback`
- Check Pangolin logs for OIDC errors:
  ```bash
  kubectl logs -n pangolin -l app=pangolin
  ```
- Verify the OIDC client ID and secret are correct in Pocket-ID

### Issue: 403 Forbidden for all users (even authorized ones)

**Solution:**
- Check the allowed users list on the resource
- Verify the email address format matches exactly
- Try adding the user's email again (UI bug workaround)
- Check if there's an IP allowlist blocking you
- Review Pangolin logs for authorization errors

---

## Health Check Criteria (Task DEV-400)

✅ **Access control configured for paperclip.basicstack.de:**
- Resource created with authentication enabled
- Authorized users specified (or group, if supported)

✅ **Routing configured:**
- HTTP resource points to correct backend
- TLS enabled with automatic certificate
- Path matching set to root (`/`)

✅ **Traefik CRDs generated:**
- IngressRoute created by controller
- Middleware created for authentication
- Resources visible in Kubernetes

---

## Community Edition Workarounds

Since you're running Community Edition, here are some workarounds for enterprise features:

### Group-based Access Control
- **Enterprise:** Assign `pangolin-admins` group to policy
- **Community Workaround:** Add each user's email individually to the resource
- **Better Solution:** Consider upgrading to Enterprise (free for businesses < $100K revenue) ([source](https://linuxiac.com/pangolin-reverse-proxy-moves-to-dual-licensing-with-new-enterprise-edition/))

### Hide Enterprise UI Elements
If the locked enterprise features are cluttering your UI, you can hide them:

1. Edit the Pangolin ConfigMap:
   ```bash
   kubectl edit configmap -n pangolin pangolin-config
   ```

2. Add this to the `config.yml` section:
   ```yaml
   flags:
     disable_enterprise_features: true
   ```

3. Restart Pangolin:
   ```bash
   kubectl rollout restart deployment -n pangolin pangolin
   ```

This will hide enterprise-only features from the UI entirely ([source](https://darkwebinformer.com/pangolin-the-self-hosted-tunneled-reverse-proxy-thats-quietly-replacing-cloudflare-tunnels/)).

---

## Upgrading to Enterprise Edition (Optional)

If you need the locked features, Enterprise Edition is free for:
- Personal and hobbyist use
- Businesses making less than $100K USD gross annual revenue

**To upgrade:**

1. Update the image in your deployment:
   ```yaml
   image: fosrl/pangolin:ee-latest  # instead of fosrl/pangolin:1.21.1
   ```

2. Apply the change and restart

3. Access the admin panel at `/admin/license`

4. Enter your license key (free tier available)

This unlocks:
- External identity providers and advanced RBAC
- Multi-organization support and custom branding  
- Shared/global policies
- Enhanced monitoring and SIEM streaming
- Priority support

More info: [Pangolin Enterprise Edition Docs](https://docs.pangolin.net/self-host/enterprise-edition)

---

## Next Steps

Once configuration is complete:

1. ✅ Verify the resource appears in Pangolin UI
2. ✅ Confirm Kubernetes CRDs were created by the controller
3. ✅ Test unauthenticated access (should redirect to login)
4. ✅ Test authenticated access (should reach Paperclip app)
5. ✅ Mark DEV-400 as complete with verification notes
6. 📝 Document any UI differences or issues encountered
7. 📊 Monitor logs for authentication/routing errors during initial rollout

---

## Additional Resources

- **Pangolin Community vs Enterprise:** [LinuxIAC Article](https://linuxiac.com/pangolin-reverse-proxy-moves-to-dual-licensing-with-new-enterprise-edition/)
- **Pangolin Documentation:** [docs.pangolin.net](https://docs.pangolin.net/)
- **Pangolin GitHub:** [github.com/fosrl/pangolin](https://github.com/fosrl/pangolin)
- **Pocket-ID Integration:** [pocket-id.org/docs/client-examples/pangolin](https://pocket-id.org/docs/client-examples/pangolin)

---

## Notes for CTO

- The exact UI layout may vary - version 1.21.1 is deployed
- Community Edition limitations are well-documented but may change in future releases
- If the CEO encounters UI elements not described here, look for conceptually similar options
- Screenshots or specific UI questions can be addressed in DEV-400 comments
- **IMPORTANT:** Do not reconfigure OIDC/SSO settings - the Pocket-ID integration is already working

---

**Last Updated:** 2026-08-02  
**For:** DEV-400 - Pangolin Community Edition Configuration